_WBGC_ Struct Reference

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 structure has been defined for a couple of reasons: First, it is a similar concept to using 'HDC' in Win32, so it can help to translate all of the GC-related operations in a 1:1 manner for Win32; Second, it enables the toolkit to cache locally EVERYTHING that might enhance performance for X11 implmentations. Win-Win.

The biggest single performance problem in X11 exists when you want to use a remote client and also want to enhance operations beyond the simple features that are natively supported by an X server, things like anti-aliasing and transparency [for example]. In order to simplify implementing these things in a way that does NOT impact performance is to cache everything locally that might otherwise result in an RPC-like call into the X Server. The single slowest operation in this case is obtaining an XImage from a Pixmap or Window, and so this is specifically cached in the toolkit. Additionally, functions that can perform operations on these resources locally (rather than remotely) can then leverage the cached information, often giving you a significant performance boost.

The only down side is the additional housekeeping needed to track all of this.

typedef struct _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 {
       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 363 of file window_helper.h.

---

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

• window_helper.h