The Enhanced X-Windows screen capture library provides a general purpose API for grabbing images from the screen in a format that can be used with other applications. It also provides a method for storing data on disk (for retrieval and export to other standardized formats).
The following functions are available in the Enhanced X-Windows screen capture library:
The following two families of function for capturing data from the screen are available:
There are four returned data options:
All image data returned is in XImage format. For visuals that require color tables, the color table is returned as an XColor array. The size of the color table is returned as an int.
You can provide storage for XImage or rely on the screen capture API to allocate storage. In either case, the application calls XDestroyImage to free it.
You can provide storage for XColor, or rely on the screen capture API to allocate storage. In either case, the application calls the C library function free to free it.
Output is to a stream, the ID of which is provided by the calling application. The calling application must ensuring the stream is open and writable by the application before calling the output functions. The calling application must also flush and close the stream after calling the output functions.
The following C interface and structures are available in the Enhanced X-Windows screen capture library:
The KDATA structure allows the interface to be expanded without modification to existing code. It also allows the application to pass in new flags as they are defined.
The screen grabbing routines return one to three data formats.
If the screen grab routines are called with a null pointer for the XImage structure, the structure is allocated by the API. Sufficient data is allocated for the XImage data field to represent the image as 24 Bit per pixel true color. If the XImage pointer is not null, it is assumed to point to a correct XImage structure with a data field sufficiently large enough for the current call. The application must ensure this is true. The kread routine must always be called with a null XImage pointer. It will allocate and return the storage on a succesful call. The application must free XImage storage by calling XDestroyImage.
If the screen grab routines are called with a null pointer for the Color_Array structure, the structure is allocated by the API with enough storage for K_DEF_CTAB_SIZE colors (4096). If the pointer is not null, the API assumes that there is sufficient storage available for numcolor XColor entries in the table. If the number of colors exceeds numcolors, an error is returned, and any data allocated by this API call will be freed. The kread routine must always be called with a null colormap pointer. It will allocate sufficient storage on a successful call. The calling applications call free to return the storage.
The storage for numcolors must be allocated by the application. If the pointer is null, an error is returned. If the screen capture routines are called with a color table previously allocated by the API, the contents of memory referenced by this pointer should contain K_DEF_CTAB_SIZE.
Note: The default value for K_DEF_CTAB_SIZE is 4096. You can overwrite this value by setting the environment variable KCTABSIZE to the appropriate value. If this value is set to less than 256, it will default to 256.
The API frees allocated data structures if an error condition is detected in the same call in which memory is allocated. Otherwise, the applications must call XDestroyImage to free the XImage structure.
This API facilitates animation generators and interactive window snooping. If an application repeatedly grabs the same window, or repeatedly grabs the same size region, the data storage allocations need to occur only once. If an application repeatedly grabs different windows, or different size regions, the data storage must be freed and reallocated each call.
The following screen capture routines are available in the Enhanced X-Windows screen capture library:
This function returns a 24 bit true color Ximage of a window tree hierarchy given the XWindow ID of the parent. Performance in this function is optimal for 24 bit visuals and for window hierarchy that include multiple colormaps. This function returns accurate data for all visuals on all servers regardless of server or window depth or visual types and combinations of the same. The return code is non zero if an error occurs.
xtern int
kgetwindow (
Display *dpy, /* IN: pointer to display */
Window window, /* IN: window id of parent of tree */
KDATA *kdata, /* IN: ptr to additional info */
XImage** ximage /* OUT: pointer to ximage pointer */
) ;
This function returns a 24 bit true color Ximage of a rectangular region of the default screen of display dpy. The input parameters xul, yul, xlr, and ylr indicate the upper left x and y cordinates and lower right x and y coordinates of the window. Performance in this function is optimal for 24 bit visuals and for regions that include multiple colormaps. This function returns accurate data for all visuals on all servers regardless of server or window depth or visual types and combinations of the same. The return code is non zero if an error occurs.
int
kgetregion(
Display *dpy, /* IN: Display pointer */
int xul, /* IN: x upper left */
int yul, /* IN: y upper left */
int xlr, /* IN: x lower right */
int ylr, /* IN: y lower right */
KDATA *kdata, /* IN: ptr to additional info */
XImage ** Ximage /* OUT: ptr to Ximage structure */
) ;
This function returns an Ximage of a window tree hierarchy given the Xwindow ID of the parent window. The image returned is 8 bit pseudo color if the number of colors is less than or equal to 255; otherwise it is 24 bit pseudo color. This function is optimal for grabbing 8 bit window hierarchies that only share a single color map. Additionally, it provides data in a format that is optimal for conversion to color table oriented file formats. This function returns accurate data for all visuals on all servers regardless of server, window depth, or visual types, and combinations of the same. If the entire region of the screen grabbed is represented by a single installed pseudo color visual, the resource ID of that visual's colormap is returned in colormap; otherwise, 0 is returned in colormap. The return code is non zero if an error occurs.
int
kgetwindow_pseudo(
Display *dpy, /* IN: pointer to display */
Window window, /* IN: window id of parent of tree */
KDATA *kdata, /* IN: ptr to additional info */
XImage** ximage, /* OUT: pointer to ximage pointer */
XColor** color_array, /* OUT: array of colors used */
int* numcolors, /* OUT: ptr to area to write */
Colormap* colormap /* OUT: ID of installed colormap
if valid */
) ;
This function returns an Ximage of a rectangular region of a display:screen given corner points of the region. The image returned is 8 bit pseudo color if the number of colors is less than or equal to 255; otherwise it is 24 bit pseudo color. This function is optimal for grabbing 8 bit window hierarchies that only share a single color map. Additionally, it provides data in a format that is optimal for conversion to color table oriented file formats. This function returns accurate data for all visuals on all servers regardless of server, window depth, or visual types, and combinations of the same. If the entire region of the screen grabbed is represented by a single installed pseudo color visual, the resource ID of that colormap is returned in colormap; otherwise, 0 is returned in colormap. The return code is non zero if an error occurs.
int
kgetregion_pseudo(
Display *dpy, /* IN: Display pointer */
int xul, /* IN: x upper left */
int yul, /* IN: y upper left */
int xlr, /* IN: x lower right */
int ylr, /* IN: y lower right */
KDATA *kdata, /* IN: ptr to additional info */
XImage ** Ximage, /* OUT: image structure */
XColor** color_array, /* OUT: array of colors used */
int* numcolors, /* OUT: ptr to area to write # of
colors used */
Colormap* colormap /* OUT: ID of colormap loaded in X */
) ;
This function returns an Ximage of a window tree hierarchy given the Xwindow ID of the parent window. The image returned is 8 bit pseudo color if the number of colors is less than or equal to 255; otherwise, it is 24 bit true color. This function is optimal for grabbing 8 bit window hierarchies that only share a single color map. Additionally, it provides data in a format that offers the best performance for displaying on displays that support both 8 and 24 bit visuals. This function returns accurate data for all visuals on all servers regardless of server, window depth, or visual types, and combinations of the same. The return code is non zero if an error occurs.
int
kgetwindow_bestdepth(
Display *dpy, /* IN: pointer to display */
Window window, /* IN: window id of parent of tree */
KDATA *kdata, /* IN: ptr to additional info */
XImage** ximage, /* OUT: pointer to ximage pointer */
XColor** color_array, /* OUT: array of colors used */
int* numcolors /* OUT: ptr to area to write # of
colors used */
Colormap* colormap /* OUT: ID of colormap loaded in X */
) ;
This function returns an Ximage of a rectangular region of a display:screen, given corner points of the region. The image returned is 8 bit pseudo color if the number of colors is less than or equal to 255; otherwise, it is 24 bit true color. This function is optimal for grabbing 8 bit window regions that only share a single colormap. Additionally, it provides data in a format that is optimal for conversion to color table oriented file formats. This function returns accurate data for all visuals on all servers regardless of server, window depth, or visual types, and combinations of the same. The return code is non zero if an error occurs.
int
kgetregion_bestdepth(
Display *dpy, /* IN: Display pointer */
int xul, /* IN: x upper left */
int yul, /* IN: y upper left */
int xlr, /* IN: x lower right */
int ylr, /* IN: y lower right */
KDATA *kdata, /* IN: ptr to additional info */
XImage ** Ximage, /* OUT: image structure */
XColor** color_array, /* OUT: array of colors used */
int* numcolors, /* OUT: ptr to area to write # of
colors used */
Colormap* colormap /* OUT: ID of colormap loaded in X */
) ;
This function returns an Ximage of a window tree hierarchy given the Xwindow ID of the parent window. The image returned is 8 bit pseudo color. If the number of colors is less than or equal to 255, this function returns accurate data. Otherwise, it applies a color reduction algorithm specified in the KDATA structure to compress the number of colors to 255. This function is optimal for producing images for display on devices that do not support greater than 8 bits per pixel. If the entire region of the screen grabbed is represented by a single installed pseudo color visual, the resource ID of that colormap is returned in colormap; otherwise, 0 is returned in colormap. The return code is non zero if an error occurs.
int
kgetwindow_8(
Display *dpy, /* IN: pointer to display */
Window window, /* IN: window id of parent of tree */
KDATA *kdata, /* IN: ptr to additional info */
XImage** ximage, /* OUT: pointer to ximage pointer */
XColor** color_array, /* OUT: array of colors used */
int* numcolors, /* OUT: ptr to area to write # of colors used */
Colormap* colormap /* OUT: ID of installed colormap
if valid */
) ;
This function returns an Ximage of a rectangular region of a display:screen, given corner points of the region. The image returned is 8 bit pseudo color. If the number of colors is less than or equal to 255, this function returns accurate data. Otherwise, it applies a color reduction algorithm specified in the KDATA structure to compress the number of colors to 255. This function is optimal for producing images for display on devices that does not support greater than 8 bits per pixel. If the entire region of the screen grabbed is represented by a single installed pseudo color visual, the resource ID of that colormap is returned in colormap; otherwise, 0 is returned in colormap. The return code is non zero if an error occurs.
int
kgetregion_8(
Display *dpy, /* IN: Display pointer */
int xul, /* IN: x upper left */
int yul, /* IN: y upper left */
int xlr, /* IN: x lower right */
int ylr, /* IN: y lower right */
KDATA *kdata, /* IN: ptr to additional info */
XImage ** Ximage, /* OUT: image structure */
XColor** color_array, /* OUT: array of colors used */
int* numcolors, /* OUT: ptr to area to write # of colors used */
Colormap* colormap /* OUT: id of installed colormap
if valid */
) ;
The following file I/O routines are available in the Enhanced X-Windows screen capture library:
#define K_PS4 0x01 /* Postscript 4 Bit greyscale */ #define K_PS8 0x02 /* Postscript 8 Bit colormapped */ #define K_PS24 0x04 /* Postscript 24 Bit RGB */ #define K_TIFF4 0x11 /* TIFF 4 Bit greyscale */ #define K_TIFF8 0x12 /* TIFF 8 Bit colormapped */ #define K_TIFF24 0x14 /* TIFF 24 Bit RGB */ #define K_XWD 0x20 /* x window dump format */
Reads an xwd formatted stream and returns the contents as an Ximage and array of Xcolors. If the visual type of the xwd stream is DirectColor, the numcolors returned will be 0 and there will be no memory allocated for the colormap. If the visual type is PseudoColor storage for the colormap is allocated. In all cases storage for the ximage will be allocated. If the visual type is not PseudoColor or DirectColor, an error is returned. If the call is successful, the number of bytes read will be returned on the stack. If an error occurs 0xFFFFFFFF (-1) is returned and any storage allocated by the function is freed.
extern int
kread(
int FileDescriptor, /* IN: File discriptor to read from */
XImage** ximage, /* OUT: Ptr to XImage structure */
int *visualtype, /* OUT: Visual type from X.h */
int *numcolors, /* OUT: Highest entry used in table */
XColor* *colormap, /* OUT: Array of Xcolors */
) ;
Outputs the Ximage to the open stream identified by the FileDescriptor parameter. Data formatted according to the Kfiletype parameter. The numcolors and colormap are ignored for direct color visuals. The Xvisual type must be either pseudocolor or direct color. On a successful call the number of bytes written is returned. If an error occurs 0xFFFFFFFF (-1) is returned.
extern int
kwrite(
int FileDescriptor, /* IN: File discriptor to write to */
XImage* ximage, /* IN: Ptr to XImage structure */
int visualtype, /* IN: Visual type from X.h */
int numcolors, /* IN: Highest entry used in table */
XColor* colormap, /* IN: Array of Xcolors */
int Kfiletype, /* IN: Format of output file */
) ;
The following utility routines are available in the Enhanced X-Windows screen capture library:
Opens a 24 bit true color window on any display that supports it .
extern int
init_true_color(
Display *dpy, /* ptr to display on which to open win */
Window *window, /* pointer to win id to be returned */
int w, /* width of the window in pixels */
int h /* height of the window in pixels */
) ;
Returns a rectangle selected by rubberbanding on the screen.
void
rubberband(
Display* dpy, /* IN: Display */
int* xul, /* OUT: x upper left */
int* yul, /* OUT: y upper left */
int* xlr, /* OUT: x lower right */
int* ylr /* OUT: y lower right */
) ;
Returns a window ID from a mouse click.
extern Window
select_window( Display *dpy );
The following files are available in the Enhanced X-Windows screen capture library: