./_Man_Openwin_html/html3/xil_create_from

Manual page for xil_create_from_window(3)

xil_create_from_window, xil_create_from_device, xil_create_double_buffered_window - create device images

SYNOPSIS

#include <xil/xil.h>

XilImage xil_create_from_window ( XilSystemState State,
Display *display,
Window window);

XilImage xil_create_from_device ( XilSystemState State,
char *devicename,
XilDevice deviceObj);

XilImage xil_create_double_buffered_window ( XilSystemState system_state,
Display*display,
Window window);

DESCRIPTION

These routines create images that are tied to particular devices. They allow X windows and various image input and output devices to be treated as if they were ordinary XIL images. After an image is created with the routines, the image can be read from the device or written to it by using the device as the source or destination of an image processing operation.

xil_create_from_window () creates an image associated with the specified X window. Images can then be copied to this image for display. The default origin for images created with this function is (0.0, 0.0), and the default region of interest (ROI) is NULL.

xil_create_from_device () creates an image associated with the device named devicename. The parameter deviceObj is the handle to the device object associated with this device type. The device object is created with the xil_device_create.3 function and is used to store device-initialization values. If the device doesn't require attribute initialization, you may pass NULL for the deviceObj parameter. The supplier of the device handler should indicate whether the device requires attribute initialization.

xil_create_double_buffered_window () creates an image associated with the specified X window in the same way that xil_create_from_window () does, except that it attempts to establish hardware double-buffering. If hardware double-buffering is not supported for the device, xil_create_double_buffered_window () returns NULL, and the developer must catch the failure and call xil_create_from_window () instead. At construction time the back buffer is the active buffer.

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer's Guide.

EXAMPLES

Create an XIL display image and copy it to a display image.

    XilSystemState State;
    XilImage display_image;
    XilImage image0;
    Display* display;
    Window window;

    /* Create an XIL display image from existing X display and window */
    display_image = xil_create_from_window(State, display, window);

    /* Copy image0 to the display */
    xil_copy(image0, display_image);

Attempt to create a double-buffered window:

    XilSystemState State;
    XilImage display_image;
    XilImage image0;
    Display* display;
    Window window;
    Xil_boolean is_double_buffered = TRUE;

    /* Create an XIL display image from existing X display and window */
    if(display_image = xil_create_double_buffered_window(State,
                                              display,window) == NULL) {
    
        is_double_buffered = FALSE;
        display_image = xil_create_from_window(State, display, window);
    }

    /* Copy image0 to the display */
    xil_copy(image0, display_image);

    if(is_double_buffered) {
        /*  Move the back buffers contents to the front buffer */
        xil_swap_buffers(display_image);
    }

NOTES

As with standard images, device images can have origins, color spaces, and so on. Subsets of device images can be referenced or written using ROIs or child images.

To resize a window that contains an XilImage, destroy the XilImage attached to the window, resize the window, wait for a ConfigureNotify event to ensure the XResizeWindow(3) is complete, and then call xil_create_from_window () to recreate the image in the new window size. Detaching and attaching an XIL image to a window is a very lightweight process.

XIL does not support using an X window's backing_store attribute to maintain an image in the window when the window is obscured or unmapped (see the Xlib Programming Manual). Your code should always check for an Expose event and take the appropriate measures for displaying the image again when the window is exposed.