X11 Work Bench Toolkit  1.0
Pixmap utility functions

Data Structures

struct  _XPM_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 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 _XPM_ATTRIBUTES_ XPM_ATTRIBUTES
 Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use. More...
 

Functions

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_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_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...
 
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...
 
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

#define RGB255_TO_XCOLOR (   R,
  G,
  B,
 
)
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
Rred color, 0-255
Ggreen color, 0-255
Bblue color, 0-255
XAn 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 95 of file pixmap_helper.h.

#define RGB_TO_XCOLOR (   R,
  G,
  B,
 
)
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
Rred color, 0-65535
Ggreen color, 0-65535
Bblue color, 0-65535
XAn 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 111 of file pixmap_helper.h.

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

Platform helper macro to create a pixmap from data.

Parameters
AA pointer to the Display
BThe Window ID
CA pointer to an array of 'char *' that represents the pixmap data
DA pointer to a Pixmap into which the data will be saved, or NULL
EA pointer to the Pixmap into which the mask data will be saved (icons only), or NULL
FA 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 672 of file platform_helper.h.

#define XPM_FREE_ATTRIBUTES (   pAttr)    /* does nothing */

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

Parameters
pAttrA 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 685 of file platform_helper.h.

Typedef Documentation

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 "&ndash;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 _XPM_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'.

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

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
pDisplayA pointer to the display to use when creating the pixmaps
wIDA window used as a 'drawable' reference when creating the pixmaps
aDataAn 'xpm' pixmap array, using the standard format generated by utilities like 'gimp'
pPixmapPointer to the variable to receive the Pixmap. If the function fails, this will be 'None'
pMaskPointer to the variable to receive the transparency mask Pixmap. This may be 'None' if there is no transparency mask
pAttrPointer 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 1848 of file platform_helper.c.

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

Create Icon pixmap pair using pre-defined resource ID.

Parameters
idIconThe unique (numeric) identifier associated with the icon
pAttrA 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.
pMaskA 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 938 of file pixmap_helper.c.

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

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

Parameters
aIconAn atom that identifies a registered or pre-defined resource ID
pAttrA 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.
pMaskA 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 964 of file pixmap_helper.c.

static __inline unsigned long PXM_GetImageDataLength ( XImage *  pImage)
static

Returns the length of XImage data.

Parameters
pImageA 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 398 of file pixmap_helper.h.

static __inline void* PXM_GetImageDataPtr ( XImage *  pImage)
static

Returns pointer to XImage data.

Parameters
pImageA 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 382 of file pixmap_helper.h.

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

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

Parameters
pDisplayThe display pointer. NULL uses the default display.
dwThe 'Drawable' for which the pixmap will be created.
pImageThe image to convert. This must be a valid image with non-zero height/width specified in the structure.
clrFGPixelForeground color pixel to use for monochrome images, typically BlackPixel(pDisplay, DefaultScreen(pDisplay))
clrBGPixelBackground 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 1057 of file pixmap_helper.c.

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
pDisplayThe display pointer. NULL uses the default display.
dwThe 'Drawable' for which the pixmap will be created.
pImageThe 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 1128 of file pixmap_helper.c.

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

Create pixmap or pixmap pair using an XPM array.

Parameters
ppXPMXPM definition array for the associated graphic
pAttrA 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.
pMaskA 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 990 of file pixmap_helper.c.

void PXM_PixelToRGB ( XStandardColormap *  pMap,
XColor *  pColor 
)

Convert the pixel menber of an XColor to RGB.

Parameters
pMapA pointer to the XStandardColormap for conversion
pColorA 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

Header File: pixmap_helper.h

Definition at line 182 of file pixmap_helper.c.

XImage* PXM_PixmapToImage ( Display *  pDisplay,
Pixmap  pxImage 
)

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

Parameters
pDisplayThe disply pointer. NULL uses the default display.
pxImageThe 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 1141 of file pixmap_helper.c.

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

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

Parameters
ppRegAppLargeXPM definition array for 'large' 36x36 icon, IDC_ICON_APP
ppRegAppSmallXPM 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 743 of file pixmap_helper.c.

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

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

Parameters
aResourceThe Atom that will be used to identify the resource
ppResourceThe 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

void PXM_RGBToPixel ( XStandardColormap *  pMap,
XColor *  pColor 
)

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

Parameters
pMapA pointer to the XStandardColormap for conversion
pColorA 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 between 0 and 65535, for each of the red, green, and blue members.

Header File: pixmap_helper.h

Definition at line 665 of file pixmap_helper.c.

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
iRthe Red value (0-255)
iGthe Green value (0-255)
iBthe Blue value (0-255)
piYthe returned 'Y' value (0-255)
piUthe returned 'U' value (0-255)
piVthe 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 126 of file pixmap_helper.c.

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
iYthe 'Y' value (0-255)
iUthe 'U' value (0-255)
iVthe 'V' value (0-255)
piRthe returned Red value (0-255)
piGthe returned Green value (0-255)
piBthe 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 154 of file pixmap_helper.c.