Extending X for Double-Buffering, Multi-Buffering, and Stereo

Several proposals have been written that address some of the issues surrounding the support of double-buffered, multi-buffered, and stereo windows in the X Window System:

The authors of this proposal have tried to unify the above documents to yield a proposal that incorporates support for double-buffering, multi-buffering, and stereo in a way that is acceptable to all concerned.

Clients should be able to:

In addition, the extension should:

Normal windows are created using the standard CreateWindow request:

CreateWindow
     parent          : WINDOW
     w_id            : WINDOW
     depth           : CARD8
     visual          : VISUALID or CopyFromParent
     x, y            : INT16
     width, height   : INT16
     border_width    : INT16
     value_mask      : BITMASK
     value_list      : LISTofVALUE

This request allocates a set of window attributes and a buffer into which an image can be drawn. The contents of this image buffer will be displayed when the window is mapped to the screen.

To support double-buffering and multi-buffering, we introduce the notion that additional image buffers can be created and bound together to form groups. The following rules will apply:

By allowing draw operations to occur on any image buffer at any time, a client could, on a multi-threaded multi-processor server, simultaneously build up images for display. To support this, each buffer must have its own resource ID. Since buffers are different than windows and pixmaps (buffers are not hierarchical and pixmaps cannot be displayed) a new resource, Buffer, is introduced. Furthermore, a Buffer is also a Drawable, thus draw operations may also be performed on buffers simply by passing a buffer ID to the existing pixmap/window interface.

To allow existing X applications to work unchanged, we assume a window ID passed in a draw request, for a multi-buffered window, will be an alias for the ID of the currently displayed image buffer. Any draw requests (eq: GetImage) on the window will be relative to the displayed image buffer.

In window management requests, only a window ID will be accepted. Requests like QueryTree, will continue to return only window ID's. Most events will return just the window ID. Some new events, described in a subsequent section, will return a buffer ID.

When a window has backing store the contents of the window are saved off-screen. Likewise, when the contents of an image buffer of a multi-buffer window is saved off-screen, it is said to have backing store. This applies to all image buffers, whether or not they are selected for display.

In some multi-buffer implementations, undisplayed buffers might be implemented using pixmaps. Since the contents of pixmaps exist off-screen and are not affected by occlusion, these image buffers in effect have backing store.

On the other hand, both the displayed and undisplayed image buffers might be implemented using a subset of the on-screen pixels. In this case, unless the contents of an image buffer are saved off-screen, these image buffers in effect do not have backing store.

Output to any image buffer of an unmapped multi-buffered window that does not have backing store is discarded. Output to any image buffer of a mapped multi-buffer window will be performed; however, portions of an image buffer may be occluded or clipped.

When an unmapped multi-buffered window becomes mapped, the contents of any image buffer buffer that did not have backing store is tiled with the background and zero or more exposure events are generated. If no background is defined for the window, then the screen contents are not altered and the contents of any undisplayed image buffers are undefined. If backing store was maintained for an image buffer, then no exposure events are generated.

The new request, CreateImageBuffers, creates a group of image buffers and associates them with a normal X window:

CreateImageBuffers
     w_id           : WINDOW
     buffers        : LISTofBUFFER
     update_action  : {Undefined,Background,Untouched,Copied}
     update_hint    : {Frequent,Intermittent,Static}
     =>
     number_buffers : CARD16

     (Errors: Window, IDChoice, Value)

One image buffer will be associated with each ID passed in buffers. The first buffer of the list is referred to as buffer[0], the next buffer[1], and so on. Each buffer will have the same visual type and geometry as the window. Buffer[0] will refer to the image buffer already associated with the window ID and its contents will not be modified. The displayed image buffer attribute is set to buffer[0].

Image buffers for the remaining ID's (buffer[1],...) are allocated. If the window is mapped, or if these image buffers have backing store, their contents will be tiled with the window background (if no background is defined, the buffer contents are undefined), and zero or more expose events will be generated for each of these buffers. The contents of an image buffer is undefined when the window is unmapped and the buffer does not have backing store.

If the window already has a group of image buffers associated with it (ie: from a previous CreateImageBuffers request) the actions described for DestroyImageBuffers are performed first (this will delete the association of the previous buffer ID's and their buffers as well as de-allocate all buffers except for the one already associated with the window ID).

To allow a server implementation to efficiently allocate the buffers, the total number of buffers required and the update action (how they will behave during an update) is specified "up front" in the request. If the server cannot allocate all the buffers requested, the total number of buffers actually allocated will be returned. No Alloc errors will be generated \- buffer[0] can always be associated with the existing displayed image buffer.

For example, an application that wants to animate a short movie loop may request 64 image buffers. The server may only be able to support 16 image buffers of this type, size, and depth. The application can then decide 16 buffers is sufficient and may truncate the movie loop, or it may decide it really needs 64 and will free the buffers and complain to the user.

One might be tempted to provide a request that inquires whether n buffers of a particular type, size, and depth could be allocated. But if the query is decoupled from the actual allocation, another client could sneak in and take the buffers before the original client has allocated them.

While any buffer of a group can be selected for display, some applications may display buffers in a predictable order (ie: the movie loop application). The list order (buffer[0], buffer[1], ...) will be used as a hint by the server as to which buffer will be displayed next. A client displaying buffers in this order may see a performance improvement.

update_action indicates what should happen to a previously displayed buffer when a different buffer becomes displayed. Possible actions are:

update_hint indicates how often the client will request a different buffer to be displayed. This hint will allow smart server implementations to choose the most efficient means to support a multi-buffered window based on the current need of the application (dumb implementations may choose to ignore this hint). Possible hints are:

To display an image buffer the following request can be used:

DisplayImageBuffers
     buffers         : LISTofBUFFER
     min_delay       : CARD16
     max_delay       : CARD16

     (Errors: Buffer, Match)

The image buffers listed will become displayed as simultaneously as possible and the update action, bound at CreateImageBuffers time, will be performed.

A list of buffers is specified to allow the server to efficiently change the display of more than one window at a time (ie: when a global screen swap method is used). Attempting to simultaneously display multiple image buffers from the same window is an error (Match) since it violates the rule that only one image buffer per group can be displayed at a time.

If a specified buffer is already displayed, any delays and update action will still be performed for that buffer. In this instance, only the update action of Background (and possibly Undefined) will have any affect on the contents of the displayed buffer. These semantics allow an animation application to successfully execute even when there is only a single buffer available for a window.

When a DisplayImageBuffers request is made to an unmapped multi-buffered window, the effect of the update action depends on whether the image buffers involved have backing store. When the target of the update action is an image buffer that does not have backing store, output is discarded. When the target image buffer does have backing store, the update is performed; however, when the source of the update is an image buffer does not have backing store (as in the case of update action Copied), the contents of target image buffer will become undefined.

min_delay and max_delay put a bound on how long the server should wait before processing the display request. For each of the windows to be updated by this request, at least min_delay milli-seconds should elapse since the last time any of the windows were updated; conversely, no window should have to wait more than max_delay milli-seconds before being updated.

min_delay allows an application to slow down an animation or movie loop so that it appears synchronized at a rate the server can support given the current load. For example, a min_delay of 100 indicates the server should wait at least 1/10 of a second since the last time any of the windows were updated. A min_delay of zero indicates no waiting is necessary.

max_delay can be thought of as an additional delay beyond min_delay the server is allowed to wait to facilitate such things as efficient update of multiple windows. If max_delay would require an update before min_delay is satisfied, then the server should process the display request as soon as the min_delay requirement is met. A typical value for max_delay is zero.

To implement the above functionality, the time since the last update by a DisplayImageBuffers request for each multi-buffered window needs to be saved as state by the server. The server may delay execution of the DisplayImageBuffers request until the appropriate time (e.g. by requeuing the request after computing the timeout); however, the entire request must be processed in one operation. Request execution indivisibility must be maintained. When a server is implemented with internal concurrency, the extension must adhere to the same concurrency semantics as those defined for the core protocol.

To explicitly clear a rectangular area of an image buffer to the window background, the following request can be used:

ClearImageBufferArea
     buffer          : BUFFER
     x, y            : INT16
     w, h            : CARD16
     exposures       : BOOL

     (Errors: Buffer, Value)

Like the X ClearArea request, x and y are relative to the window's origin and specify the upper-left corner of the rectangle. If width is zero, it is replaced with the current window width minus x. If height is zero it is replaced with the current window height minus y. If the window has a defined background tile, the rectangle is tiled with a plane mask of all ones, a function of Copy, and a subwindow-mode of ClipByChildren. If the window has background None, the contents of the buffer are not changed. In either case, if exposures is true, then one or more exposure events are generated for regions of the rectangle that are either visible or are being retained in backing store.

The group of image buffers allocated by a CreateImageBuffers request can be destroyed with the following request:

DestroyImageBuffers
     w_id          : WINDOW

     (Error: Window)

The association between the buffer ID's and their corresponding image buffers are deleted. Any image buffers not selected for display are de-allocated. If the window is not multi-buffered, the request is ignored.

The following attributes will be associated with each window that is multi-buffered:

     displayed_buffer : CARD16
     update_action    : {Undefined,Background,Untouched,Copied}
     update_hint      : {Frequent,Intermittent,Static}
     window_mode      : {Mono,Stereo}
     buffers          : LISTofBUFFER

displayed_buffer is set to the index of the currently displayed image buffer (for stereo windows, this will be the index of the left buffer \- the index of the right buffer is simply index+1). window_mode indicates whether this window is Mono or Stereo. The ID for each buffer associated with the window is recorded in the buffers list. The above attributes can be queried with the following request:

GetMultiBufferAttributes
     w_id             : WINDOW
     =>
     displayed_buffer : CARD16
     update_action    : {Undefined,Background,Untouched,Copied}
     update_hint      : {Frequent,Intermittent,Static}
     window_mode      : {Mono,Stereo}
     buffers          : LISTofBUFFER

     (Errors: Window, Access, Value)

If the window is not multi-buffered, a Access error will be generated. The only multi-buffer attribute that can be explicitly set is update_hint. Rather than have a specific request to set this attribute, a generic set request is provided to allow for future expansion:

SetMultiBufferAttributes
     w_id            : WINDOW
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Window, Match, Value)

If the window is not multi-buffered, a Match error will be generated. The following attributes are maintained for each buffer of a multi-buffered window:

     window           : WINDOW
     event_mask       : SETofEVENT
     index            : CARD16
     side             : {Mono,Left,Right}

window indicates the window this buffer is associated with. event_mask specifies which events, relevant to buffers, will be sent back to the client via the associated buffer ID (initially no events are selected). index is the list position (0, 1, ...) of the buffer. side indicates whether this buffer is associated with the left side or right side of a stereo window. For non-stereo windows, this attribute will be set to Mono. These attributes can be queried with the following request:

GetBufferAttributes
     buffer          : BUFFER
     =>
     window           : WINDOW
     event_mask       : SETofEVENT
     index            : CARD16
     side             : {Mono,Left,Right}

     (Errors: Buffer, Value)

The only buffer attribute that can be explicitly set is event_mask. The only events that are valid are Expose and the new ClobberNotify and UpdateNotify event (see Events section below). A Value error will be generated if an event not selectable for a buffer is specified in an event mask. Rather than have a specific request to set this attribute, a generic set request is provided to allow for future expansion:

SetBufferAttributes
     buffer          : BUFFER
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Buffer, Value)

Clients may want to query the server about basic multi-buffer and stereo capability on a per screen basis. The following request returns a large list of information that would most likely be read once by Xlib for each screen, and used as a data base for other Xlib queries:

GetBufferInfo
     root            : WINDOW
     =>
     info            : LISTofSCREEN_INFO

Where SCREEN_INFO and BUFFER_INFO are defined as:

     SCREEN_INFO     : [ normal_info : LISTofBUFFER_INFO,
                         stereo_info : LISTofBUFFER_INFO ]

     BUFFER_INFO     : [ visual      : VISUALID,
                         max_buffers : CARD16,
                         depth       : CARD8 ]

Information regarding multi-buffering of normal (mono) windows is returned in the normal_info list. The stereo_info list contains information about stereo windows. If the stereo_info list is empty, stereo windows are not supported on the screen. If max_buffers is zero, the maximum number of buffers for the depth and visual is a function of the size of the created window and current memory limitations.

The following request returns the major and minor version numbers of this extension:

GetBufferVersion
     =>
     major_number    : CARD8
     minor_number    : CARD8

The version numbers are an escape hatch in case future revisions of the protocol are necessary. In general, the major version would increment for incompatible changes, and the minor version would increment for small upward compatible changes. Barring changes, the major version will be 1, and the minor version will be 1.

All events normally generated for single-buffered windows are also generated for multi-buffered windows. Most of these events (ie: ConfigureNotify) will only be generated for the window and not for each buffer. These events will return a window ID.

Expose events will be generated for both the window and any buffer affected. When this event is generated for a buffer, the same event structure will be used but a buffer ID is returned instead of a window ID. Clients, when processing these events, will know whether an ID returned in an event structure is for a window or a buffer by comparing the returned ID to the ones returned when the window and buffer were created.

GraphicsExposure and NoExposure are generated using whatever ID is specified in the graphics operation. If a window ID is specified, the event will contain the window ID. If a buffer ID is specified, the event will contain the buffer ID.

In some implementations, moving a window over a multi-buffered window may cause one or more of its buffers to get overwritten or become unwritable. To allow a client drawing into one of these buffers the opportunity to stop drawing until some portion of the buffer is writable, the following event is added:

ClobberNotify
     buffer         :  BUFFER
     state          : {Unclobbered,PartiallyClobbered,FullyClobbered}

The ClobberNotify event is reported to clients selecting ClobberNotify on a buffer. When a buffer that was fully or partially clobbered becomes unclobbered, an event with Unclobbered is generated. When a buffer that was unclobbered becomes partially clobbered, an event with PartiallyClobbered is generated. When a buffer that was unclobbered or partially clobbered becomes fully clobbered, an event with FullyClobbered is generated.

ClobberNotify events on a given buffer are generated before any Expose events on that buffer, but it is not required that all ClobberNotify events on all buffers be generated before all Expose events on all buffers.

The ordering of ClobberNotify events with respect to VisibilityNotify events is not constrained.

If multiple buffers were used as an image FIFO between an image server and the X display server, then the FIFO manager would like to know when a buffer that was previously displayed, has been undisplayed and updated, as the side effect of a DisplayImageBuffers request. This allows the FIFO manager to load up a future frame as soon as a buffer becomes available. To support this, the following event is added:

UpdateNotify
     buffer         :  BUFFER

The UpdateNotify event is reported to clients selecting UpdateNotify on a buffer. Whenever a buffer becomes updated (e.g. its update action is performed as part of a DisplayImageBuffers request), an UpdateNotify event is generated.

The following error type has been added to support this extension:

/*
 * Create a normal window
 */
CreateWindow( W, ... )

/*
 * Create two image buffers.  Assume after display, buffer
 * contents become "undefined".  Assume we will "frequently"
 * update the display.  Abort if we don't get two buffers,
 */
n = CreateImageBuffers( W, [B0,B1], Undefined, Frequent )
if (n != 2) <abort>

/*
 * Map window to the screen
 */
MapWindow( W )

/*
 * Draw images using alternate buffers, display every
 * 1/10 of a second.  Note we draw B1 first so it will
 * "pop" on the screen
 */
while animating
{
     <draw picture using B1>
     DisplayImageBuffers( [B1], 100, 0 )

     <draw picture using B0>
     DisplayImageBuffers( [B0], 100, 0 )
}

/*
 * Strip image buffers and leave window with
 * contents of last displayed image buffer.
 */
DestroyImageBuffers( W )

/*
 * Create a normal window
 */
CreateWindow( W, ... )

/*
 * Create 'N' image buffers.  Assume after display, buffer
 * contents are "untouched".  Assume we will "frequently"
 * update the display.  Abort if we don't get all the buffers.
 */
n = CreateImageBuffers( W, [B0,B1,...,B(N-1)], Untouched, Frequent )
if (n != N) <abort>

/*
 * Map window to screen
 */
MapWindow( W )

/*
 * Draw each frame of movie one per buffer
 */
foreach frame
     <draw frame using B(i)>

/*
 * Cycle through frames, one frame every 1/10 of a second.
 */
while animating
{
     foreach frame
          DisplayImageBuffers( [B(i)], 100, 0 )
}

CreateStereoWindow
     parent          : WINDOW
     w_id            : WINDOW
     left, right     : BUFFER
     depth           : CARD8
     visual          : VISUALID or CopyFromParent
     x, y            : INT16
     width, height   : INT16
     border_width    : INT16
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Alloc, Color, Cursor, Match,
              Pixmap, Value, Window)

/*
 * Create the stereo window, map it the screen,
 * and draw the left and right images
 */
CreateStereoWindow( W, L, R, ... )

MapWindow( W )

<draw picture using L,R>

/*
 * Create stereo window and map it to the screen
 */
CreateStereoWindow( W, L, R, ... )

/*
 * Create two pairs of image buffers.  Assume after display,
 * buffer contents become "undefined".  Assume we will "frequently"
 * update the display.  Abort if we did get all the buffers.
 */
n = CreateImageBuffers( W, [L0,R0,L1,R1], Undefined, Frequently )
if (n != 4) <abort>

/*
 * Map window to the screen
 */
MapWindow( W )

/*
 * Draw images using alternate buffers,
 * display every 1/10 of a second.
 */
while animating
{
     <draw picture using L1,R1>
     DisplayImageBuffers( [L1], 100, 0 )

     <draw picture using L0,R0>
     DisplayImageBuffers( [L0], 100, 0 )
}

/*
 * Create stereo window
 */
CreateStereoWindow( W, L, R, ... )

/*
 * Create N pairs of image buffers.  Assume after display,
 * buffer contents are "untouched".  Assume we will "frequently"
 * update the display.  Abort if we don't get all the buffers.
 */
n = CreateImageBuffers( W, [L0,R0,...,L(N-1),R(N-1)], Untouched, Frequently )
if (n != N*2) <abort>

/*
 * Map window to screen
 */
MapWindow( W )

/*
 * Draw the left and right halves of each image
 */
foreach stereo image
     <draw picture using L(i),R(i)>

/*
 * Cycle through images every 1/10 of a second
 */
while animating
{
     foreach stereo image
          DisplayImageBuffers( [L(i)], 100, 0 )
}

BUFFER_INFO

4       VISUALID     visual
2       CARD16       max-buffers
1       CARD8        depth
1                    unused

SETofBUFFER_EVENT

        #x00008000   Exposure
        #x02000000   ClobberNotify
        #x04000000   UpdateNotify

ClobberNotify
1       see first-event code
1                                unused
2       CARD16                   sequence number
4       BUFFER                   buffer
1                                state
        0 Unclobbered
        1 PartiallyClobbered
        2 FullyClobbered
23                                unused

UpdateNotify
1 first-event+1 code
1                       unused
2      CARD16           sequence number
4      BUFFER           buffer
24                      unused

Buffer
1     0                 Error
1     see first-error code
2     CARD16                 sequence number
4     CARD32                 bad resource id
2     CARD16                 minor-opcode
1     CARD8                  major-opcode
21                           unused

GetBufferVersion
1       see major-opcode         major-opcode
1       0                  minor-opcode
2       1                  request length
->
1       1                  Reply
1                          unused
2       CARD16             sequencenumber
4       0                  reply length
1       CARD8              majorversion number
1       CARD8              minorversion number
22                         unused


CreateImageBuffers

1        see major-opcode  major-opcode
1        1                 minor-opcode
2        3+n               requestlength
4        WINDOW            wid
1                          update-action
         0 Undefined
         1 Background
         2 Untouched
         3 Copied
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static
2                          unused
4n     LISTofBUFFER        buffer-list
->
1        1                 Reply
1                          unused
2      CARD16              sequencenumber
4      0                   reply length
2      CARD16              number-buffers
22                         unused


DestroyImageBuffers

1        see major-opcode  major-opcode
1       2                  minor-opcode
2       2                  request length
4       WINDOW             wid


DisplayImageBuffers


1        see major-opcode  major-opcode
2        2+n               requestlength
2        CARD16            min-delay
2        CARD16            max-delay
4n       LISTofBUFFER      buffer-list


SetMultiBufferAttributes

1        see major-opcode  major-opcode
1        4                 minor-opcode
2        3+n               requestlength
4        WINDOW            wid
4        BITMASK           value-mask (has n bits set to 1)
         #x00000001        update-hint
4n        LISTofVALUE      value-list
VALUEs
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static


GetMultiBufferAttributes

1        see major-opcode  major-opcode
1        5                 minor-opcode
2        2                 request length
4        WINDOW            wid
®
1        1                 Reply
1                          unused
2        CARD16            sequencenumber
4        n                 reply length
2        CARD16            displayed-buffer
1                          update-action
         0 Undefined
         1 Background
         2 Untouched
         3 Copied
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static
1                          window-mode
         0 Mono
         1 Stereo
19                         unused
4n       LISTofBUFFER      buffer list


SetBufferAttributes

1        see major-opcode  major-opcode
1        6                 minor-opcode
2        3+n               requestlength
4        BUFFER            buffer
4        BITMASK           value-mask (has n bits set to 1)
         #x00000001        event-mask
4n       LISTofVALUE       value-list
VALUEs
4        SETofBUFFER_EVENT event-mask

GetBufferAttributes

1        see major-opcode  major-opcode
1        7                 minor-opcode
2        2                 request length
4        BUFFER            buffer
->
1        1                 Reply
1                          unused
2        CARD16            sequencenumber
4        0                 reply length
4        WINDOW            wid
4        SETofBUFFER_EVENT event-mask
2        CARD16            index
         1 side
         0 Mono
         1 Left
         2 Right
13                         unused

GetBufferInfo

1        see major-opcode  major-opcode
1        8                   minor-opcode
2        2                   request length
4        WINDOW              root
®
1        1                   Reply
1                            unused
2        CARD16              sequencenumber
4        2(n+m)              replylength
2        n                   number BUFFER_INFO in normal-info
2        m                   number BUFFER_INFO in stereo-info
20                           unused
8n       LISTofBUFFER_INFO   normal-info
8m       LISTofBUFFER_INFO   stereo-info

CreateStereoWindow

1        see major-opcode  major-opcode
1        9 minor-opcode
2        11+n                    requestlength
3                                unused
1        CARD8                   depth
4        WINDOW                  wid
4        WINDOW                  parent
4        BUFFER                  left
4        BUFFER                  right
2        INT16                   x
2        INT16                   y
2        CARD16                  width
2        CARD16                  height
2        CARD16                  border-width
2                                class
         0 CopyFromParent
         1 InputOutput
         2 InputOnly
4        VISUALID                visual
         0 CopyFromParent
4        BITMASK                 value-mask (has n bits set to 1)
         encodings are the same
         as for CreateWindow
4n       LISTofVALUE             value-list
         encodings are the same
         as for CreateWindow


ClearImageBufferArea

1 see major-opcode major-opcode
1        10                      minor-opcode
2        5                       request length
4        WINDOW                  buffer
2        INT16                   x
2        INT16                   y
2        CARD16                  width
2        CARD16                  height
3                                unused
1        BOOL                    exposures