Graphic context commands

<sxg>

  <!-- width and height declarations -->

  <pixmap id="pixmap1">
    <size>scaled</size>
    <width>16</width>
    <height>16</height>
    <gc id="pixmap1_gc1" />
  </pixmap>

  <gc id="pixmap1_gc">

    <!-- Graphic context commands -->

  </gc>
</sxg>

After declaring one or more gcs inside their pixmaps, the gc elements execute commands for the graphic context specified by their id attribute. A gc element is a list of commands described below. Each list gets executed in the given order, 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 gc element referencing the same graphic context id:

<sxg>

    <!-- ... -->

  <gc id="pixmap1_gc">

    <!-- ... -->

  </gc>

  <render id="cell">

    <!-- ... -->

  </render>

  <gc id="pixmap2_gc">

    <!-- ... -->

  </gc>

  <gc id="pixmap1_gc">

    <!-- ... -->

  </gc>

  <render id="main">

    <!-- ... -->

  </render>

</sxg>

This executes some graphic context commands for the graphic context pixmap1_gc, followed by RENDER commands for the picture cell, then graphic context commands for the graphic context pixmap2_gc, then pixmap1_gc, and finally some RENDER commands for the main picture.

Note

The graphic context state is persistent. If, for example, the first set of pixmap1_gc commands included setting the graphic context's function, the second set of pixmap1_gc commands starts with the graphic context still having that function set.

function

<gc id="pixmap1_gc">

  <!-- -->

  <function>set</function>

  <!-- -->

</gc>

This sets the current function component value for the graphic context. The value must be one of the following: clear, and, and_reverse, copy, and_inverted, noop, xor, or, nor, equiv, invert, or_reverse, copy_inverted, or_inverted, nand, or set.

foreground

<gc id="pixmap1_gc">

  <!-- -->

  <foreground>.5</foreground>

  <!-- -->

</gc>

This sets the foreground component value for the graphic context. The X protocol defines this component value as an integer, ranging from 0 and up to the value based on the pixmap's depth. The value specified in foreground ranges from 0 to 1, and gets scaled to the appropriate range of permissible foreground values.

As described previously, the pixmap serves as an alpha channel filter. A value of 0 is a completely transparent pixel value, a value of 1 is a fully opaque pixel value. A pixmap declared with a mask element can only have a value of a 0 or a 1, since it's a 1 bit deep pixmap. A non-mask pixmap is 8 bits deep, and a value between 0 and 1 gets scaled across the entire 8-bit deep pixmap.

background

<gc id="pixmap1_gc">

  <!-- -->

  <background>.5</background>

  <!-- -->

</gc>

This sets the background component value for the graphic context. The X protocol defines this component value as an integer, ranging from 0 and up to the value based on the pixmap's depth. The value specified in background ranges from 0 to 1, and gets scaled to the appropriate range of permissible background values.

As described previously, the pixmap serves as an alpha channel filter. A value of 0 is a completely transparent pixel value, a value of 1 is a fully opaque pixel value. A pixmap declared with a mask element can only have a value of a 0 or a 1.

line_width

<gc id="pixmap1_gc">

  <!-- -->

  <line_width>1</line_width>

  <!-- -->

</gc>

This sets the line-width component value of the graphic context. Specifying the value 0 set line-width to 0. Specifying a non-0 value scales it according to the pixmap's size; and if the result gets rounded off to 0, it gets increased to 1 before setting the line-width.

  <line_width slim="1">1</line_width>
</gc>

An optional slim attribute adds an additional scaling step: line-width gets set 0 if the scaled line width got rounded off to 1. The line-width remains unchanged if the scaled line width got rounded off to 2, or higher.

line_style

<gc id="pixmap1_gc">

  <!-- -->

  <line_style>on_off_dash</line_style>

  <!-- -->

</gc>

This sets the line-style component value of the graphic context. The value is one of: solid, on_off_dash, or double_dash.

join_style

<gc id="pixmap1_gc">

  <!-- -->

  <join_style>bevel</join_style>

  <!-- -->

</gc>

This sets the join-style component value of the graphic context. The value is one of: miter (default value), round, or bevel.

cap_style

<gc id="pixmap1_gc">

  <!-- -->

  <cap_style>round</cap_style>

  <!-- -->

</gc>

This sets the cap-style component value of the graphic context. The value is one of: not_last, butt (default value) round, or projecting.

fill_style

<gc id="pixmap1_gc">

  <!-- -->

    <fill_style />

    <fill_style>
      <tiled>non_mask_pixmap</tiled>
      <x>0</x>
      <y>0</y>
    </fill_style>

    <fill_style>
      <stippled>mask_pixmap</stippled>
      <x>0</x>
      <y>0</y>
    </fill_style>

    <fill_style>
      <opaque_stippled>mask_pixmap</opaque_stippled>
      <x>0</x>
      <y>0</y>
    </fill_style>

  <!-- -->

</gc>

This sets the fill-style, tile-stipple-x-origin, and tile-stipple-y-origin component values of the graphic context. An empty fill_style element sets the fill-style component to Solid. Otherwise, the fill-style component gets set to Tiled, Stippled, or OpaqueStippled, with either the tile or the stipple component value set to specified pixmap. The stipple pixmap must be declared with the mask element. The tile pixmap cannot be declared with mask element.

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

clip

<gc id="pixmap1_gc">

  <!-- -->

    <clip>
      <pixmap>pixmap2</pixmap>
      <x>0</x>
      <y>0</y>

      <clipped>
	<line>

	  <!-- -->

	</line>
      </clipped>
    </clip>

    <clip>
      <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>

      <clipped>
	<line>

	  <!-- -->

	</line>
      </clipped>

    </clip>

    <!-- -->

</gc>

This sets the clip-mask component value of the graphic context, in one of two 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 graphic context's clip-mask attribute directly.

  • Using a list of rectangles. Each rectangle's coordinates get scaled according to the underlying pixmap's size.

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

The pixmap specified by pixmap must be declared with a mask element.

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

dashes

<gc id="pixmap1_gc">

  <!-- -->

  <dashes>
    <dash>1</dash>
    <dash>2</dash>
  </dashes>

  <!-- -->

</gc>

This executes the SetDashes X protocol command using the dash values.

The offset element defaults to 0, if not given, and sets the dash-offset.

All of these values get scaled according to the pixmap's size.

line

<gc id="pixmap1_gc">

  <!-- -->

  <line>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>5</x>
      <y>5</y>
    </point>
    <point>
      <x>0</x>
      <y>10</y>
    </point>
  </line>

  <!-- -->

</gc>

This executes the PolyLine X protocol command using the point coordinates. All of these coordinates get scaled according to the pixmap's size.

<gc id="pixmap1_gc">

  <!-- -->

  <line>
    <fill>convex</fill>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>5</x>
      <y>5</y>
    </point>
    <point>
      <x>0</x>
      <y>10</y>
    </point>
  </line>

  <!-- -->

</gc>

An optional fill executes the the FillPoly X protocol instead of PolyLine. The fill specifies either complex nonconvex or convex. This sets the shape command parameter.

fill and clear

<gc id="pixmap1_gc">

  <!-- -->

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

  <!-- -->

  <clear />

</gc>

fill executes the PolyFillRectangle X protocol command for one rectangle specified by the coordinates. All of these coordinates get scaled according to the pixmap's size.

clear is a shorthand for a fill that covers the entire pixmap. This is helpful in clearing scaled pixmaps.

Note

Since clear is really a fill, the function must be set to clear to actually clear the pixmap.

fill_arc_mode

<gc id="pixmap1_gc">

  <!-- -->

  <fill_arc_mode>pie_slice</fill_arc_mode>

  <!-- -->

</gc>

This sets the arc-mode component value of the graphic context. The value is either chord or pie_slice.

arcs

<gc id="pixmap1_gc">

  <!-- -->

  <arcs>

    <fill /> <!-- optional -->

    <arc>
      <x>0</x>
      <y>0</y>
      <width>9</width>
      <height>9</height>
      <angle1>45</angle1>
      <angle2>90</angle2>
    </arc>

    <arc>
      <x>5</x>
      <y>5</y>
      <width>9</width>
      <height>9</height>
      <angle1>45</angle1>
      <angle2>90</angle2>
    </arc>
  </arcs>

  <!-- -->

</gc>

This executes either the PolyArc or the PolyFillArc protocol command, depending on whether the fill element exists. Each arc's coordinates get scaled according to the pixmap's size.

Note

The angles are specified in degrees, and SXG takes care of scaling it by 64, as defined by the X protocol.

Note

Note that, by default, LibCXX Windows Library calculates coordinates based on the center of virtually-scaled pixels. This has implications on the specification of the width and height of the arc. The width and the height of the scaled arc is computed from x to x+width and y to y+height.

<sxg>
  <width>10</width>
  <height>10</height>

  <!-- -->

  <arcs>

    <arc>
      <x>0</x>
      <y>0</y>
      <width>9</width>
      <height>9</height>
      <angle1>0</angle1>
      <angle2>360</angle2>
    </arc>

This defines a virtual cartesian coordinate space of 10x10 pixels, and draws a full circle within the coordinates defined by (x, y) and (x+width, y+height); or (0, 0) through (9, 9), the entire size of the virtual 10x10 cartesian coordinate space.

When scaled, the scaled circle gets bounded on the center of the virtually-scaled pixels. If the scaled image 1:1, the circle touches the sides of the image, since each virtual pixel is equivalent to a single physical pixel. If the scaled image is 3:1, there's a one pixel gap between the circle and the sides of the image, since the circle is scaled to the centerpoints of the virtuals, which now correspond to 3x3 physical pixels.

Note that explicitly specifying a line_width of 1 also scales the width of the drawn line. With a 3:1 scale the drawn line becomes three pixels thick; and with the circle boundary is anchored at the centerpoint of the scaled pixel, the drawn circle once again touches the sides of the image.

Note

LibCXX Windows Library also makes an additional, final adjustment to the size of the drawn arc. The underlying X Protocol's PolyArc and PolyFillArc commands' arcs specify the bounding rectangle of pixels (x,y) through (x+width,x+height) inclusively. So, a circle 50 pixels across and tall gets specified by an actual width and height of 49 (indicating fifty pixels starting with x and ending with pixel x+49, across, same for height).

The SXG image only needs to specify the coordinates based on the centerpoints of virtual pixels, and the scaled adjusted width and height gets calculated accordingly.