[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 AIXwindows Programming Guide

Chapter 6. Enhanced X-Windows Screen Capture Library

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

Screen Capture Functions

The following functions are available in the Enhanced X-Windows screen capture library:

Capture Types

The following two families of function for capturing data from the screen are available:

window capture The screen region to be returned is identified as an X-Windows id. It is treated as the parent of a window hierarchy, and the region of the screen bounded by that window's borders is captured and returned. (Call XMapRaised to ensure the window is exposed.)
region capture The screen region to be captured is identified by its upper left and lower right coordinates. All windows overlapping the defined region, including the root window, are checked. Any completely obscured windows are skipped. Otherwise, the intersection of the window and the indicated region are read and added to a combined memory map.

Returned Data Formats

There are four returned data options:

Data Structures

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.

File I/O Functions

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.

C Programming Interface

The following C interface and structures are available in the Enhanced X-Windows screen capture library:

Input Data Structure

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.

Output Data Formats

The screen grabbing routines return one to three data formats.

XImage The XWindows XImage structure. It contains the pixel data for the Image, and it is returned by all screen capture routines and kread on a successful call.
Color_Array A XColor array. It is returned by both the kread and screen capture routines when the resultant XImage is a pseudo color visual type.
numcolors An integer indicating the number of colors returned in the color array. It is not necessarily the size of the color array. For direct color visuals the returned value will always be zero.

Allocating Storage for Returned 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.

Freeing Allocated Data Structures

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.

Data Storage Philosophy

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.

Screen Capture Routines

The following screen capture routines are available in the Enhanced X-Windows screen capture library:

kgetwindow

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  */
             ) ;

kgetregion

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  */
            ) ;

kgetwindow_pseudo

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                    */
       ) ;

kgetregion_pseudo

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  */
         ) ;

kgetwindow_bestdepth

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   */
         ) ; 

kgetregion_bestdepth

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  */
        ) ;

kgetwindow_8

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                    */
        ) ;

kgetregion_8

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                   */
        ) ;

File I/O Routines

The following file I/O routines are available in the Enhanced X-Windows screen capture library:

Output File Formats Defined in interface.h

#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           */ 

kread

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             */
     ) ;

kwrite

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        */
      ) ;

Utility Routines

The following utility routines are available in the Enhanced X-Windows screen capture library:

init_true_color

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       */
     ) ;

rubberband

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    */
      ) ;

select_window

Returns a window ID from a mouse click.

extern Window 
    select_window( Display  *dpy );

Ship Files

The following files are available in the Enhanced X-Windows screen capture library:


[ Previous | Next | Contents | Glossary | Home | Search ]