Pixmap utility functions

Data Structures
struct	tagXPM_ATTRIBUTES
	Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use. More...

Macros
#define	RGB255_TO_XCOLOR(R, G, B, X)
	Simple RGB assignment to pixel, 0-255 RGB. More...
#define	RGB_TO_XCOLOR(R, G, B, X)
	Simple RGB assignment to pixel, 0-65535 RGB. More...
#define	RGB255_FROM_XCOLOR(X, R, G, B)
	Simple RGB assignment from pixel, 0-255 RGB. More...
#define	RGB_FROM_XCOLOR(X, R, G, B)
	Simple RGB assignment from pixel, 0-65535 RGB. More...
#define	WB_isin(X)   WB_icos((X) - 256) /* subtract 256, i.e. pi/2 radians, to convert a cos to a sin */
	integer 127 * sin(iVal * pi / 512) calculation via lookup table More...
#define	XPM_CREATE_PIXMAP_FROM_DATA(A, B, C, D, E, F)   MyLoadPixmapFromData(A,B,C,D,E,F)
	Platform helper macro to create a pixmap from data. More...
#define	XPM_FREE_ATTRIBUTES(pAttr)   /* does nothing */
	Platform helper macro to free XPM_ATTRIBUTES filled in by XPM_CREATE_PIXMAP_FROM_DATA() More...

Typedefs
typedef struct tagXPM_ATTRIBUTES	XPM_ATTRIBUTES
	Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use. More...

Functions
static __inline__ XStandardColormap *	PXM_StandardColormapFromColormap (Display *pDisplay, Colormap colormap)
	create temporary XStandardColormap from a Colormap More...
void	PXM_RGBToYUV (int iR, int iG, int iB, int *piY, int *piU, int *piV)
	Convert R, G, B values to Y, U, V with 0-255 range. More...
void	PXM_RGBToHSV (int iR, int iG, int iB, int *piH, int *piS, int *piV)
	Convert R, G, B values to H, S, V with 0-255 range. More...
void	PXM_YUVToRGB (int iY, int iU, int iV, int *piR, int *piG, int *piB)
	Convert Y, U, V values to R, G, B with 0-255 range. More...
void	PXM_HSVToRGB (int iH, int iS, int iV, int *piR, int *piG, int *piB)
	Convert H, S, V values to R, G, B with 0-255 range. More...
void	PXM_PixelToRGB (XStandardColormap *pMap, XColor *pColor)
	Convert the pixel menber of an XColor to RGB. More...
void	PXM_RGBToPixel (XStandardColormap *pMap, XColor *pColor)
	Icon Registration for application 'large' and 'small' icons. More...
void	PXM_RegisterAppIcons (char *ppRegAppLarge[], char *ppRegAppSmall[])
	Icon Registration for application 'large' and 'small' icons. More...
int	PXM_RegisterPixmapResource (Atom aResource, char *ppResource[])
	Register an icon (or pixmap) resource using an Atom. More...
Pixmap	PXM_GetIconPixmap (int idIcon, XPM_ATTRIBUTES *pAttr, Pixmap *pMask)
	Create Icon pixmap pair using pre-defined resource ID. More...
Pixmap	PXM_GetIconPixmapFromAtom (Atom aIcon, XPM_ATTRIBUTES *pAttr, Pixmap *pMask)
	Create Icon pixmap pair using a registered or pre-defined resource ID. More...
Pixmap	PXM_LoadPixmap (char *ppXPM[], XPM_ATTRIBUTES *pAttr, Pixmap *pMask)
	Create pixmap or pixmap pair using an XPM array. More...
Pixmap	PXM_ImageToPixmap (Display *pDisplay, Drawable dw, XImage *pImage, unsigned long clrFGPixel, unsigned long clrBGPixel)
	Convert 'locally stored' XImage to 'server object' Pixmap. More...
Pixmap	PXM_ImageToPixmap0 (Display *pDisplay, Drawable dw, XImage *pImage)
	Convert 'locally stored' XImage to 'server object' Pixmap using default FG/BG colors for monochrome. More...
XImage *	PXM_PixmapToImage (Display *pDisplay, Pixmap pxImage)
	Convert pixmap to image (a wrapper for XGetImage on a pixmap) More...
Pixmap	PXM_CreatePixmap (Display *pDisplay, Drawable dw, unsigned int width, unsigned int height, unsigned int depth)
	Wrapper for XCreatePixmap() More...
int	PXM_FreePixmap (Display *pDisplay, Pixmap pxImage)
	Wrapper for XCreatePixmap() More...
Pixmap	PXM_CopyPixmap (Display *pDisplay, Drawable dw, Pixmap pxImage)
	Copy a pixmap for the specified Display and Drawable. More...
int	WBXShmQueryExtension (Display *pDisplay)
	Indicates whether the 'XShm' extensions are available (libXext) More...
int	WBXPutImage (Display *pDisplay, Drawable dw, WBGC gc, XImage *pImage, int src_x, int src_y, int dest_x, int dest_y, unsigned int width, unsigned int height)
	Write contents of an XImage onto a Drawable. More...
XImage *	WBXGetImage (Display *pDisplay, Drawable dw, int x, int y, unsigned int width, unsigned int height, unsigned long plane_mask, int format)
	Read contents of a Drawable onto an XImage. More...
int	WBXDestroyImage (XImage *pImage)
	Destroy an XImage - call this instead of XDestroyImage() More...
XImage *	WBXCopyImage (Display *pDisplay, XImage *pImage)
	Make a copy of an XImage. More...
static __inline__ void *	PXM_GetImageDataPtr (XImage *pImage)
	Returns pointer to XImage data. More...
static __inline__ unsigned long	PXM_GetImageDataLength (XImage *pImage)
	Returns the length of XImage data. More...
void	WBSimpleAntiAliasPixmap (Display *pDisplay, const XStandardColormap *pMap, Pixmap pxImage, unsigned long lPixel, WB_GEOM *pGeom)
	Simple anti-alias of a Pixmap using foreground pixel color. More...
void	WBSimpleAntiAliasImage (const XStandardColormap *pMap, XImage *pImage, unsigned long lPixel, WB_GEOM *pGeom)
	Simple anti-alias of an XImage using foreground pixel color. More...
unsigned char	WB_isqrt (unsigned char iVal)
	integer square root of a value 0-255 More...
unsigned char	WB_icos0 (unsigned char iVal)
	integer 255 * cos(iVal * pi / 512) calculation via lookup table (legacy, to be removed?) More...
char	WB_icos (int iVal)
	integer 127 * cos(iVal * pi / 512) calculation via lookup table More...
int	MyLoadPixmapFromData (Display *pDisplay, Window wID, char *aData[], Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr)
	Alternate for XpmCreatePixmapFromData() whenever libXpm is not being used. More...

Detailed Description

Utility functions for loading and managing pixmaps, icons, cursors, and so forth. These are primarily utilities and wrappers that include platform-dependent implementations as well as more generic functionality.

Macro Definition Documentation

RGB255_FROM_XCOLOR

#define RGB255_FROM_XCOLOR	(		X,
			R,
			G,
			B
	)

Value:

{register unsigned short __iR,__iG,__iB; RGB_FROM_XCOLOR(X,__iR, __iG, __iB); \
                                     if(__iR < 0xff80){ __iR += 0x80; } \
                                     if(__iG < 0xff80){ __iG += 0x80; } \
                                     if(__iB < 0xff80){ __iB += 0x80; } \
                                     __iR = __iR >> 8; __iG = __iG >> 8; __iB = __iB >> 8; \
                                     __iR &= 0xff; __iG &= 0xff; __iB &= 0xff; \
                                     (R) = __iR; (G) = __iG; (B) = __iB; }

Simple RGB assignment from pixel, 0-255 RGB.

Parameters

X	An XColor structure with valid RGB elements
R	returned red color, 0-255
G	returned green color, 0-255
B	returned blue color, 0-255

Assigns the R, G, and B parameters based on an XColor structure with 0-255 RGB This assumes the red, green, and blue elements of the XColor structure are correct. To assign red, green, and blue elements from the 'pixel' element within the XColor structure, use PXM_PixelToRGB()

Definition at line 129 of file pixmap_helper.h.

RGB255_TO_XCOLOR

#define RGB255_TO_XCOLOR	(		R,
			G,
			B,
			X
	)

Value:

{ (X).red = ((unsigned int)(R) << 8) & 0xffff; \
                                    (X).green = ((unsigned int)(G) << 8) & 0xffff; \
                                    (X).blue = ((unsigned int)(B) << 8) & 0xffff; \
                                    (X).flags = DoRed | DoGreen | DoBlue; }

Simple RGB assignment to pixel, 0-255 RGB.

Parameters

R	red color, 0-255
G	green color, 0-255
B	blue color, 0-255
X	An XColor structure

Assigns the appropriate RGB elements of an XColor structure based on 0-255 RGB. This does NOT assign the 'pixel' element. For that, use PXM_RGBToPixel()

Definition at line 94 of file pixmap_helper.h.

RGB_FROM_XCOLOR

#define RGB_FROM_XCOLOR	(		X,
			R,
			G,
			B
	)

Value:

{ (R) = (((X).flags) & DoRed) ? ((unsigned int)(X).red) & 0xffff : 0; \
                                   (G) = (((X).flags) & DoGreen) ? ((unsigned int)(X).green) & 0xffff : 0; \
                                   (B) = (((X).flags) & DoBlue) ? ((unsigned int)(X).blue) & 0xffff : 0; }

Simple RGB assignment from pixel, 0-65535 RGB.

Parameters

X	An XColor structure with valid RGB elements
R	returned red color, 0-65535
G	returned green color, 0-65535
B	returned blue color, 0-65535

Assigns the R, G, and B parameters based on an XColor structure with 0-65535 RGB This assumes the red, green, and blue elements of the XColor structure are correct. To assign red, green, and blue elements from the 'pixel' element within the XColor structure, use PXM_PixelToRGB()

Definition at line 150 of file pixmap_helper.h.

RGB_TO_XCOLOR

#define RGB_TO_XCOLOR	(		R,
			G,
			B,
			X
	)

Value:

{ (X).red = ((unsigned int)(R)) & 0xffff; \
                                 (X).green = ((unsigned int)(G)) & 0xffff; \
                                 (X).blue = ((unsigned int)(B)) & 0xffff; \
                                 (X).flags = DoRed | DoGreen | DoBlue; }

Simple RGB assignment to pixel, 0-65535 RGB.

Parameters

R	red color, 0-65535
G	green color, 0-65535
B	blue color, 0-65535
X	An XColor structure

Assigns the appropriate elements of an XColor structure based on 0-65535 RGB This does NOT assign the 'pixel' element. For that, use PXM_RGBToPixel()

Definition at line 110 of file pixmap_helper.h.

WB_isin

#define WB_isin

(

X

)

WB_icos((X) - 256) /* subtract 256, i.e. pi/2 radians, to convert a cos to a sin */

integer 127 * sin(iVal * pi / 512) calculation via lookup table

Parameters

iVal	An integer between 0 and 1024 that corresponds to an angle, where 0-1024 would be 0-2pi radians

Returns

An signed char sine value between -127 and 127

Use this function when an approximate cosine is needed within Quadrant I

Definition at line 1102 of file pixmap_helper.h.

XPM_CREATE_PIXMAP_FROM_DATA

#define XPM_CREATE_PIXMAP_FROM_DATA	(		A,
			B,
			C,
			D,
			E,
			F
	)		MyLoadPixmapFromData(A,B,C,D,E,F)

Platform helper macro to create a pixmap from data.

Parameters

A	A pointer to the Display
B	The Window ID
C	A pointer to an array of 'char *' that represents the pixmap data
D	A pointer to a Pixmap into which the data will be saved, or NULL
E	A pointer to the Pixmap into which the mask data will be saved (icons only), or NULL
F	A pointer to an XPM_ATTRIBUTES structure. If libXpm is present, this will be defined in X11/xpm.h

Returns

An integer indicating success or failure. See XpmCreatePixmapFromData in libXpm documentation

This macro abstracts calls to XpmCreatePixmapFromData() by allowing an internal function to be called whenever libXpm is not available for this purpose.

Definition at line 1233 of file platform_helper.h.

XPM_FREE_ATTRIBUTES

#define XPM_FREE_ATTRIBUTES

(

pAttr

)

/* does nothing */

Platform helper macro to free XPM_ATTRIBUTES filled in by XPM_CREATE_PIXMAP_FROM_DATA()

Parameters

pAttr

A pointer to the XPM_ATTRIBUTES that was filled in by a successful call to XPM_CREATE_PIXMAP_FROM_DATA()

This macro abstracts calls to XpmFreeAttributes() by allowing an internal function to be called whenever libXpm is not available for this purpose. For the current implementation, the non-libXpm version does nothing.
Use this macro to free up XPM_ATTRIBUTES structure members that consume resources after a successful call to XPM_CREATE_PIXMAP_FROM_DATA(). This will help prevent resource leaks.

Definition at line 1246 of file platform_helper.h.

Typedef Documentation

XPM_ATTRIBUTES

XPM_ATTRIBUTES

Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use.

When libXpm is in use, XPM_ATTRIBUTES becomes a #define for XpmAttributes, the structure used by XpmCreatePixmapFromData(). Because so many elements are not needed, MyLoadPixmapFromData() uses this scaled-down version whenever libXpm is not being used by the library.

The configure option "--enable-libXpm" forces linkage with libXpm. Note that this is NOT the default option, since performance is adversely affected when using libXpm. However, for 100% compatibility, it may be necessary to use libXpm as MyLoadPixmapFromData() has not been tested on all platforms.

When libXpm is NOT in use, the follow structure is defined:

typedef struct tagXPM_ATTRIBUTES
{
  int width;    // The width of the returned pixmaps
  int height;   // height of the returned pixmaps
  int depth;    // depth of the returned 'image' pixmap.  The mask pixmap always has a depth of '1'.

} XPM_ATTRIBUTES;

When libXpm IS in use, the following macro is defined:

#define XPM_ATTRIBUTES XpmAttributes

In summary, this structure is a scaled-down version of the standard X11 structure 'XpmAttributes', and is defined ONLY when libXpm is not in use (based on the configure script). Only those structure members that are needed by this toolkit have been defined in the scaled-down version.

For more information, see MyLoadPixmapFromData()

Function Documentation

MyLoadPixmapFromData()

int MyLoadPixmapFromData	(	Display *	pDisplay,
		Window	wID,
		char *	aData[],
		Pixmap *	pPixmap,
		Pixmap *	pMask,
		XPM_ATTRIBUTES *	pAttr
	)

Alternate for XpmCreatePixmapFromData() whenever libXpm is not being used.

Parameters

pDisplay	A pointer to the display to use when creating the pixmaps
wID	A window used as a 'drawable' reference when creating the pixmaps
aData	An 'xpm' pixmap array, using the standard format generated by utilities like 'gimp'
pPixmap	Pointer to the variable to receive the Pixmap. If the function fails, this will be 'None'
pMask	Pointer to the variable to receive the transparency mask Pixmap. This may be 'None' if there is no transparency mask
pAttr	Pointer to the 'XPM_ATTRIBUTES' structure, which is a subset of the XpmAttributes structure used by XpmCreatePixmapFromData()

Returns

A value of zero on success (same as XpmSuccess, returned by XpmCreatePixmapFromData() on success).

This function is an alternate for XpmCreatePixmapFromData() whenever libXpm is not being used. It provides similar functionality, although there are some significant differences, particularly with the use of XPM_ATTRIBUTES as an actual structure and not just a '#define'. Additionally, there is a significant performance benefit for using this function in lieu of libXpm. As such it is the default configuration NOT to use libXpm.

If you want to use libXpm, you can use the '–enable-libXpm' option in the 'configure' script for the project.

Whenever libXpm is compiled in, XPM_ATTRIBUTES becomes a macro that is defined as XpmAttributes, the structure used by XpmCreatePixmapFromData(). There are a large number of members in this structure that are not useful for the purpose of this function, and so a scaled-down version is used when MyLoadPixmapFromData is being invoked.

You should consider whether or not you want to use libXpm whenever it is present on your system, as this function has not been fully tested on all platforms. However, using libXpm carries with it a significant performance penalty. If the application runs ok with the default configuration (i.e. no libXpm), you might as well leave it as-is.

Header File: platform_helper.h

Definition at line 3108 of file platform_helper.c.

PXM_CopyPixmap()

Pixmap PXM_CopyPixmap	(	Display *	pDisplay,
		Drawable	dw,
		Pixmap	pxImage
	)

Copy a pixmap for the specified Display and Drawable.

Parameters

pDisplay	The display associated with the source and destination Pixmaps
dw	The Drawable associated with the new Pixmap (this defines how to create it)
pxImage	the Pixmap image to free resources for

Returns

A Pixmap with the appropriate characteristics, or None on error.

This function implements the functionality of XCreatPixmap() and XCopyArea() and other operations that are necessary to implement this somewhat common functionality.

Header File: pixmap_helper.h

Definition at line 1265 of file pixmap_helper.c.

PXM_CreatePixmap()

Pixmap PXM_CreatePixmap	(	Display *	pDisplay,
		Drawable	dw,
		unsigned int	width,
		unsigned int	height,
		unsigned int	depth
	)

Wrapper for XCreatePixmap()

Parameters

pDisplay	The display associated with the specified window
dw	The Drawable associated with the Pixmap (this defines how to create it)
width	The width of the arc's elipse
height	The height of the arc's elipse
depth	The bit depth of the Pixmap - if 0, uses DefaultDepth(pDisplay, DefaultScreen(pDisplay))

Returns

A Pixmap with the appropriate characteristics, or None on error.

This function wraps XCreatePixmap() on X11 systems, and replicates its behavior elsewhere

Header File: pixmap_helper.h

PXM_FreePixmap()

int PXM_FreePixmap	(	Display *	pDisplay,
		Pixmap	pxImage
	)

Wrapper for XCreatePixmap()

Parameters

pDisplay	The display associated with the specified window
pxImage	the Pixmap image to free resources for

Returns

an integer indicating success or failure

This function wraps XFreePixmap() on X11 systems, and replicates its behavior elsewhere

Header File: pixmap_helper.h

PXM_GetIconPixmap()

Pixmap PXM_GetIconPixmap	(	int	idIcon,
		XPM_ATTRIBUTES *	pAttr,
		Pixmap *	pMask
	)

Create Icon pixmap pair using pre-defined resource ID.

Parameters

idIcon	The unique (numeric) identifier associated with the icon
pAttr	A pointer to an XpmAttributes structure when libXpm is present, or an XPM_ATTRIBUTES compatibility structure otherwise. For portability you should use the XPM_ATTRIBUTES definition, even when libXpm is guaranteed to be present.
pMask	A pointer to the variable that receives the 'Transparency Mask' pixmap for the icon (may be 'None'). This parameter may be NULL.

Returns

The pixmap identifier for the Icon image, or None on error.

Use this function whenever you need to load an icon using a pre-defined resource ID.

Header File: pixmap_helper.h

Definition at line 1020 of file pixmap_helper.c.

PXM_GetIconPixmapFromAtom()

Pixmap PXM_GetIconPixmapFromAtom	(	Atom	aIcon,
		XPM_ATTRIBUTES *	pAttr,
		Pixmap *	pMask
	)

Create Icon pixmap pair using a registered or pre-defined resource ID.

Parameters

aIcon	An atom that identifies a registered or pre-defined resource ID
pAttr	A pointer to an XpmAttributes structure when libXpm is present, or an XPM_ATTRIBUTES compatibility structure otherwise. For portability you should use the XPM_ATTRIBUTES definition, even when libXpm is guaranteed to be present.
pMask	A pointer to the variable that receives the 'Transparency Mask' pixmap for the icon (may be 'None'). This parameter may be NULL.

Returns

The pixmap identifier for the Icon image, or None on error.

Use this function whenever you need to load an icon using a pre-defined or registered Atom

Header File: pixmap_helper.h

Definition at line 1046 of file pixmap_helper.c.

PXM_GetImageDataLength()

static __inline__ unsigned long PXM_GetImageDataLength ( XImage *  pImage )

static

Returns the length of XImage data.

Parameters

pImage

A pointer to an XImage (must not be NULL)

Returns

The length of the data from the XImage

Call this to get the length of the data stored in an XImage. This data can be copied and stored elsewhere, as needed, or restored from a stored copy.

Header File: pixmap_helper.h

Definition at line 1009 of file pixmap_helper.h.

PXM_GetImageDataPtr()

static __inline__ void* PXM_GetImageDataPtr ( XImage *  pImage )

static

Returns pointer to XImage data.

Parameters

pImage

A pointer to an XImage (must not be NULL)

Returns

The data pointer element from the XImage

Call this to get the pointer to the data stored in an XImage. This data can be copied and stored elsewhere, as needed, or restored from a stored copy.

Header File: pixmap_helper.h

Definition at line 993 of file pixmap_helper.h.

PXM_HSVToRGB()

void PXM_HSVToRGB	(	int	iH,
		int	iS,
		int	iV,
		int *	piR,
		int *	piG,
		int *	piB
	)

Convert H, S, V values to R, G, B with 0-255 range.

Parameters

iH	the 'H' value (0-255)
iS	the 'S' value (0-255)
iV	the 'V' value (0-255)
piR	the returned Red value (0-255)
piG	the returned Green value (0-255)
piB	the returned Blue value (0-255)

Translate colors from HSV to RGB. Often this is desirable when doing color conversions, where you want to alter the brightness or saturation, but leave the color 'tone' as-is.
The 'hue' (H) information determines the color tone, the 'S' the saturatio, and the value (V) determines the brightness.

Header File: pixmap_helper.h

Definition at line 426 of file pixmap_helper.c.

PXM_ImageToPixmap()

Pixmap PXM_ImageToPixmap	(	Display *	pDisplay,
		Drawable	dw,
		XImage *	pImage,
		unsigned long	clrFGPixel,
		unsigned long	clrBGPixel
	)

Convert 'locally stored' XImage to 'server object' Pixmap.

Parameters

pDisplay	The display pointer. NULL uses the default display.
dw	The 'Drawable' for which the pixmap will be created.
pImage	The image to convert. This must be a valid image with non-zero height/width specified in the structure.
clrFGPixel	Foreground color pixel to use for monochrome images, typically BlackPixel(pDisplay, DefaultScreen(pDisplay))
clrBGPixel	Background color pixel to use for monochrome images, typically WhitePixel(pDisplay, DefaultScreen(pDisplay))

Returns

The resultant pixmap

This function is a convenient way to perform a standard operation that converts an Image to a Pixmap. A pixmap is a more efficient way of storing graphic data for subsequent display. Typically a pixmap will be cached for a window's Expose event handler, and is re-created when needed. Pixmaps are typically stored by the X server, so an operation that paints a window with a pixmap should perform more efficiently. However, a pixmap cannot be queried nor directly manipulated, while an XImage can.
The function returns a Pixmap identifier, or None. To delete the Pixmap, use XFreePixmap().

Header File: pixmap_helper.h

Definition at line 1139 of file pixmap_helper.c.

PXM_ImageToPixmap0()

Pixmap PXM_ImageToPixmap0	(	Display *	pDisplay,
		Drawable	dw,
		XImage *	pImage
	)

Convert 'locally stored' XImage to 'server object' Pixmap using default FG/BG colors for monochrome.

Parameters

pDisplay	The display pointer. NULL uses the default display.
dw	The 'Drawable' for which the pixmap will be created.
pImage	The image to convert. This must be a valid image with non-zero height/width specified in the structure.

Returns

The resultant pixmap

This function is a convenient way to perform a standard operation that converts an Image to a Pixmap. A pixmap is a more efficient way of storing graphic data for subsequent display. Typically a pixmap will be cached for a window's Expose event handler, and is re-created when needed. Pixmaps are typically stored by the X server, so an operation that paints a window with a pixmap should perform more efficiently. However, a pixmap cannot be queried nor directly manipulated, while an XImage can.
For monochrome images, the foreground color is black, and the background color is white.
The function returns a Pixmap identifier, or None. To delete the Pixmap, use XFreePixmap().

Header File: pixmap_helper.h

Definition at line 1211 of file pixmap_helper.c.

PXM_LoadPixmap()

Pixmap PXM_LoadPixmap	(	char *	ppXPM[],
		XPM_ATTRIBUTES *	pAttr,
		Pixmap *	pMask
	)

Create pixmap or pixmap pair using an XPM array.

Parameters

ppXPM	XPM definition array for the associated graphic
pAttr	A pointer to an XpmAttributes structure when libXpm is present, or an XPM_ATTRIBUTES compatibility structure otherwise. Pass a NULL pointer if you do not need the attributes. For portability you should use the XPM_ATTRIBUTES definition, even when libXpm is guaranteed to be present.
pMask	A pointer to the variable that receives the 'Transparency Mask' pixmap for the image or icon (may be 'None'). Pass a NULL pointer if you do not need the mask.

Returns

The pixmap identifier for the image, or None on error.

This function conveniently wraps XpmCreatePixmapFromData()

Header File: pixmap_helper.h

Definition at line 1072 of file pixmap_helper.c.

PXM_PixelToRGB()

void PXM_PixelToRGB	(	XStandardColormap *	pMap,
		XColor *	pColor
	)

Convert the pixel menber of an XColor to RGB.

Parameters

pMap	A pointer to the XStandardColormap for conversion
pColor	A pointer to the XColor structure. The 'pixel' member must be a valid pixel value

This function reads the pixel member from 'pColor' and calculates the RGB values between 0 and 65535, assigning them to the red, green, and blue members of the XColor structure along with appropriate flags.

Header File: pixmap_helper.h

Definition at line 688 of file pixmap_helper.c.

PXM_PixmapToImage()

XImage* PXM_PixmapToImage	(	Display *	pDisplay,
		Pixmap	pxImage
	)

Convert pixmap to image (a wrapper for XGetImage on a pixmap)

Parameters

pDisplay	The disply pointer. NULL uses the default display.
pxImage	The image pixmap

Returns

An XImage pointer allocated by Xlib, with data in ZPixmap format. Use XDestroyImage to dispose of it.

This function wraps the functionality of XGetImage with a simpler interface, returning an XImage * to an object allocated by Xlib. A pixmap is typically stored on the X Server, whereas an XImage is stored locally.
XGetImage creates an XImage using the same depth as the pixmap. The plane mask specified by this function includes all image data, and the origin is always 0,0. The XImage format is always ZPixmap.
The size of the pixmap is automatically determined using XGetGeometry(). As a side note, you could theoretically use this function to create an image from a pixmap for the purpose of determining its characteristics.
The function returns NULL on error. Use XDestroyImage to dispose of the XImage object.

Header File: pixmap_helper.h

Definition at line 1224 of file pixmap_helper.c.

PXM_RegisterAppIcons()

void PXM_RegisterAppIcons	(	char *	ppRegAppLarge[],
		char *	ppRegAppSmall[]
	)

Icon Registration for application 'large' and 'small' icons.

Parameters

ppRegAppLarge	XPM definition array for 'large' 36x36 icon, IDC_ICON_APP
ppRegAppSmall	XPM definition array for 'small' 19x19 icon, ID_APPLICATION

Use this function to register the application's icons for IDC_ICON_APP and ID_APPLICATION. In this way you can use both of them in dialog boxes and take advantage of PXM_GetIconPixmap() to create a pair of icon pixmaps whenever they are needed.

Header File: pixmap_helper.h

Definition at line 825 of file pixmap_helper.c.

PXM_RegisterPixmapResource()

int PXM_RegisterPixmapResource	(	Atom	aResource,
		char *	ppResource[]
	)

Register an icon (or pixmap) resource using an Atom.

Parameters

aResource	The Atom that will be used to identify the resource
ppResource	The XPM data array that defines the pixmap or icon

Returns

The function returns zero on success, non-zero on error.

This function allows you to register a pixmap or icon resource using an Atom. Typically this will be used by dialog boxes or menus to conveniently identify pixmap or icon images.

Header File: pixmap_helper.h

PXM_RGBToHSV()

void PXM_RGBToHSV	(	int	iR,
		int	iG,
		int	iB,
		int *	piH,
		int *	piS,
		int *	piV
	)

Convert R, G, B values to H, S, V with 0-255 range.

Parameters

iR	the Red value (0-255)
iG	the Green value (0-255)
iB	the Blue value (0-255)
piH	the returned 'H' value (0-255)
piS	the returned 'S' value (0-255)
piV	the returned 'V' value (0-255)

Translate colors from RGB to HSV. Often this is desirable when doing color conversions, where you want to alter the brightness or saturation, but leave the color 'tone' as-is.
The 'hue' (H) information determines the color tone, the 'S' the saturation, and the value (V) determines the brightness.

Header File: pixmap_helper.h

Definition at line 522 of file pixmap_helper.c.

PXM_RGBToPixel()

void PXM_RGBToPixel	(	XStandardColormap *	pMap,
		XColor *	pColor
	)

Icon Registration for application 'large' and 'small' icons.

Parameters

pMap	A pointer to the XStandardColormap for conversion
pColor	A pointer to the XColor structure. The 'red' 'green' and 'blue' members must be a valid RGB value

This function reads the red, green, and blue members from 'pColor' and calculates the pixel value. RGB entries are assumed to be between 0 and 65535, for each of the red, green, and blue members.

Header File: pixmap_helper.h

Definition at line 735 of file pixmap_helper.c.

PXM_RGBToYUV()

void PXM_RGBToYUV	(	int	iR,
		int	iG,
		int	iB,
		int *	piY,
		int *	piU,
		int *	piV
	)

Convert R, G, B values to Y, U, V with 0-255 range.

Parameters

iR	the Red value (0-255)
iG	the Green value (0-255)
iB	the Blue value (0-255)
piY	the returned 'Y' value (0-255)
piU	the returned 'U' value (0-255)
piV	the returned 'V' value (0-255)

Translate colors from RGB to YUV. Often this is desirable when doing color conversions, where you want to alter the brightness but leave the chroma information as-is.
The chrominance (U, V) information determines the color space, and the luminance (Y) determines the brightness. Altering the brightness 'Y' effectively leaves the chrominance information intact, while affecting how 'bright' a color appears. A color can also be 'faded' or 'saturated' by equally increasing or decreasing the 'U' and 'V' levels.

In YUV, for a white pixel, Y should be 255, U and V should both be 128
In RGB, a white pixel would have R, G, and B at 255.
Similarly, a black pixel should have R, G, B of 0, with Y at 255, and both U and V 128.
However, the actual YUV calculations return 'iY' as 16 for 'black', and 235 for 'white'. Anything outside of this Y range SHOULD result in 'faded' colors (towards black or white). This algorithm has been tested for RGB values between 0 and 255, respectively, and the inverse calculation results in a deviation of at most '1' for R, G, or B, from the original RGB value.

Header File: pixmap_helper.h

Definition at line 371 of file pixmap_helper.c.

PXM_StandardColormapFromColormap()

static __inline__ XStandardColormap* PXM_StandardColormapFromColormap ( Display *  pDisplay, Colormap  colormap  )

static

create temporary XStandardColormap from a Colormap

Parameters

pDisplay	The Display * associated with the color map (or NULL for default)
colormap	The Colormap value (NOTE: it must be of the same type as the default colormap for the associated Display)

Returns

A pointer to an internal (static) XStandardColormap structure. This value should not be cached.

This function returns a pointer to a static XStandardColormap structure assigned to a specified Colormap, using the specified Display (or default if NULL is specified for the 'D' parameter) for color-related parameters that are part of the XStandardColormap structure.

This is a convenience function for things like PXM_PixelToRGB() and PXM_RGBToPixel(), where you may have a Colormap but you need an XStandardColormap.

Definition at line 179 of file pixmap_helper.h.

PXM_YUVToRGB()

void PXM_YUVToRGB	(	int	iY,
		int	iU,
		int	iV,
		int *	piR,
		int *	piG,
		int *	piB
	)

Convert Y, U, V values to R, G, B with 0-255 range.

Parameters

iY	the 'Y' value (0-255)
iU	the 'U' value (0-255)
iV	the 'V' value (0-255)
piR	the returned Red value (0-255)
piG	the returned Green value (0-255)
piB	the returned Blue value (0-255)

Translate colors from YUV to RGB. Often this is desirable when doing color conversions, where you want to alter the brightness but leave the chroma information as-is.
The chrominance (U, V) information determines the color space, and the luminance (Y) determines the brightness. Altering the brightness 'Y' effectively leaves the chrominance information intact, while affecting how 'bright' a color appears. A color can also be 'faded' or 'saturated' by equally increasing or decreasing the 'U' and 'V' levels.
In YUV, for a white pixel, Y should be 255, U and V should both be 128
In RGB, a white pixel would have R, G, and B at 255.
Similarly, a black pixel should have R, G, B of 0, with Y at 255, and both U and V 128.
However, the actual YUV calculations return 'iY' as 16 for 'black', and 235 for 'white'. Anything outside of this Y range SHOULD result in 'faded' colors (towards black or white). This algorithm has been tested for RGB values between 0 and 255, respectively, and the inverse calculation results in a deviation of at most '1' for R, G, or B, from the original RGB value.

Header File: pixmap_helper.h

Definition at line 399 of file pixmap_helper.c.

WB_icos()

char WB_icos

(

int

iVal

)

integer 127 * cos(iVal * pi / 512) calculation via lookup table

Parameters

iVal	An integer between 0 and 1024 that corresponds to an angle, where 0-1024 would be 0-2pi radians

Returns

An signed char cosine value between -127 and 127

Use this function when an approximate cosine is needed within Quadrant I

Definition at line 338 of file pixmap_helper.c.

WB_icos0()

unsigned char WB_icos0

(

unsigned char

iVal

)

integer 255 * cos(iVal * pi / 512) calculation via lookup table (legacy, to be removed?)

Parameters

iVal	An unsigned integer between 0 and 255 that corresponds to an angle, where 0-256 would be 0-pi/2 radians. (a value of 256 would always be 0)

Returns

An integer cosine value between 0 and 255, where WB_icos(0) would return 255, WB_icos(64) would return zero

Use this function when an approximate cosine is needed within Quadrant I

Definition at line 179 of file pixmap_helper.c.

WB_isqrt()

unsigned char WB_isqrt

(

unsigned char

iVal

)

integer square root of a value 0-255

Parameters

iVal	An integer between 0 and 255, for which a square root will be returned

Returns

The integer square root of 'iVal'.

Use this function when an approximate square root of an integer between 0 and 255 is needed, and you don't want to waste CPU cycles calculating it with floating point numbers.

Definition at line 153 of file pixmap_helper.c.

WBSimpleAntiAliasImage()

void WBSimpleAntiAliasImage	(	const XStandardColormap *	pMap,
		XImage *	pImage,
		unsigned long	lPixel,
		WB_GEOM *	pGeom
	)

Simple anti-alias of an XImage using foreground pixel color.

Parameters

pMap	A const pointer to an XStandardColormap. May be NULL to use the system default colormap
pImage	A pointer to an XImage (must not be NULL)
lPixel	A pixel value equal to the foreground color for anti-aliasing
pGeom	A pointer to a WB_GEOM structure (may be NULL, implying the entire image)

Call this to do a 'simple anti-alias' on the data stored in an XImage. The algorithm will look for corners that use the foreground color, and fill them in with an appropriate calculated color value based on the current pixel in that spot.

This function is expected to be used with lines and text, following a drawing operation.

Header File: pixmap_helper.h

Definition at line 1458 of file pixmap_helper.c.

WBSimpleAntiAliasPixmap()

void WBSimpleAntiAliasPixmap	(	Display *	pDisplay,
		const XStandardColormap *	pMap,
		Pixmap	pxImage,
		unsigned long	lPixel,
		WB_GEOM *	pGeom
	)

Simple anti-alias of a Pixmap using foreground pixel color.

Parameters

pDisplay	A pointer to a Display (NULL implies the default display)
pMap	A const pointer to an XStandardColormap. May be NULL to use the system default colormap
pixmap	A pixmap containing the image data (must not be None)
lPixel	A pixel value equal to the foreground color for anti-aliasing
pGeom	A pointer to a WB_GEOM structure (may be NULL, implying the entire pixmap)

Call this to do a 'simple anti-alias' on the data stored in an XImage. The algorithm will look for corners that use the foreground color, and fill them in with an appropriate calculated color value based on the current pixel in that spot.

This function is expected to be used with lines and text, following a drawing operation.

Header File: pixmap_helper.h

Definition at line 1344 of file pixmap_helper.c.

WBXCopyImage()

XImage* WBXCopyImage	(	Display *	pDisplay,
		XImage *	pImage
	)

Make a copy of an XImage.

Parameters

pDisplay	A pointer to the Display, or NULL to use the default display
pImage	A pointer to an XImage

Returns

An XImage that is a copy of the original

Use this function to make a copy of an XImage via XCreateImage

Header File: pixmap_helper.h

Definition at line 1709 of file pixmap_helper.c.

WBXDestroyImage()

int WBXDestroyImage

(

XImage *

pImage

)

Destroy an XImage - call this instead of XDestroyImage()

Parameters

pImage

A pointer to an XImage that may have been allocated using shared memory.

Returns

A non-zero value on error, or zero on success

Use this function in lieu of XDestroyImage() for an image that was returned from one of the API functions in the X11workbench Toolkit. In some cases, the XImage may have been created using shared memory. This would mean that the shared memory will need to be free'd up correctly using the WBFreeShm() (and related) utility functions.

Header File: pixmap_helper.h

Definition at line 1693 of file pixmap_helper.c.

WBXGetImage()

XImage* WBXGetImage	(	Display *	pDisplay,
		Drawable	dw,
		int	x,
		int	y,
		unsigned int	width,
		unsigned int	height,
		unsigned long	plane_mask,
		int	format
	)

Read contents of a Drawable onto an XImage.

Parameters

pDisplay	The disply pointer. NULL uses the default display.
dw	A Drawable upon which to perform the action
x	The X coordinate within the source Drawable (upper, left corner)
y	The Y coordinate within the source Drawable (upper, left corner)
width	The width of the image data to transfer
height	The height of the image data to transfer
plane_mask	The 'plane_mask' of the bits to transfer
format	The format of the image - may be XYBitmap, XYPixmap, or ZPixmap. XYBitmap is monochrome. ZPixmap is more efficient than XYPixmap, but requires more memory.

Returns

A pointer to a newly created XImage containing the copied image. See XGetImage() in the X11 API documentation

When libXext is being used, this function wraps XShmCreateImage() and XShmGetImage(). Otherwise, it calls XGetImage().

The resulting XImage may use shareable memory. If it does, the memory is managed using the WBAllocShm() (and related) functions from the X11workbench Toolkit. You will need to use WBXDestroyImage to destroy the XImage returned by this function, rather than XDestroyImage(), to avoid any memory management conflicts.

Header File: pixmap_helper.h

Definition at line 1607 of file pixmap_helper.c.

WBXPutImage()

int WBXPutImage	(	Display *	pDisplay,
		Drawable	dw,
		WBGC	gc,
		XImage *	pImage,
		int	src_x,
		int	src_y,
		int	dest_x,
		int	dest_y,
		unsigned int	width,
		unsigned int	height
	)

Write contents of an XImage onto a Drawable.

Parameters

pDisplay	The disply pointer. NULL uses the default display.
dw	A Drawable upon which to perform the action
gc	A GC with which to perform the action
pImage	A pointer to an XImage with which to perform the action
src_x	The X coordinate within the source image (upper, left corner)
src_y	The Y coordinate within the source image (upper, left corner)
dest_x	The X coordinate within the destination Drawable (upper, left corner)
dest_y	The Y coordinate within the destination Drawable (upper, left corner)
width	The width of the image data to transfer
height	The height of the image data to transfer

Returns

A non-zero value on failure, zero on success. See XPutImage() in the X11 API documentation

When libXext is being used, this function wraps XShmPutImage(). Otherwise, it calls XPutImage().

Header File: pixmap_helper.h

Definition at line 1580 of file pixmap_helper.c.

WBXShmQueryExtension()

int WBXShmQueryExtension

(

Display *

pDisplay

)

Indicates whether the 'XShm' extensions are available (libXext)

Parameters

pDisplay

The disply pointer. NULL uses the default display.

Returns

A non-zero value if the extensions are available for the given display; otherwise, zero

When libXext is being used, this function wraps XShmQueryExtension(). Otherwise, it returns zero.

Header File: pixmap_helper.h

Definition at line 1574 of file pixmap_helper.c.