Appendix A. Scalable X Graphics
Prev   Next

Appendix A. Scalable X Graphics

Index

Structure of an SXG file
Scaling and round-off errors
Scaling algorithm
Specifying fonts
Creating pictures
Creating solid color pictures
Defining a background color
Using theme colors
Using predefined locations and dimensions
Creating text pictures
Creating pixmaps
Graphic context commands
function
foreground
background
line_width
line_style
join_style
cap_style
fill_style
clip
dashes
line
fill and clear
fill_arc_mode
arcs
Picture render commands
op
repeat
clip
fill
composite
triangles
tristrip and trifan
Example SXG file
Using XInclude with SXG files

SXG is an XML-based file format. LibCXX Widget Toolkit uses SXG to draw scalable icons and other widgets. LibCXX Widget Toolkit uses its own custom icon file format for the following reasons:

Structure of an SXG file

<sxg>
  <width>16</width>
  <height>16</height>
  <widthmm>10</widthmm>
  <heightmm>10</widthmm>

  <!-- <depth>1</depth> -->

  <!-- optional -->

  <widthfactor>2</widthfactor>
  <heightfactor>2</heightfactor>

  <!-- font declaration -->

  <!-- pixmap and picture declaration -->

  <!-- gc and render instructions -->
</sxg>

The top level sxg element defines:

  • Dimensions of the virtual cartesian coordinate space of the SXG file. The drawing instructions in the rest of the file get specified using these dimensions.

    The above example specifies that this SXG file gives drawing instructions on a canvas that's 16 virtual pixels across, and 16 virtual pixels tall. The X and Y coordinates, therefore, range from 0 to 15. Coordinate (0, 0) is the top left corner.

    LibCXX Widget Toolkit computes the SXG's image actual size, in pixels, then scales the coordinates in the SXG file to the displayed image's actual size. For example, if LibCXX Widget Toolkit needs to scale the above image to a 32x32 icon, all coordinates in the SXG file get effectively doubled.

    The coordinates in the SXG file can be fractional (i.e., fill a rectangle 8.5 pixels wide, and this dimension gets scaled appropriately). However, it's better to use the smallest virtual coordinate space that's large enough to represent all points as whole numbers,

    Note

    The individual drawing instructions' coordinates may be fractional, but the width and height elements must specify integer values.

  • The widthmm and heightmm elements give the default, or nominal, size of the image in the SXG file. The dimensions are in millimeters. The values may be fractional, but they compute an integer pixel value according to the screen display's resolution.

    For example, with the default SXG size given as ten millimeters wide and tall, a screen display with the resolution of 2.5 pixels per millimeter produces the nominal SXG size of 25x25 pixels, and the all coordinates in the SXG file get scaled accordingly.

  • Optional elements widthfactor and heightfactor default to 1. The nominal width and height gets rounded off to an even multiple of pixels specified by this value. For example, setting both to 2 ensures that the default image width and height is always an even number of pixels.

  • Some special-purpose SXG icons have a depth element with a value of 1. This creates a one-bit deep image that's typically used to create a masking image of some kind.

    This is used to create a masking picture, such as the mask for dithering disabled widgets.

  • The font elements specify the fonts used by text pictures.

  • The pixmap and picture elements create pixmaps and picture objects used in drawing the SXG image. These elements directly correspond to X protocol's pixmap and RENDER extension's picture objects.

    A unique label identifies each picture and pixmap. A picture labeled “main” gets created by default, this is the final drawn image. After executing the drawing instructions in the SXG file, the “main” picture's contents become the drawn image. All other pictures and pixmaps get discarded. The “main” picture's actual size determines the scaling factors for all scaled drawing instructions. The LibCXX Widget Toolkit creates a picture object, perhaps after consulting SXG file's nominal width and height, and the drawing instructions in the SXG file get scaled accordingly.

    All picture and pixmap labels are unique. The same label cannot be used for both a picture and a pixmap. To make things slightly confusing, pixmaps may be specified as picture parameters in some drawing instructions, using their label. This is because a picture gets created for each pixmap. And to confuse things even further, each regular picture object, of course, represents a pixmap, and a pixmap gets created for each regular picture (except for solid color pictures, as explained later).

    The reason for separate pixmap and picture declarations has to do with the pictformat of the resulting pixmap/picture duo. There are two main groups of drawing instructions in the SXG file. One group uses X protocol's graphic contexts that are only used with pixmaps. The second group uses RENDER extension instructions; which can only use pictures.

    The size of regular picture and pixmap objects either get scaled based on “main”'s picture, or they are fixed dimensions, as specified by their size widget.

  • The rest of the SXG file consists of gc and render elements. Each pixmap has a collection of one or more gcs, that are directly equivalent to X protocol's graphic contexts, which draw on their pixmap. Graphic contexts also have unique label identifiers. The same graphic context label cannot be used by another pixmap's graphic context.

    The gc element specifies a list of commands to execute for a graphic context object with the specified label identifier. The render element specifies a list of commands to execute for a picture object with the specified label identifier.

    All coordinates in gc and render elements may be fractional, and they get scaled according to the referenced pixmap or picture's size. Example: a picture or a pixmap defines its size as ten by ten "millimeters". The display's resolution is 3.5 pixels per millimeter. The actual object's size is 35 by 35 pixels. All coordinates specified in the gc or render elements are still values between and up to, but not including 10. Fractional coordinates are allowed, and they get scaled to the 0-34 range.

Prev   Next
Windows no longer getting updated Table Of Contents Scaling and round-off errors