1asimagexml(1) AfterStep X11 window manager asimagexml(1)
2
6 asimagexml - XML schema to be used for scripting image manipulation by
7 AfterStep and ascompose libAfterImage/asimagexml
8
10 is a tool to compose image(s) and display/save it based on supplied XML
11 input file.
12
15 ascompose reads supplied XML data, and manipulates image accordingly.
16 It could transform images from files of any supported file format,
17 draw gradients, render antialiased texturized text, perform
18 superimposition of arbitrary number of images, and save images into
19 files of any of supported output file formats.
20 At any point, the result of any operation could be assigned a name,
22 and later on referenced under this name.
23 At any point during the script processing, result of any operation
25 could be saved into a file of any supported file types.
26 Internal image format is 32bit ARGB with 8bit per channel.
28 Last image referenced, will be displayed in X window, unless -n option
30 is specified. If -r option is specified, then this image will be
31 displayed in root window of X display, effectively setting a background
32 for a desktop. If -o option is specified, this image will also be
33 saved into the file or requested type.
34
36 Here is the list and description of possible XML tags to use in the
37 script :
38 img - load image from the file.
39 recall - recall previously loaded/generated image by its name.
40 text - render text string into new image.
41 save - save an image into the file.
42 bevel - draw solid bevel frame around the image.
43 gradient - render multipoint gradient.
44 mirror - create mirror copy of an image.
45 blur - perform gaussian blur on an image.
46 rotate - rotate/flip image in 90 degree increments.
47 scale - scale an image to arbitrary size.
48 slice - enlarge image to arbitrary size leaving corners unchanged.
49 crop - crop an image to arbitrary size.
50 tile - tile an image to arbitrary size.
51 hsv - adjust Hue, Saturation and Value of an image.
52 pad - pad image with solid color from either or all sides.
53 solid - generate new image of requested size, filled with solid
54 color.
55 composite - superimpose arbitrary number of images using one of 15
56 available methods.
57 if - conditional processing based on value of the variables
58 set - sets value of the variable
59 printf - formated printing of the value of the variable
60 Each tag generates new image as the result of the transformation -
62 existing images are never modified and could be reused as many times
63 as needed. See below for description of each tag.
64 Whenever numerical values are involved, the basic math ops (add,
66 subtract, multiply, divide), unary minus, and parentheses are
67 supported.
68 Operator precedence is NOT supported. Percentages are allowed, and
70 apply to either width or height of the appropriate image (usually
71 the refid image).
72 Also, variables of the form $image.width and $image.height are
74 supported. $image.width is the width of the image with refid "image",
75 and $image.height is the height of the same image. The special
76 $xroot.width and $xroot.height values are defined by the the X root
77 window, if there is one. This allows images to be scaled to the
78 desktop size: <scale width="$xroot.width" height="$xroot.height">.
79 Each tag is only allowed to return ONE image.
81
83 - render text string into new image, using specific font, size and tex‐
84 ture.
85
88 <text id="new_id" font="font" point="size" fgcolor="color"
89 bgcolor="color" fgimage="image_id" bgimage="image_id"
90 spacing="points">My Text Here</text>
91
93 id Optional. Image will be given this name for future reference.
94 font Optional. Default is "fixed". Font to use for text.
96 point Optional. Default is 12. Size of text in points.
98 fgcolor
100 Optional. No default. The text will be drawn in this color.
101 bgcolor
103 Optional. No default. The area behind the text will be drawn in
104 this color.
105 fgimage
107 Optional. No default. The text will be textured by this image.
108 bgimage
110 Optional. No default. The area behind the text will be filled
111 with this image.
112 spacing
114 Optional. Default 0. Extra pixels to place between each glyph.
115 type Optional. Default 0. Valid values are from 0 to 7 and each rep‐
117 reseend different 3d type.
118
121 <text> without bgcolor, fgcolor, fgimage, or bgimage will NOT
122 produce visible output by itself. See EXAMPLES below.
123
125 - superimpose arbitrary number of images on top of each other.
126
129 <composite id="new_id" op="op_desc"
130 keep-transparency="0|1" merge="0|1">
131
133 id Optional. Image will be given this name for future reference.
134 op Optional. Default is "alphablend". The compositing operation.
136 Valid values are the standard AS blending ops: add, alphablend,
137 allanon, colorize, darken, diff, dissipate, hue, lighten, over‐
138 lay, saturate, screen, sub, tint, value.
139 merge Optional. Default is "expand". Valid values are "clip" and
141 "expand". Determines whether final image will be expanded to the
142 maximum size of the layers, or clipped to the bottom layer.
143 keep-transparency
145 Optional. Default is "0". Valid values are "0" and "1". If set
146 to "1", the transparency of the bottom layer will be kept for
147 the final image.
148
151 All images surrounded by this tag will be composited with the given op.
152
154 All tags surrounded by this tag may have some of the common attributes
155 in addition to their normal ones. Under no circumstances is there a
156 conflict with the normal child attributes:
157 crefid Optional. An image ID defined with the "id" parameter for any
159 previously created image. If set, percentages in "x" and "y"
160 will be derived from the width and height of the crefid image.
161 x Optional. Default is 0. Pixel coordinate of left edge.
163 y Optional. Default is 0. Pixel coordinate of top edge.
165 align Optional. Alternative to x - allowed values are right, center
167 and left.
168 valign Optional. Alternative to y - allowed values are top, middle and
170 bottom.
171 clip_x Optional. Default is 0. X Offset on infinite surface tiled with
173 this image, from which to cut portion of an image to be used in
174 composition.
175 clip_y Optional. Default is 0. Y Offset on infinite surface tiled with
177 this image, from which to cut portion of an image to be used in
178 composition.
179 clip_width
181 Optional. Default is image width. Tile image to this width prior
182 to superimposition.
183 clip_height
185 Optional. Default is image height. Tile image to this height
186 prior to superimposition.
187 tile Optional. Default is 0. If set will cause image to be tiled
189 across entire composition, unless overridden by clip_width or
190 clip_height.
191 tint Optional. Additionally tint an image to specified color. Tinting
193 can both lighten and darken an image. Tinting color 0 or
194 #7f7f7f7f yields no tinting. Tinting can be performed on any
195 channel, including alpha channel.
196
199 libAfterImage
200
202 - load image from the file.
203
206 <img id="new_img_id" src=filename/>
207
209 id Optional. Image will be given this name for future reference.
210 src Required. The filename (NOT URL) of the image file to load.
212
215 The special image src "xroot:" will import the background image
216 of the root X window, if any. No attempt will be made to offset this
217 image to fit the location of the resulting window, if one is displayed.
218
220 - recall previously generated and named image by its id.
221
224 <recall id="new_id" srcid="image_id" default_src="filename"/>
225
227 id Optional. Image will be given this name for future reference.
228 srcid Required. An image ID defined with the "id" parameter for any
230 previously created image. libAfterImage/asimagexml/release
231
233 - release(destroy if possible) previously generated and named image by
234 its id.
235
238 <release srcid="image_id">
239
241 srcid Required. An image ID defined with the "id" parameter for any
242 previously created image. libAfterImage/asimagexml/color
243
245 - defines symbolic name for a color and set of variables.
246
249 <color name="sym_name" domain="var_domain" argb=colorvalue/>
250
252 name Symbolic name for the color value, to be used to refer to that
253 color.
254 argb 8 characters hex definition of the color or other symbolic color
256 name.
257 domain string to be used to prepend names of defined variables.
259
262 In addition to defining symbolic name for the color this tag will define
263 7 other variables : domain.sym_name.red, domain.sym_name.green,
264 domain.sym_name.blue, domain.sym_name.alpha,
265 domain.sym_name.hue, domain.sym_name.saturation,
266 domain.sym_name.value
267
269 - prints variable value to standard output.
270
273 <printf format="format_string" var="variable_name" val="expression"/>
274
276 format_string
277 Standard C format string with exactly 1 placeholder.
278 var Name of the variable, which value will be printed.
280 val math expression to be printed.
282
286 - declares variable, assigning it a numeric value of expression.
287
290 <set var="variable_name" domain="var_domain" val="expression"/>
291
293 var Name of the variable, which value will be set.
294 val math expression to be evaluated.
296 domain (optional) variable's domain to be prepended to its name using
298 format var_domain.variable_name libAfterImage/asimagexml/if
299
301 - evaluates logical expression and if result evaluates to not true(or
302 false if <unless> tag is used ), handles tags within.
303
306 <if val1="expression" [op="gt|lt|ge|le|eq|ne" val2="expression"]/>
307 [<then>...</then><else>...</else>]
308 </if>
309 <unless val1="expression" [op="gt|lt|ge|le|eq|ne" val2="expression"]/>
310
312 val1 math expression to be evaluated.
313 val2 math expression to be evaluated.
315 op (optional) comparison op to be applied to values
317
320 <if val1="$ascs.Base.value" val2="50" op="gt"><then>...</then><else>...</else></if>
321
323 - render multipoint gradient.
324
327 <gradient id="new_id" angle="degrees"
328 refid="refid" width="pixels" height="pixels"
329 colors ="color1 color2 color3 [...]"
330 offsets="fraction1 fraction2 fraction3 [...]"/>
331
333 id Optional. Image will be given this name for future reference.
334 refid Optional. An image ID defined with the "id" parameter for any
336 previously created image. If set, percentages in "width" and
337 "height" will be derived from the width and height of the refid
338 image.
339 width Optional. The result will have this width.
341 height Optional. The result will have this height.
343 colors Required. Whitespace-separated list of colors. At least two col‐
345 ors are required. Each color in this list will be visited in
346 turn, at the intervals given by the offsets attribute.
347 offsets
349 Optional. Whitespace-separated list of floating point values
350 ranging from 0.0 to 1.0. The colors from the colors attribute
351 are given these offsets, and the final gradient is rendered from
352 the combination of the two. If both colors and offsets are given
353 but the number of colors and offsets do not match, the minimum
354 of the two will be used, and the other will be truncated to
355 match. If offsets are not given, a smooth stepping from 0.0 to
356 1.0 will be used.
357 angle Optional. Given in degrees. Default is 0. This is the direction
359 of the gradient. Currently the only supported values are 0, 45,
360 90, 135, 180, 225, 270, 315. 0 means left to right, 90 means top
361 to bottom, etc. libAfterImage/asimagexml/solid
362
364 - generate image of specified size and fill it with solid color.
365
368 <solid id="new_id" color="color" opacity="opacity"
369 width="pixels" height="pixels"
370 refid="refid" width="pixels" height="pixels"/>
371
373 id Optional. Image will be given this name for future reference.
374 width Optional. The result will have this width.
376 height Optional. The result will have this height.
378 refid Optional. An image ID defined with the "id" parameter for any
380 previously created image. If set, percentages in "width" and
381 "height" will be derived from the width and height of the refid
382 image.
383 color Optional. Default is "#ffffffff". An image will be created and
385 filled with this color.
386 width Required. The image will have this width.
388 height Required. The image will have this height.
390 opacity
392 Optional. Default is 100. Values from 0 to 100 represent the
393 opacity of resulting image with 100 being completely opaque.
394 Effectively overrides alpha component of the color setting.
395 libAfterImage/asimagexml/save
396
398 - write generated/loaded image into the file of one of the supported
399 types
400
403 <save id="new_id" dst="filename" format="format" compress="value"
404 opacity="value" replace="0|1" delay="mlsecs">
405
407 id Optional. Image will be given this name for future reference.
408 dst Optional. Name of file image will be saved to. If omitted image
410 will be dumped into stdout - usefull for CGI apps.
411 format Optional. Ouput format of saved image. Defaults to the extension
413 of the "dst" parameter. Valid values are the standard AS image
414 file formats: xpm, jpg, png, gif, tiff.
415 compress
417 Optional. Compression level if supported by output file format.
418 Valid values are in range of 0 - 100 and any of "deflate",
419 "jpeg", "ojpeg", "packbits" for TIFF files. Note that JPEG and
420 GIF will produce images with deteriorated quality when compress
421 is greater then 0. For JPEG default is 25, for PNG default is 6
422 and for GIF it is 0.
423 opacity
425 Optional. Level below which pixel is considered to be transpar‐
426 ent, while saving image as XPM or GIF. Valid values are in range
427 0-255. Default is 127.
428 replace
430 Optional. Causes ascompose to delete file if the file with the
431 same name already exists. Valid values are 0 and 1. Default is 1
432 - files are deleted before being saved. Disable this to get mul‐
433 timage animated gifs.
434 delay Optional. Delay to be stored in GIF image. This could be used to
436 create animated gifs. Note that you have to set replace="0" and
437 then write several images into the GIF file with the same name.
438
441 This tag applies to the first image contained within the tag. Any
442 further images will be discarded.
443
445 - set image's background color.
446
449 <background id="new_id" color="color">
450
452 id Optional. Image will be given this name for future reference.
453 color Required. Color to be used for background - fills all the spaces
455 in image with missing pixels.
456
459 This tag applies to the first image contained within the tag. Any
460 further images will be discarded.
461
463 - perform a gaussian blurr on an image.
464
467 <blur id="new_id" horz="radius" vert="radius" channels="argb">
468
470 id Optional. Image will be given this name for future reference.
471 horz Optional. Horizontal radius of the blur in pixels.
473 vert Optional. Vertical radius of the blur in pixels.
475 channels
477 Optional. Applys blur only on listed color channels: a - alpha,
478 r - red, g - green, b - blue
479
482 This tag applies to the first image contained within the tag. Any
483 further images will be discarded.
484
486 - draws solid bevel frame around the image.
487
490 <bevel id="new_id" colors="color1 color2"
491 width="pixels" height="pixels" refid="refid"
492 border="left top right bottom" solid=0|1 outline=0|1>
493
495 id Optional. Image will be given this name for future reference.
496 colors Optional. Whitespace-separated list of colors. Exactly two col‐
498 ors are required. Default is "#ffdddddd #ff555555". The first
499 color is the color of the upper and left edges, and the second
500 is the color of the lower and right edges.
501 borders
503 Optional. Whitespace-separated list of integer values. Default
504 is "10 10 10 10". The values represent the offsets toward the
505 center of the image of each border: left, top, right, bottom.
506 solid Optional - default is 1. If set to 0 will draw bevel gradually
508 fading into the image.
509 outline
511 Optional - default is 0. If set to 1 will draw bevel around the
512 image vs. inside the image.
513 width Optional. The result will have this width.
515 height Optional. The result will have this height.
517 refid Optional. An image ID defined with the "id" parameter for any
519 previously created image. If set, percentages in "width" and
520 "height" will be derived from the width and height of the refid
521 image.
522
525 This tag applies to the first image contained within the tag. Any
526 further images will be discarded.
527
529 - create new image as mirror copy of an old one.
530
533 <mirror id="new_id" dir="direction"
534 width="pixels" height="pixels" refid="refid">
535
537 id Optional. Image will be given this name for future reference.
538 dir Required. Possible values are "vertical" and "horizontal". The
540 image will be flipped over the x-axis if dir is vertical, and
541 flipped over the y-axis if dir is horizontal.
542 width Optional. The result will have this width.
544 height Optional. The result will have this height.
546 refid Optional. An image ID defined with the "id" parameter for any
548 previously created image. If set, percentages in "width" and
549 "height" will be derived from the width and height of the refid
550 image.
551
554 This tag applies to the first image contained within the tag. Any
555 further images will be discarded.
556
558 - rotate an image in 90 degree increments (flip).
559
562 <rotate id="new_id" angle="degrees"
563 width="pixels" height="pixels" refid="refid">
564 * ATTRIBUTES
565 id Optional. Image will be given this name for future reference.
566 angle Required. Given in degrees. Possible values are currently
567 "90", "180", and "270". Rotates the image through the given
568 angle.
569 width Optional. The result will have this width.
570 height Optional. The result will have this height.
571 refid Optional. An image ID defined with the "id" parameter for
572 any previously created image. If set, percentages in "width"
573 and "height" will be derived from the width and height of the
574 refid image.
575
577 This tag applies to the first image contained within the tag. Any
578 further images will be discarded.
579
581 - scale image to arbitrary size
582
585 <scale id="new_id" ref_id="other_imag" src_x="pixels" src_y="pixels"
586 src_width="pixels" src_height="pixels"
587 width="pixels" height="pixels">
588
590 id Optional. Image will be given this name for future reference.
591 refid Optional. An image ID defined with the "id" parameter for any
593 previously created image. If set, percentages in "width" and
594 "height" will be derived from the width and height of the refid
595 image.
596 width Required. The image will be scaled to this width.
598 height Required. The image will be scaled to this height.
600 src_x Optional. Default is 0. X Offset on infinite surface tiled with
602 this image, from which to cut portion of an image to be used in
603 scaling.
604 src_y Optional. Default is 0. Y Offset on infinite surface tiled with
606 this image, from which to cut portion of an image to be used in
607 scaling.
608 src_width
610 Optional. Default is image width. Tile image to this width prior
611 to scaling.
612 src_height
614 Optional. Default is image height. Tile image to this height
615 prior to scaling.
616 * NOTES
618 This tag applies to the first image contained within the tag. Any
620 further
622 images will be discarded.
623 If you want to keep image proportions while scaling - use "propor‐
625 tional"
626 instead
628 of specific size for particular dimention. libAfterImage/asim‐
629 agexml/slice
630
632 - slice image to arbitrary size leaving corners unchanged
633
636 <slice id="new_id" ref_id="other_imag" width="pixels" height="pixels"
637 x_start="slice_x_start" x_end="slice_x_end"
638 y_start="slice_y_start" y_end="slice_y_end"
639 scale="0|1">
640
642 id Optional. Image will be given this name for future reference.
643 refid Optional. An image ID defined with the "id" parameter for any
645 previously created image. If set, percentages in "width" and
646 "height" will be derived from the width and height of the refid
647 image.
648 width Required. The image will be scaled to this width.
650 height Required. The image will be scaled to this height.
652 x_start
654 Optional. Position at which vertical image slicing begins. Cor‐
655 responds to the right side of the left corners.
656 x_end Optional. Position at which vertical image slicing end. Corre‐
658 sponds to the left side of the right corners.
659 y_start
661 Optional. Position at which horisontal image slicing begins.
662 Corresponds to the bottom side of the top corners.
663 y_end Optional. Position at which horisontal image slicing end. Corre‐
665 sponds to the top side of the bottom corners.
666 scale Optional. If set to 1 will cause middle portion of the image to
668 be scaled instead of tiled.
669
672 This tag applies to the first image contained within the tag. Any
673 further images will be discarded.
674 Contents of the image between x_start and x_end will be tiled
675 horizontally. Contents of the image between y_start and y_end will be
676 tiled vertically. This is usefull to get background images to fit the
677 size of the text or a widget, while preserving its borders undistorted,
678 which is the usuall result of simple scaling.
679 If you want to keep image proportions while resizing-use "proportional"
680 instead of specific size for particular dimention.
681
683 - crop image to arbitrary area within it.
684
687 <crop id="new_id" refid="other_image" srcx="pixels" srcy="pixels"
688 width="pixels" height="pixels" tint="color">
689
691 id Optional. Image will be given this name for future reference.
692 refid Optional. An image ID defined with the "id" parameter for any
694 previously created image. If set, percentages in "width" and
695 "height" will be derived from the width and height of the refid
696 image.
697 srcx Optional. Default is "0". Skip this many pixels from the left.
699 srcy Optional. Default is "0". Skip this many pixels from the top.
701 width Optional. Default is "100%". Keep this many pixels wide.
703 height Optional. Default is "100%". Keep this many pixels tall.
705 tint Optional. Additionally tint an image to specified color. Tinting
707 can both lighten and darken an image. Tinting color 0 or
708 #7f7f7f7f yeilds no tinting. Tinting can be performed on any
709 channel, including alpha channel.
710
713 This tag applies to the first image contained within the tag. Any
714 further images will be discarded.
715
717 - tile an image to specified area.
718
721 <tile id="new_id" refid="other_image" width="pixels" height="pixels"
722 x_origin="pixels" y_origin="pixels" tint="color" complement=0|1>
723
725 id Optional. Image will be given this name for future reference.
726 refid Optional. An image ID defined with the "id" parameter for any
728 previously created image. If set, percentages in "width" and
729 "height" will be derived from the width and height of the refid
730 image.
731 width Optional. Default is "100%". The image will be tiled to this
733 width.
734 height Optional. Default is "100%". The image will be tiled to this
736 height.
737 x_origin
739 Optional. Horizontal position on infinite surface, covered with
740 tiles of the image, from which to cut out resulting image.
741 y_origin
743 Optional. Vertical position on infinite surface, covered with
744 tiles of the image, from which to cut out resulting image.
745 tint Optional. Additionally tint an image to specified color. Tinting
747 can both lighten and darken an image. Tinting color 0 or
748 #7f7f7f7f yields no tinting. Tinting can be performed on any
749 channel, including alpha channel.
750 complement
752 Optional. Will use color that is the complement to tint color
753 for the tinting, if set to 1. Default is 0.
754
757 This tag applies to the first image contained within the tag. Any
758 further images will be discarded.
759
761 - adjust Hue, Saturation and/or Value of an image and optionally tile
762 an image to arbitrary area.
763
766 <hsv id="new_id" refid="other_image"
767 x_origin="pixels" y_origin="pixels" width="pixels" height="pixels"
768 affected_hue="degrees|color" affected_radius="degrees"
769 hue_offset="degrees" saturation_offset="value"
770 value_offset="value">
771
773 id Optional. Image will be given this name for future reference.
774 refid Optional. An image ID defined with the "id" parameter for any
776 previously created image. If set, percentages in "width" and
777 "height" will be derived from the width and height of the refid
778 image.
779 width Optional. Default is "100%". The image will be tiled to this
781 width.
782 height Optional. Default is "100%". The image will be tiled to this
784 height.
785 x_origin
787 Optional. Horizontal position on infinite surface, covered with
788 tiles of the image, from which to cut out resulting image.
789 y_origin
791 Optional. Vertical position on infinite surface, covered with
792 tiles of the image, from which to cut out resulting image.
793 affected_hue
795 Optional. Limits effects to the renage of hues around this hue.
796 If numeric value is specified - it is treated as degrees on 360
797 degree circle, with : red = 0, yellow = 60, green = 120, cyan =
798 180, blue = 240, magenta = 300. If colorname or value preceded
799 with # is specified here - it will be treated as RGB color and
800 converted into hue automagically.
801 affected_radius
803 Optional. Value in degrees to be used in order to calculate the
804 range of affected hues. Range is determined by substracting and
805 adding this value from/to affected_hue.
806 hue_offset
808 Optional. Value by which to adjust the hue.
809 saturation_offset
811 Optional. Value by which to adjust the saturation.
812 value_offset
814 Optional. Value by which to adjust the value.
815
818 One of the Offsets must be not 0, in order for operation to be
819 performed.
820 This tag applies to the first image contained within the tag. Any
822 further images will be discarded.
823
825 - pad an image with solid color rectangles.
826
829 <pad id="new_id" left="pixels" top="pixels"
830 right="pixels" bottom="pixels" color="color"
831 refid="refid" width="pixels" height="pixels">
832
834 id Optional. Image will be given this name for future reference.
835 width Optional. The result will have this width.
837 height Optional. The result will have this height.
839 refid Optional. An image ID defined with the "id" parameter for any
841 previously created image. If set, percentages in "width" and
842 "height" will be derived from the width and height of the refid
843 image.
844 left Optional. Size to add to the left of the image.
846 top Optional. Size to add to the top of the image.
848 right Optional. Size to add to the right of the image.
850 bottom Optional. Size to add to the bottom of the image.
852 color Optional. Color value to fill added areas with. It could be
854 transparent of course. Default is #FF000000 - totally black.
855
858 This tag applies to the first image contained within the tag. Any
859 further images will be discarded.
8603rd Berkeley Distribution AfterStep v.2.2.6 asimagexml(1)