xvdisplay(3)

NAME
xvdisplay - displaying Khoros images

DESCRIPTION
xvdisplay is the Khoros Library which contains utilities to aid in displaying Khoros images on workstations under X Windows, Release 11, Version 4. The xvdisplay library must be used in conjunction with the xvforms and xvutils libraries.

As a general rule, the Khoros libraries used by xvroutines each must have some way of storing information about and later identifying the current environment of the application that is using them. The vexpr and xvgraphics libraries use an integer id for this purpose, while the xvforms library uses a pointer to a xvf_form structure for the same reason. The xvdisplay library uses a DisplayStructure in which to store and reference the various necessary necessary information about the calling xvroutine's current environment.

ALL programs that utilize these routines MUST link against:

-lXaw -lXmu -lXt -lXext -lX11

ALL programs that utilize these routines MUST include the statement:

#include "xvdisplay.h"
#include "xvforms.h"

For an explanation of all the following routines in greater detail, with explanations of all arguments to each routine, please see the section on xvdisplay in the Khoros Programmer's Manual, chapter 8, Libraries.

AVAILABLE ROUTINES

xvd_initialize()

This routine initializes global variables that will be used during future calls to the xvdisplay library. It initializes the screen, the root window, and the default screen. A graphics context for drawing is created, and foreground and background pixels are given default values. The number of colors available on the screen is determined, as well as the type of visual being dealt with. In addition, a cursor is created for use with the raster widget. This routine MUST be called before ANY other calls to the xvdisplay library are made.

xvd_initialize(display)

Display *display;

xvd_init_xvdisplay()

This routine creates and initializes the xvdisplay structure. It doesn't create any X resources associated with the image, shape mask, clip mask, overlay, or colormap, and it does not display the image. Returns a pointer to the completed DisplayStructure which will be needed for subsequent calls to the xvdisplay library.

DisplayStructure *xvd_init_xvdisplay(display, image, shape, clip, overlay,
                        private_cmap, read_only, shape_parent, colormap)

Display *display;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;
int private_cmap;
int read_only;
int shape_parent;
Colormap colormap;

xvd_build_xvdisplay()

This routine builds up the xvdisplay structure with all X resources associated with the image, shape mask, clip mask, and so on. It does not, however, create a window in which to display the image. It is required that the DisplayStructure be already allocated and initialized with a prior call to xvd_init_xvdisplay().

xvd_build_xvdisplay(xvdisplay)

DisplayStructure *xvdisplay;

xvd_init_image()

IMPORTANT NOTE: Due to enhancements that have been made to the xvdisplay library, this routine has been outdated as of Patch2. It still exists for backwards compatibility with those existing applications that call it; however, programmers that have existing programs calling this routine should migrate as soon as possible. Old calls to this routine should be replaced with a pair of calls to xvd_init_xvdisplay() and xvd_build_xvdisplay(), described above.

This routine creates and initializes the xvdisplay structure and all associated X resources. Takes a Khoros VIFF data structure, and prepares the image contained within it to be displayed as an XImage under X Windows, version 11 release 4. Returns a pointer to the completed DisplayStructure which will be needed for subsequent calls to the xvdisplay library.

DisplayStructure *xvd_init_image(display, image, shape, clip, overlay,
                        private_cmap, read_only, shape_parent, colormap)

Display *display;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;
int private_cmap;
int read_only;
int shape_parent;
Colormap colormap;

xvd_create_xvdisplay()

Creates and initializes the xvdisplay structure and all associated X resources. Creates and automatically pops up the window with the specified image displayed in it. NOTE: do not use this routine in conjunction with xvd_init_xvdisplay(), xvd_build_xvdisplay(), or xvd_create_raster().

DisplayStructure *xvd_create_xvdisplay(display, image, shape, clip, overlay,
                private_cmap, read_only, name, xpos, ypos, position_widget)

Display *display;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;
int private_cmap;
int read_only;
char *name;
int xpos, ypos;
int position_widget;

xvd_create_image()

IMPORTANT NOTE: Due to enhancements that have been made to the xvdisplay library, this routine has been outdated as of Patch2. It still exists for backwards compatibility with those existing applications that call it; however, programmers that have exing programs calling this routine should migrate as soon as possible. Old calls to this routine should be replaced with a call to xvd_create_xvdisplay(), described above.

This routine creates and initializes the xvdisplay structure and all associated resources. Creates and pops up the window with the image displayed in it.

DisplayStructure *xvd_create_image(display, image, shape, clip, overlay,
                private_cmap, read_only, name, xpos, ypos, position_widget)

Display *display;
struct xvimage *image;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;
int private_cmap;
int read_only;
char *name;
int xpos, ypos;
int position_widget;

xvd_create_raster()

Creates & initializes a raster widget for the xvdisplay structure. The DisplayStructure must already be initialized (with a prior call to xvd_init_xvdisplay()). All X resources must be already created (with a prior call to xvd_build_xvdisplay()). The parent must already have been created (in graphical user interfaces, with a call to the xvf_init_XXX() routine, automatically generated by conductor.

xvd_create_raster(display, parent, xvdisplay, position_widget)
Display *display;
Widget parent;
DisplayStructure *xvdisplay;
int position_widget;

xvd_create_icon()

Creates and initializes an icon widget in which the image is displayed in miniature. Creates and maps the icon with the image displayed in it. Note: this routine should be called after the xvdisplay structure is initialized with a call to xvd_init_xvdisplay(). It does not initialize the xvdisplay structure for you, like xvd_create_xvdisplay() does.

xvd_create_icon(display, xvdisplay, desired_width, desired_height);

Display *display;
DisplayStructure *xvdisplay;
int desired_width;
int desired_height;

xvd_delete_xvdisplay()

Deletes the DisplayStructure and frees all associated resources. Should be called after a particular DisplayStructure will no longer be used.

xvd_delete_xvdisplay(xvdisplay)

DisplayStructure *xvdisplay;

xvd_delete_image()

IMPORTANT NOTE: Due to enhancements that have been made to the xvdisplay library, this routine has been outdated as of Patch2. It still exists for backwards compatibility with those existing applications that call it; however, programmers that have existing programs calling this routine should migrate as soon as possible. Old calls to this routine should be replaced with a call to xvd_delete_xvdisplay(), described above.

Deletes the DisplayStructure and frees all associated resources. Should be called after a particular DisplayStructure will no longer be used.

xvd_delete_image(xvdisplay)

DisplayStructure *xvdisplay;

xvd_error_handler()

This very specialized routine is used to handle X Protocol errors. When an error from Xlib, the X Toolkit, or the Athena Widget set is encountered, it is often difficult to establish what portion of the application's code is causing the X Protocol error. The xvdisplay library's use of xvd_error_handler() makes it possible to trace the location of code causing X Errors via the dbx or other debugging program.

The xvd_error_handler() routine is AUTOMATICALLY INSTALLED with the use of the xvdisplay library - YOU NEED NOT EXPLICITLY INSTRUCT YOUR PROGRAM TO CALL THIS ROUTINE. The definition of this routine is provided simply for your information, and NOT because you should make a call to xvd_error_handler() in your program!

If X Protocol errors are encountered in your application that uses the xvdisplay library, you can instruct the dbx program to stop in the xvd_error_handler() routine. Then, by using the dbx "where" command, the faulty code can be easily located. The xvd_error_handler routine will return FALSE (0) if it is possible for the application to recover from the X Protocol error. If the error cannot be recovered from, it will print out the error message produced by X, it will exit the program.

xvd_error_handler(display, xerror)
Display *display;
XErrorEvent *error;

xvd_autocolor()

Performs one of several predefined types of automatic coloring on a Khoros image. The image to be autocolored must be contained in the DisplayStructure, as is the case after a call to xvd_init_image(), or xvd_create_image().

xvd_autocolor(xvdisplay, type)
DisplayStructure *xvdisplay;
int type;

xvd_set_colormap()

Sets the colormap for the widget passed in.

xvd_set_colormap(widget, colormap)
Widget widget;
Colormap colormap;

xvd_extract_roi()

Extracts a region of interest from the displayed image into a new Khoros VIFF data structure.

struct xvimage *xvd_extract_roi(xvdisplay, mouse, x1, y1, x2, y2)
DisplayStructure *xvdisplay;
int mouse;
int x1, y1, x2, y2;

xvd_insert_roi()

Inserts a region of interest contained in a Khoros VIFF data structure into the displayed image.

xvd_insert_roi(xvdisplay, subimage, mouse, x, y, saveimage)
DisplayStructure *xvdisplay;
struct xvimage *subimage;
int mouse;
int x, y;
struct xvimage **saveimage;

xvd_update_image()

Updates the currently displayed image, or displays a new image. Note that there must be an image already displayed when you call this routine. There are several possible cases for situations in whichh you might want to call this routine. Please see the section on the xvdisplay library in Chapter 8 of the Khoros Programmer's Manual for the usage that fits your particular case.

xvd_update_image(xvdisplay, image)
DisplayStructure *xvdisplay;
struct xvimage *image;

xvd_update_shape()

Updates the shape mask, or displays the current image with a new shape mask. Note that there must be an shape mask already shaping the window when you call this routine. There are several possible cases for situations in which you might want to call this routine. Please see the section on the xvdisplay library in Chapter 8 of the Khoros Programmer's Manual for the usage that fits your particular case.

xvd_update_shape(xvdisplay, shape)
DisplayStructure *xvdisplay;
struct xvimage *shape;

xvd_update_clip()

Updates the clip mask, or displays the current image with a new clip mask. Note that there must be an clip mask already overlaid on the image when you call this routine. There are several possible cases for situations in which you might want to call this routine. Please see the section on the xvdisplay library in Chapter 8 of the Khoros Programmer's Manual for the usage that fits your particular case.

xvd_update_clip(xvdisplay, clip)
DisplayStructure *xvdisplay;
struct xvimage *clip;

xvd_update_overlay()

Updates the overlay image, or displays the current image with a new overlay. Note that there must be an overlay already on the image when you call this routine. There are several possible cases for situations in which you might want to call this routine. Please see the section on the xvdisplay library in Chapter 8 of the Khoros Programmer's Manual for the usage that fits your particular case.

xvd_update_overlay(xvdisplay, overlay)
DisplayStructure *xvdisplay;
struct xvimage *overlay;

xvd_update_xvdisplay()

Updates the currently displayed image, the shape mask, the clip mask, and the overlay image. There are several possible cases for situations in which you might want to call this routine. Please see the section on the xvdisplay library in Chapter 8 of the Khoros Programmer's Manual for the usage that fits your particular case.

xvd_update_xvdisplay(xvdisplay, image, shape, clip, overlay)
DisplayStructure *xvdisplay;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;

xvd_update_all()

IMPORTANT NOTE: Due to enhancements that have been made to the xvdisplay library, this routine has been outdated as of Patch2. It still exists for backwards compatibility with those existing applications that call it; however, programmers that have existing programs calling this routine should migrate as soon as possible. Old calls to this routine should be replaced with a call to xvd_update_xvdisplay(), described above.

Updates the currently displayed image, the shape mask, the clip mask, and the overlay image.

xvd_update_all(xvdisplay, image, shape, clip, overlay)
DisplayStructure *xvdisplay;
struct xvimage *image;
struct xvimage *shape;
struct xvimage *clip;
struct xvimage *overlay;

xvd_update_xcolors()

Updates the colors displayed in the image; this is a very specialized routine for use when you elect to make changes directly to the XColor structures stored in the xvdisplay->xcolors array. The colors in the xvdisplay->xcolors can only be dynamically changed if the xvdisplay read_only parameter has been set to FALSE (0) when calling xvd_create_xvdisplay or xvd_init_xvdisplay. Note: be aware that you make changes to the xvdisplay->xcolors array at your own risk!

xvd_update_xcolors(xvdisplay)
DisplayStructure *xvdisplay;

xvd_update_region()

Updates a specified region of the currently displayed image, rather than the entire image. Only applicable when a specific portion of the currently displayed image has had a change made to its contents. Warning - this routine does not free pixels when they are no longer used.

xvd_update_region(xvdisplay, x, y, w, h)
DisplayStructure *xvdisplay;
int x, y;
int w, h;

xvd_update_pixel()

Updates a specific pixel of the currently displayed image. Only applicable when a specific pixel of the currently displayed image has changed.

xvd_update_pixel(xvdisplay, x, y)
DisplayStructure *xvdisplay;
int x, y;

xvd_query_position()

Finds the position of the cursor in the window. Returns TRUE (1) if the next event is a Motion Notify event, so that application may do motion compression if applicable. Returns FALSE (0) otherwise.

int xvd_query_position(widget, x, y, clip)
Widget widget;
int *x, *y;
int clip;

xvd_check_visibility()

Determines whether or not a widget is currently visible. Returns TRUE (1) if the widget is visible, FALSE (0) otherwise.

int xvd_check_visibility(widget)
Widget widget;

xvd_query_value()

Returns the value of the image at the desired x & y position (the pixel). xvd_query_value() will also return the index into the image map. This routine also returns a flag indicating whether the currently displayed pixel color is actually allocated or is the closest available color to another allocated color.

int xvd_query_value(xvdisplay, x, y, value, index, allocated)
DisplayStructure *xvdisplay;
int x, y; double *value; int *index, *allocated;

xvd_clear_image()

Clears (blanks out) the currently displayed image.

int xvd_clear_image(xvdisplay, free_image)
DisplayStructure *xvdisplay;
int free_image;

xvd_clear_shape()

Clears (gets rid of) the current shape mask.

int xvd_clear_shape(xvdisplay, free_shape)
DisplayStructure *xvdisplay;
int free_shape;

xvd_clear_clip()

Clears (gets rid of) the current clip mask.

int xvd_clear_clip(xvdisplay, free_clip)
DisplayStructure *xvdisplay;
int free_clip;

xvd_clear_overlay()

Clears (gets rid of) the current overlay.

int xvd_clear_overlay(xvdisplay, free_overlay)
DisplayStructure *xvdisplay;
int free_overlay;

xvd_clear_xvdisplay()

Clears and frees all internal resources associated with the xvdisplay structure. All ximages and pixmaps are cleared, but the input images supplied by the user are cleared only if free_images is TRUE (1), otherwise their fields are simply cleared from the DisplayStructure.

int xvd_clear_xvdisplay(xvdisplay, free_images)
DisplayStructure *xvdisplay;
int free_images;

xvd_shrink_ximage()

Takes an ximage, and returns a shrunken ximage of the desired width and height. This is commonly used when creating an icon or image to zoom in.

xvd_shrink_ximage(display, ximage, desired_width, desired_height, subximage)
DisplayStructure *display;
XImage *ximage;
int desired_width, desired_height;
XImage *subximage;