Picture render commands

<sxg>

  <!-- width and height declarations -->

  <picture id="pen">
    <type>pixmap</type>
    <size>scaled</size>
    <width>16</width>
    <height>16</height>
  </picture>

  <render id="pen">

    <!-- Graphic context commands -->

  </render>
</sxg>

After declaring one or more picturess, the render elements execute commands for the picture object specified by their id attribute. A picture object with the id main gets automatically created by default. It represents the final drawn picture. Each render element itself contains a list of commands to execute, and the SXG file itself has a list of gc and render elements, which are processed in the order of their appearance. It's possible to have more than one appearance of a render element referencing the same picture id:

<sxg>

    <!-- ... -->

  <render id="pen">

    <!-- ... -->

  </render>

  <gc id="pixmap1_gc">

    <!-- ... -->

  </gc>

  <render id="pen">

    <!-- ... -->

  </render>

  <render id="main">

    <!-- ... -->

  </render>

</sxg>

This executes some rendering commands for the pen picture, followed by graphic context commands for the graphic context pixmap1_gc, followed by more render commands for picture pen, and finally some render commands for the main picture.

op

  <!-- -->

  <op>atop</op>

  <!-- -->

Several commands described below contain an optional op which specifies the compositing operator. Its value must be one of the following, setting the correposnding compositing operation from the RENDER specification: clear, src, dst, over, over_reverse, in, in_reverse, out, out_reverse, atop, atop_reverse, xor, add, saturate, disjoint_clear, disjoint_src, disjoint_dst, disjoint_over, disjoint_over_reverse, disjoint_in, disjoint_in_reverse, disjoint_out, disjoint_out_reverse, disjoint_atop, disjoint_atop_reverse, disjoint_xor, conjoint_clear, conjoint_src, conjoint_dst, conjoint_over, conjoint_over_reverse, conjoint_in, conjoint_in_reverse, conjoint_out, conjoint_out_reverse, conjoint_atop, conjoint_atop_reverse, conjoint_xor, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, hsl_hue, hsl_saturation, hsl_color, or hsl_luminosity.

Note

The last fifteen compositing operators are not specified in the RENDER extension, but are defined by the XCB library, and these definitions are available, as is. Since SXG uses the display server to execute all drawing instructions, support for each compositing operator depends on the display server.

repeat

<render id="pic1">

  <!-- -->

  <repeat>normal</repeat>

  <!-- -->

</render>

The repeat element sets the picture's repeat attribute. The value must be none, normal, pad, or reflect.

clip

<render id="pic1">

  <!-- -->

  <clip>
    <pixmap>pixmap1</pixmap>
    <clipped>
      <fill>

	<!-- -->

      </fill>
    </clipped>
  </clip>

  <clip>
    <rectangle>
      <x>0</x> <!-- optional -->
      <y>0</y>
      <width>10</width>
      <height><10</height>
   </rectangle>

    <rectangle>
      <x>10</x>
      <y>10</y>
      <width>10</width>
      <height><10</height>
    </rectangle>
    <clipped>
      <fill>

	<!-- -->

      </fill>
    </clipped>
  </clip>

  <!-- -->

</render>

The clip element sets the picture's clip area in one of two different ways:

  • Using the id label of a pixmap that serves as a clipping mask. This pixmap must be declared with a mask element.

    This option sets the picture object's clip-mask attribute directly.

  • Using a list of rectangles. Each rectangle's coordinates get scaled according to the pixture's size. This option uses the SetPictureClipRectangles command to set the picture object's clip-mask attribute.

The optional x and y elements set the clip-x-origin, and clip-y-origin attributes values. The coordinates get scaled according to the picture's size. If not specified, they default to actual (0, 0) coordinates.

The clip must have exactly one clipped inner element, which contains a list of any element that can appear in a render, except for another clip. The elements in clipped get executed with the clip mask in effect, after which point the clip mask is removed.

fill

<render id="pic1">

  <!-- -->

  <fill>
    <op>over</op>  <!-- optional, defaults to src -->

    <r>1</r>
    <g>1</g>

    <rectangle>
      <x>0</x>
      <y>0</y>
      <width>10</width>
      <height><10</height>
    </rectangle>

    <rectangle>
      <x>10</x>
      <y>10</y>
      <width>10</width>
      <height><10</height>
    </rectangle>
  </fill>

  <!-- -->

</render>

The fill element executes a FillRectangles render command. Its r, g, b, and a elements specify the value of the red, green, blue, and alpha channels, respectively. Each value ranges between 0 (minimum) and 1 (maximum). r, g, and b defaults to 0, minimum intensity. a defaults to 1, maximum intensity. Alternatively, a predefined theme color can also be specified.

The optional op elements defaults to src, Each rectangle's coordinates get scaled according to the pixture's size.

composite

<render id="pic1">

  <!-- -->

  <composite>
    <op>over</op>
    <x>0</x>    <!-- optional -->
    <y>0</y>
    <width>10</width>
    <height>10</height>
    <src>
      <picture>yellow</picture>
      <x>0</x>    <!-- optional -->
      <y>0</y>
    </src>
    <mask>   <!-- optional -->
      <pixmap>pixmap1</pixmap>
      <x>0</x>    <!-- optional -->
      <y>0</y>
    </mask>
  </composite>

  <!-- -->

  <composite>
    <op>over</op>
    <x>5</x>
    <y>5</y>

    <srcsize />

    <halign>centered</halign>
    <valign>middle</valign>

    <src>
      <picture>prompt</picture>
    </src>
  </composite>

  <!-- -->

</render>

The composite element executes a Composite render command. The Composite's dst picture is the render element that contains the composite command. x, y, width, and height specify the dst-x, dst-y, width and height parameters.

A srcsize is an alternative to width and height, this uses the source picture's width and height, instead. The optional halign and valign elements determine how x, y values are interpreted. halign may be left (default), centered, or right. valign may be top (default), middle, or or bottom.

op specifies the compositing operator. src specifies the src picture's label id, and the src-x and src-y parameters.

The optional mask gives the ID of the pixmap for the mask parameter (the RENDER extension specifies this as a picture object, and SXG provides a picture object for the given pixmap); together with the mask-x and mask-y parameters.

All coordinates get scaled according to their respective element's size. If not specified, they default to actual (0, 0) coordinates. Both the destination picture, the source picture, and the optional masking pixmap if specified, should have the same size setting.

triangles

<render id="pic1">

  <!-- -->

  <triangles>
    <op>over</op>          <!-- optional -->
    <mask>pixmap1</mask>   <!-- optional -->

    <x>0</x>               <!-- optional -->
    <y>0</y>               <!-- optional -->

    <src>yellow</src>

    <triangle>
      <p1>
	<x>0</x>
	<y>0</y>
      </p1>
      <p2>
	<x>10</x>
	<y>0</y>
      </p2>
      <p3>
	<x>0</x>
	<y>10</y>
      </p3>
    </triangle>

    <triangle>
      <p1>
	<x>10</x>
	<y>0</y>
      </p1>
      <p2>
	<x>20</x>
	<y>0</y>
      </p2>
      <p3>
	<x>20</x>
	<y>10</y>
      </p3>
    </triangle>
  </triangles>
  <!-- -->

</render>

The triangles element executes a Triangles render command. The optional op specifies the compositing operator, and defaults to src. The optional mask gives the ID of the pixmap for the mask parameter (the RENDER extension specifies this as a picture object, and SXG provides a picture object for the given pixmap). The optional x and y set Triangles' src-x and src-y parameters. The coordinates get scaled according to the picture's size. If not specified, they default to actual (0, 0) coordinates. The src element is the id label of a picture that sets the src parameter.

The triangle elements define each triangle's three corners. All coordinates get scaled according to the pixture's size.

tristrip and trifan

<render id="pic1">

  <!-- -->

  <tristrip>
    <op>over</op>          <!-- optional -->
    <mask>pixmap1</mask>   <!-- optional -->
    <x>0</x>               <!-- optional -->
    <y>0</y>               <!-- optional -->
    <src>yellow</src>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>10</x>
      <y>0</y>
    </point>
    <point>
      <x>10</x>
      <y>10</y>
    </point>
    <point>
      <x>20</x>
      <y>10</y>
    </point>
  </tristrip>

  <trifan>
    <op>over</op>          <!-- optional -->
    <mask>pixmap1</mask>   <!-- optional -->
    <x>0</x>               <!-- optional -->
    <y>0</y>               <!-- optional -->
    <src>yellow</src>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>10</x>
      <y>0</y>
    </point>
    <point>
      <x>10</x>
      <y>10</y>
    </point>
    <point>
      <x>0</x>
      <y>10</y>
    </point>
  </trifan>

  <!-- -->

</render>

These elements execute the TriStrip or the TriFan render command. The optional op specifies the compositing operator, and defaults to src. The optional mask gives the ID of the pixmap for the mask parameter (the RENDER extension specifies this as a picture object, and SXG provides a picture object for the given pixmap). The optional x and y parameters set src-x and src-y parameters. The coordinates get scaled according to the picture's size. If not specified, they default to actual (0, 0) coordinates. The src element is the id label of a picture that sets the src parameter.

A list of point elements provides the coordinates for the points command parameter. All coordinates get scaled according to the pixture's size.