internal wrapper struct for GC with local cache More...

#include <window_helper.h>

Data Fields
Display *	display
	the Display associated with the WBGC (NULL implies 'Default Display')

Drawable	dw
	the Drawable for which this WBGC was created (None implies default Window)

GC	gc
	the associated 'GC'

XGCValues	values
	cached XGCValues for the GC

WB_FONT	pFont
	cached default font

Region	clip_rgn
	clipping region (or None to use clip_image) - owned by the object

XImage *	clip_image
	cached XImage for the GC, for 'clip mask'

XImage *	tile_image
	cached XImage for the GC, for 'tile'

XImage *	stip_image
	cached XImage for the GC, for 'stipple'

Detailed Description

internal wrapper struct for GC with local cache

The WBGC data type (and its associated structure) represent a locally cached 'Graphics Context' that can be efficiently used by the X11workbench Toolkit . It is similar to a GC structure in X11, and an HDC in windows, and exists for basically the same purpose.

Local cacheing of context information improves efficiency, especially for remote X11 clients.

typedef struct s_WBGC
{
  Display *display;   // the Display associated with the WBGC (NULL implies 'Default Display')
  Drawable dw;        // the Drawable for which this WBGC was created (None implies default Window)
  GC gc;              // the associated 'GC'
  XGCValues values;   // cached XGCValues for the GC
  WB_FONT pFont;      // cached default font
  Region clip_rgn;    // clipping region (or None to use clip_image)
  XImage *clip_image; // cached XImage for the GC, for 'clip mask'
  XImage *tile_image; // cached XImage for the GC, for 'tile'
  XImage *stip_image; // cached XImage for the GC, for 'stipple'
} * WBGC;

It is generally safe to query the 'values' member in order to get cached information about the WBGC. You should not change them, however.

The XOrg documentation defines the XGCValues structure as follows:

typedef struct // XGCValues
{
  int function;               // logical operation
  unsigned long plane_mask;   // plane mask
  unsigned long foreground;   // foreground pixel
  unsigned long background;   // background pixel
  int line_width;             // line width (in pixels)
  int line_style;             // LineSolid, LineOnOffDash, LineDoubleDash
  int cap_style;              // CapNotLast, CapButt, CapRound, CapProjecting
  int join_style;             // JoinMiter, JoinRound, JoinBevel
  int fill_style;             // FillSolid, FillTiled, FillStippled FillOpaqueStippled
  int fill_rule;              // EvenOddRule, WindingRule
  int arc_mode;               // ArcChord, ArcPieSlice
  Pixmap tile;                // tile pixmap for tiling operations
  Pixmap stipple;             // stipple 1 plane pixmap for stippling
  int ts_x_origin;            // offset for tile or stipple operations
  int ts_y_origin;
  Font font;                  // default text font for text operations
  int subwindow_mode;         // ClipByChildren, IncludeInferiors
  Bool graphics_exposures;    // boolean, should exposures be generated
  int clip_x_origin;          // origin for clipping
  int clip_y_origin;
  Pixmap clip_mask;           // bitmap clipping; other calls for rects
  int dash_offset;            // patterned/dashed line information
  char dashes;
} XGCValues;

Additional information regarding the drawing of lines

The XOrg 'manual page' documentation for XGCValues also includes the following information (slightly edited):

The line-width is measured in pixels and either can be greater than or
equal to one (wide line) or can be the special value zero (thin line).
Wide lines are drawn centered on the path described by the graphics
request.  Unless otherwise specified by the join-style or cap-style,
the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
width w is a rectangle with vertices at the following real coordinates:
[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
Here sn is the sine of the angle of the line, and cs is the cosine of
the angle of the line.  A pixel is part of the line and so is drawn if
the center of the pixel is fully inside the bounding box (which is
viewed as having infinitely thin edges).  If the center of the pixel is
exactly on the bounding box, it is part of the line if and only if the
interior is immediately to its right (x increasing direction).  Pixels
with centers on a horizontal edge are a special case and are part of
the line if and only if the interior or the boundary is immediately
below (y increasing direction) and the interior or the boundary is
immediately to the right (x increasing direction).
Thin lines (zero line-width) are one-pixel-wide lines drawn using an
unspecified, device-dependent algorithm.  There are only two con-
straints on this algorithm.
1.   If a line is drawn unclipped from [x1,y1] to [x2,y2] and if
    another line is drawn unclipped from [x1+dx,y1+dy] to
    [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line
    if and only if the point [x+dx,y+dy] is touched by drawing the
    second line.
2.   The effective set of points comprising a line cannot be affected
    by clipping.  That is, a point is touched in a clipped line if and
    only if the point lies inside the clipping region and the point
    would be touched by the line when drawn unclipped.
A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
and join-style.  It is recommended that this property be true for thin
lines, but this is not required.  A line-width of zero may differ from
a line-width of one in which pixels are drawn.  This permits the use of
line drawing hardware from many manufacturers, which may run many times
faster than the more precisely specified wide lines.
In general, drawing a thin line will be faster than drawing a wide line
of width one.  However, because of their different drawing algorithms,
thin lines may not mix well aesthetically with wide lines.  If it is
desirable to obtain precise and uniform results across all displays, a
client should always use a line-width of one rather than a line-width
of zero.

To be fair, the use of a line width of zero in the X11Workbench Toolkit is NOT recommended. The XImage code will assume zero implies width=1.

Also, an algorithm that allows the 'touching' of the same point many times is not impractical with an XImage; that is, the amount of code needed to check if a point were touched or will be touched is more computationally expensive than 'just touching it anyway'. As such, the XImage code may 'touch' a point multiple times, depending. For video hardware, especially accelerated video hardware, this could be a performance hit. But when using an XImage as a backing store for the window contents, it makes more sense to simply draw it anyway.

Additional information can be found in the aforementioned manual page.

Definition at line 397 of file window_helper.h.

The documentation for this struct was generated from the following file:

window_helper.h

Data Fields

Detailed Description