GLXSELECTEVENT(3G)

NAME
glXSelectEvent - select GLX events for a window or a GLX pixel buffer

C SPECIFICATION

void glXSelectEvent(Display * dpy, GLXDrawable draw, unsigned long event_mask);

PARAMETERS

dpy
    Specifies the connection to the X server.

draw
    Specifies a GLX drawable. Must be a GLX pixel buffer or a window.

event_mask
    Specifies the events to be returned for draw.

DESCRIPTION

glXSelectEvent sets the GLX event mask for a GLX pixel buffer or a window. Calling glXSelectEvent overrides any previous event mask that was set by the client for draw. Note that it does not affect the event masks that other clients may have specified for draw since each client rendering to draw has a separate event mask for it.

Currently, only one GLX event, GLX_PBUFFER_CLOBBER_MASK, can be selected. The following data is returned to the client when a GLX_PBUFFER_CLOBBER_MASK event occurs:

typedef struct {
int event_type; | /* GLX_DAMAGED or GLX_SAVED */
int draw_type; | /* GLX_WINDOW or GLX_PBUFFER */
unsigned long serial; | /* # of last request processed by server */
Bool send_event; | /* true if this came for SendEvent request */
Display *display; | /* display the event was read from */
GLXDrawable drawable; | /* i.d. of Drawable */
unsigned int buffer_mask; | /* mask indicating affected buffers */
int x, y; |
int width, height; |
int count; | /* if nonzero, at least this many more */

} GLXPbufferClobberEvent; The valid bit masks used in buffer_mask are:

Bitmask | Corresponding Buffer
GLX_FRONT_LEFT_BUFFER_BIT | Front left color buffer
GLX_FRONT_RIGHT_BUFFER_BIT | Front right color buffer
GLX_BACK_LEFT_BUFFER_BIT | Back left color buffer
GLX_BACK_RIGHT_BUFFER_BIT | Back right color buffer
GLX_AUX_BUFFERS_BIT | Auxiliary buffer
GLX_DEPTH_BUFFER_BIT | Depth buffer
GLX_STENCIL_BUFFER_BIT | Stencil buffer
GLX_ACCUM_BUFFER_BIT | Accumulation buffer

A single X server operation can cause several buffer clobber events to be sent. (e.g., a single GLX pixel buffer may be damaged and cause multiple buffer clobber events to be generated). Each event specifies one region of the GLX drawable that was affected by the X Server operation. The buffer_mask field indicates which color buffers and ancillary buffers were affected. All the buffer clobber events generated by a single X server action are guaranteed to be contiguous in the event queue. The conditions under which this event is generated and the event_type varies, depending on the type of the GLX drawable.

When the GLX_AUX_BUFFERS_BIT is set in buffer_mask, then aux_buffer is set to indicate which buffer was affected. If more than one aux buffer was affected, then additional events are generated as part of the same contiguous event group. Each additional event will have only the GLX_AUX_BUFFERS_BIT set in buffer_mask, and the aux_buffer field will be set appropriately. For nonstereo drawables, GLX_FRONT_LEFT_BUFFER_BIT and GLX_BACK_LEFT_BUFFER_BIT are used to specify the front and back color buffers.

For preserved GLX pixel buffers, a buffer clobber event with type GLX_SAVED is generated whenever the contents of the GLX pixel buffer is moved out of offscreen memory. The event(s) describes which portions of the GLX pixel buffer were affected. Clients who receive many buffer clobber events, referring to different save actions, should consider freeing the GLX pixel buffer resource in order to prevent the system from thrashing due to insufficient resources.

For an unpreserved GLXPbuffer, a buffer clobber event, with type GLX_DAMAGED, is generated whenever a portion of the GLX pixel buffer becomes invalid. The client may wish to regenerate the invalid portions of the GLX pixel buffer.

For Windows, buffer clobber events, with type GLX_SAVED, occur whenever an ancillary buffer, associated with the window, gets clobbered or moved out of off-screen memory. The event contains information indicating which color buffers and ancillary buffers\(emand which portions of those buffers\(emwere affected.

NOTES

glXSelectEvent is available only if the GLX version is 1.3 or greater.

If the GLX version is 1.1 or 1.0, the GL version must be 1.0. If the GLX version is 1.2, then the GL version must be 1.1. If the GLX version is 1.3, then the GL version must be 1.2.

ERRORS

GLXBadDrawable is generated if draw is not a valid window or a valid GLX pixel buffer.

ASSOCIATED GETS

glXGetSelectedEvent()

SEE ALSO

glXCreatePbuffer()

COPYRIGHT

Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.