doc/fvwm/images.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: images.xml,v 1.4 2007/07/16 15:07:14 scott Exp $ -->
   3 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   4   "../docbook-xml/docbookx.dtd"
   5 [
   6 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   7 %myents;
   8 ]>
   9
  10 <section id="icons_and_images">
  11 <title>Icons and Images</title>
  12 <para>Fvwm can load <markup>.xbm,</markup> <markup>.xpm,</markup>
  13 <markup>.png</markup> and
  14 <markup>.svg</markup> images. <emphasis remap='B'>XBM</emphasis>
  15 images are monochrome.  Fvwm can always display
  16 <emphasis remap='B'>XBM</emphasis> files. <emphasis remap='B'>XPM</emphasis>
  17 and <emphasis remap='B'>PNG</emphasis> formats are color images.
  18 SVG is a vector graphics image format.
  19 Compile-time options determine whether fvwm can display
  20 <emphasis remap='B'>XPM</emphasis>, <emphasis remap='B'>PNG</emphasis> or
  21 <emphasis remap='B'>SVG</emphasis>
  22 icons and images. See the <emphasis remap='I'>INSTALL.fvwm</emphasis>
  23 file for more information.</para>
  24
  25 <!-- TODO: Create a link to INSTALL.fvwm file? -->
  26
  27 <para>The related <emphasis remap='B'>SHAPE</emphasis>
  28 compile-time option can make fvwm display spiffy shaped icons.</para>
  29
  30
  31 <section id='svg_rendering_options'>
  32 <title>SVG rendering options</title>
  33
  34 <para>
  35 SVG images are generated from (XML) text files.  A really simple SVG file
  36 might look something like this:</para>
  37
  38 <programlisting>
  39 &lt;svg width="120" height="80">
  40         &lt;rect fill="red"     width="40" height="40"  x="0"   y="0"  />
  41         &lt;rect fill="lime"    width="40" height="40"  x="40"  y="0"  />
  42         &lt;rect fill="blue"    width="40" height="40"  x="80"  y="0"  />
  43         &lt;rect fill="cyan"    width="40" height="40"  x="0"   y="40" />
  44         &lt;rect fill="magenta" width="40" height="40"  x="40"  y="40" />
  45         &lt;rect fill="yellow"  width="40" height="40"  x="80"  y="40" />
  46 &lt;/svg>
  47 </programlisting>
  48
  49 <mediaobject output='html'>
  50         <imageobject><imagedata
  51                 fileref="../images/svg_rendering/plain.png" />
  52         </imageobject>
  53         <caption>
  54                 <code>image.svg</code>
  55                 <para />
  56         </caption>
  57 </mediaobject>
  58
  59 <para>
  60 By default, SVG images are rendered as the image creator intended
  61 them to. But since SVG is a vector graphics format, the images can
  62 be rendered at any choosen size and rotation, e.g. making it possible
  63 to use the same icon file rendered at diffrent sizes for the
  64 <fvwmref cmd="Style" opt="Icon"/> and <fvwmref cmd="Style" opt="MiniIcon"/>
  65 styles.</para>
  66
  67 <para>The rendering options are specified as a string appended to the SVG
  68 filename as follows:</para>
  69
  70 <cmdsynopsis>
  71         <filename
  72                 ><replaceable>image.svg</replaceable
  73         ></filename
  74         ><literal>:</literal
  75         ><literal
  76                 ><arg choice='opt'>!</arg
  77         ></literal
  78         ><arg choice='opt'
  79                 ><synopfragmentref linkend="svg_rendering_size"
  80                         >size</synopfragmentref
  81         ></arg
  82         ><arg choice='plain' rep='repeat'
  83                 ><arg choice='opt'
  84                         ><synopfragmentref linkend="svg_rendering_position"
  85                                 >position</synopfragmentref
  86                 ></arg
  87                 ><arg choice='opt'
  88                         ><synopfragmentref linkend="svg_rendering_rotation"
  89                                 >rotation</synopfragmentref
  90                 ></arg
  91                 ><arg choice='opt'
  92                         ><synopfragmentref linkend="svg_rendering_scale"
  93                                 >scale</synopfragmentref
  94                 ></arg
  95         > </arg
  96         ><synopfragment id="svg_rendering_size"
  97                 ><literal
  98                         ><arg choice='opt'>-</arg
  99                 ></literal
 100                 ><replaceable>width</replaceable
 101                 ><literal
 102                         ><arg choice='req'>x</arg
 103                 ></literal
 104                 ><literal
 105                         ><arg choice='opt'>-</arg
 106                 ></literal
 107                 ><replaceable>height</replaceable
 108         ></synopfragment
 109         ><synopfragment id="svg_rendering_position"
 110                 ><literal
 111                         ><group choice='req'
 112                                 ><arg choice='plain'>-</arg
 113                                 ><arg choice='plain'>+</arg
 114                         ></group
 115                 ></literal
 116                 ><replaceable>xpos</replaceable
 117                 ><literal
 118                         ><group choice='req'
 119                                 ><arg choice='plain'>-</arg
 120                                 ><arg choice='plain'>+</arg
 121                         ></group
 122                 ></literal
 123                 ><replaceable>ypos</replaceable
 124         ></synopfragment
 125         ><synopfragment id="svg_rendering_rotation"
 126                 ><literal>@</literal
 127                 ><literal
 128                         ><arg choice='opt'>-</arg
 129                 ></literal
 130                 ><replaceable>angle</replaceable
 131         ></synopfragment
 132         ><synopfragment id="svg_rendering_scale"
 133                 ><literal
 134                         ><group choice='req'
 135                                 ><arg choice='plain'>*</arg
 136                                 ><arg choice='plain'>/</arg
 137                         ></group
 138                 ></literal
 139                 ><literal
 140                         ><arg choice='opt'>-</arg
 141                 ></literal
 142                 ><replaceable>factor</replaceable
 143                 ><literal
 144                         ><group choice='opt'
 145                                 ><arg choice='plain'>x</arg
 146                                 ><arg choice='plain'>y</arg
 147                         ></group
 148                 ></literal
 149         ></synopfragment>
 150 </cmdsynopsis>
 151
 152 <para>
 153 The option string always starts with a colon ('<literal>:</literal>')
 154 to separate it from the filename.  An empty option string can skip this
 155 colon, but it might still be a good idea to include it to prevent
 156 ambiguity if the filename contains any colon.</para>
 157
 158 <programlisting>
 159 filename_without_colon.svg
 160 filename:with:colon.svg:
 161 </programlisting>
 162
 163 <para>
 164 An exclamation point ('<literal>!</literal>') transposes the entire final
 165 image (including the rendering area), i.e. all the horizontal and all the
 166 vertical coordinates are swapped with each other.</para>
 167
 168 <programlisting>
 169 image.svg:!
 170 </programlisting>
 171
 172 <mediaobject output='html'>
 173         <imageobject><imagedata
 174                 fileref="../images/svg_rendering/transpose.png" />
 175         </imageobject>
 176         <caption>
 177                 <code>image.svg:!</code>
 178                 <para />
 179         </caption>
 180 </mediaobject>
 181
 182 <para>
 183 <replaceable>width</replaceable> and <replaceable>height</replaceable>
 184 specifies the dimensions of the rendering area in pixels, i.e. the
 185 dimensions of the resulting image.  The actual image is fitted to fill
 186 the entire rendering area.</para>
 187
 188 <programlisting>
 189 image.svg:60x60
 190 </programlisting>
 191
 192 <mediaobject output='html'>
 193         <imageobject><imagedata
 194                 fileref="../images/svg_rendering/size.png" />
 195         </imageobject>
 196         <caption>
 197                 <code>image.svg:60x60</code>
 198                 <para />
 199         </caption>
 200 </mediaobject>
 201
 202 <para>
 203 Use a <replaceable>width</replaceable> or <replaceable>height</replaceable>
 204 value of 0 to keep the aspect ratio.</para>
 205
 206 <programlisting>
 207 image.svg:0x60
 208 image.svg:60x0
 209 </programlisting>
 210
 211 <mediaobject output='html'>
 212         <imageobject><imagedata
 213                 fileref="../images/svg_rendering/size_keep_ratio_x.png" />
 214         </imageobject>
 215         <caption>
 216                 <code>image.svg:0x60</code>
 217                 <para />
 218         </caption>
 219 </mediaobject>
 220 <mediaobject output='html'>
 221         <imageobject><imagedata
 222                 fileref="../images/svg_rendering/size_keep_ratio_y.png" />
 223         </imageobject>
 224         <caption>
 225                 <code>image.svg:60x0</code>
 226                 <para />
 227         </caption>
 228 </mediaobject>
 229
 230 <para>A '<literal>-</literal>' before <replaceable>width</replaceable>
 231 mirrors the rendering area horizontally.</para>
 232
 233 <programlisting>
 234 image.svg:-0x0
 235 </programlisting>
 236
 237 <para>A '<literal>-</literal>' before <replaceable>height</replaceable>
 238 mirrors the rendering area vertically.</para>
 239
 240 <programlisting>
 241 image.svg:0x-0
 242 </programlisting>
 243
 244 <mediaobject output='html'>
 245         <imageobject><imagedata
 246                 fileref="../images/svg_rendering/size_mirroring_y.png" />
 247         </imageobject>
 248         <caption>
 249                 <code>image.svg:0x-0</code>
 250                 <para />
 251         </caption>
 252 </mediaobject>
 253
 254 <para>
 255 <replaceable>xpos</replaceable> and <replaceable>ypos</replaceable>
 256 specifies a translation of the image in pixels.  A positive
 257 <replaceable>xpos</replaceable> value moves the image to the right.  A
 258 positive <replaceable>ypos</replaceable> value moves it down.  Moving
 259 it partially outside of the rendering area results in a cropped
 260 image.</para>
 261
 262 <programlisting>
 263 image.svg:-30-0
 264 image.svg:-0+10
 265 image.svg:-30+10
 266 </programlisting>
 267
 268 <mediaobject output='html'>
 269         <imageobject><imagedata
 270                 fileref="../images/svg_rendering/position.png" />
 271         </imageobject>
 272         <caption>
 273                 <code>image.svg:-30+10</code>
 274                 <para />
 275         </caption>
 276 </mediaobject>
 277
 278 <para>
 279 <replaceable>angle</replaceable> specifies a rotation around the actual
 280 image center in degrees. This might result in a cropped image.  A
 281 positive value rotates the image clockwise.  Floating point values are
 282 recognized.</para>
 283
 284 <programlisting>
 285 image.svg:@180
 286 image.svg:@-90
 287 image.svg:@30
 288 image.svg:@57.3
 289 </programlisting>
 290
 291 <mediaobject output='html'>
 292         <imageobject><imagedata
 293                 fileref="../images/svg_rendering/rotation.png" />
 294         </imageobject>
 295         <caption>
 296                 <code>image.svg:@30</code>
 297                 <para />
 298         </caption>
 299 </mediaobject>
 300
 301 <para>
 302 <replaceable>factor</replaceable> specifes a scaling of the actual
 303 image (not the rendering area). Scaling it up results in a cropped
 304 image.  Floting point values are recognized.  Division by zero is
 305 ignored.  If <replaceable>factor</replaceable> is directly followed
 306 by a '<literal>x</literal>' or a '<literal>y</literal>', the scaling
 307 is horizontal or vertical respectively.  Otherwise the scaling is
 308 uniform.</para>
 309
 310 <programlisting>
 311 image.svg:*2
 312 image.svg:/2
 313 image.svg:/3x
 314 image.svg:/2y
 315 </programlisting>
 316
 317 <mediaobject output='html'>
 318         <imageobject><imagedata
 319                 fileref="../images/svg_rendering/scale_up_uniform.png" />
 320         </imageobject>
 321         <caption>
 322                 <code>image.svg:*2</code>
 323                 <para />
 324         </caption>
 325 </mediaobject>
 326 <mediaobject output='html'>
 327         <imageobject><imagedata
 328                 fileref="../images/svg_rendering/scale_down_uniform.png" />
 329         </imageobject>
 330         <caption>
 331                 <code>image.svg:/2</code>
 332                 <para />
 333         </caption>
 334 </mediaobject>
 335 <mediaobject output='html'>
 336         <imageobject><imagedata
 337                 fileref="../images/svg_rendering/scale_down_y.png" />
 338         </imageobject>
 339         <caption>
 340                 <code>image.svg:/2y</code>
 341                 <para />
 342         </caption>
 343 </mediaobject>
 344
 345 <para>
 346 Scaling down a translated or rotated image can prevent cropping.</para>
 347
 348 <programlisting>
 349 image.svg:@30*0.6
 350 </programlisting>
 351
 352 <mediaobject output='html'>
 353         <imageobject><imagedata
 354                 fileref="../images/svg_rendering/prevent_cropping.png" />
 355         </imageobject>
 356         <caption>
 357                 <code>image.svg:@30*0.6</code>
 358                 <para />
 359         </caption>
 360 </mediaobject>
 361
 362 <para>
 363 Repeated usage of translation, rotation, and scaling is allowed.
 364  Translation and rotation are additive.  Scaling is multiplicative.</para>
 365
 366 <programlisting>
 367 image.svg:*2/3
 368 image.svg:/3x/2y
 369 </programlisting>
 370
 371 <mediaobject output='html'>
 372         <imageobject><imagedata
 373                 fileref="../images/svg_rendering/scale_down.png" />
 374         </imageobject>
 375         <caption>
 376                 <code>image.svg:/3x/2y</code>
 377                 <para />
 378         </caption>
 379 </mediaobject>
 380
 381 <para>
 382 When combining affine transformations, the scaling is always done first,
 383 then the rotation, and finally the translation.</para>
 384
 385 <programlisting>
 386 image.svg:-30+10@30/3x/2y
 387 </programlisting>
 388
 389 <mediaobject output='html'>
 390         <imageobject><imagedata
 391                 fileref="../images/svg_rendering/affine_combined.png" />
 392         </imageobject>
 393         <caption>
 394                 <code>image.svg:-30+10@30/3x/2y</code>
 395                 <para />
 396         </caption>
 397 </mediaobject>
 398
 399 <para>
 400 Use a negative scale <replaceable>factor</replaceable> to mirror the
 401 actual image.</para>
 402
 403 <programlisting>
 404 image.svg:-30+10@30/-3x/2y
 405 </programlisting>
 406
 407 <mediaobject output='html'>
 408         <imageobject><imagedata
 409                 fileref="../images/svg_rendering/scale_mirroring.png" />
 410         </imageobject>
 411         <caption>
 412                 <code>image.svg:-30+10@30/-3x/2y</code>
 413                 <para />
 414         </caption>
 415 </mediaobject>
 416
 417 <para>
 418 Mirroring of the rendering area is done after any scaling, rotation or
 419 translation of the image.</para>
 420
 421 <programlisting>
 422 image.svg:-0x0-30+10@30/3x/2y
 423 </programlisting>
 424
 425 <mediaobject output='html'>
 426         <imageobject><imagedata
 427                 fileref="../images/svg_rendering/size_mirroring.png" />
 428         </imageobject>
 429         <caption>
 430                 <code>image.svg:-0x0-30+10@30/3x/2y</code>
 431                 <para />
 432         </caption>
 433 </mediaobject>
 434
 435 <para>
 436 Transposing is done last of all, after everything else.</para>
 437
 438 <programlisting>
 439 image.svg:!-0x0-30+10@30/3x/2y
 440 </programlisting>
 441
 442 <mediaobject output='html'>
 443         <imageobject><imagedata
 444                 fileref="../images/svg_rendering/all_combined.png" />
 445         </imageobject>
 446         <caption>
 447                 <code>image.svg:!-0x0-30+10@30/3x/2y</code>
 448                 <para />
 449         </caption>
 450 </mediaobject>
 451
 452 </section>
 453 </section>