man/Xmbuf.man

   1 .\" Copyright (c) 1989, 1994  X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice shall be included in
  11 .\" all copies or substantial portions of the Software.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  16 .\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  17 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  18 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  19 .\" SOFTWARE.
  20 .\"
  21 .\" Except as contained in this notice, the name of the X Consortium shall not
  22 .\" be used in advertising or otherwise to promote the sale, use or other
  23 .\" dealing in this Software without prior written authorization from the
  24 .\" X Consortium.
  25 .\"
  26 .\" Copyright 1989, Digital Equipment Corporation.
  27 .\" Permission to use, copy, modify, distribute, and sell this documentation
  28 .\" for any purpose and without fee is hereby granted, provided that the above
  29 .\" copyright notice and this permission notice appear in all copies.
  30 .\" Digital Equipment Corporation makes no representations
  31 .\" about the suitability for any purpose of the information in
  32 .\" this document.  This documentation is provided "as is"
  33 .\" without express or implied warranty.
  34 .\"
  35 .de ZN
  36 .ie t \fB\^\\$1\^\fR\\$2
  37 .el \fI\^\\$1\^\fP\\$2
  38 ..
  39 .TH XMBUF __libmansuffix__ __xorgversion__ "X FUNCTIONS"
  40 .SH NAME
  41 XmbufQueryExtension, XmbufGetVersion, XmbufCreateBuffers, XmbufDestroyBuffers, XmbufDisplayBuffers, XmbufGetWindowAttributes, XmbufChangeWindowAttributes, XmbufGetBufferAttributes, XmbufChangeBufferAttributes, XmbufGetScreenInfo, XmbufCreateStereoWindow - X multibuffering functions
  42 .SH SYNTAX
  43 .nf
  44 .LP
  45 \&#include <X11/extensions/multibuf.h>
  46 .LP
  47 Bool XmbufQueryExtension(
  48     Display *dpy,
  49     Display *dpy,
  50     int *event_base_return,
  51     int *error_base_return);
  52 .LP
  53 Status XmbufGetVersion(
  54     Display *dpy,
  55     int *major_version_return,
  56     int *minor_version_return);
  57 .LP
  58 int XmbufCreateBuffers(
  59     Display *dpy,
  60     Window window,
  61     int count,
  62     int update_action,
  63     int update_hint,
  64     Multibuffer *buffers_update);
  65 .LP
  66 void XmbufDestroyBuffers(
  67     Display *dpy,
  68     Window window);
  69 .LP
  70 void XmbufDisplayBuffers(
  71     Display *dpy,
  72     int count,
  73     Multibuffer *buffers,
  74     int min_delay,
  75     int max_delay);
  76 .LP
  77 Status XmbufGetWindowAttributes(
  78     Display *dpy,
  79     Window window,
  80     XmbufWindowAttributes *attributes);
  81 .LP
  82 void XmbufChangeWindowAttributes(
  83     Display *dpy,
  84     Window window,
  85     unsigned long valuemask,
  86     XmbufSetWindowAttributes *attributes);
  87 .LP
  88 Status XmbufGetBufferAttributes(
  89     Display *dpy,
  90     Multibuffer buffer,
  91     XmbufBufferAttributes *attributes);
  92 .LP
  93 void XmbufChangeBufferAttributes(
  94     Display *dpy,
  95     Multibuffer buffer,
  96     unsigned long valuemask,
  97     XmbufSetBufferAttributes *attributes);
  98 .LP
  99 Status XmbufGetScreenInfo(
 100     Display *dpy,
 101     Drawable drawable,
 102     int *nmono_return,
 103     XmbufBufferInfo **mono_info_return,
 104     int *nstereo_return,
 105     XmbufBufferInfo **stereo_info_return);
 106 .LP
 107 Window XmbufCreateStereoWindow(
 108     Display *dpy,
 109     Window parent,
 110     int x,
 111     int y,
 112     unsigned int width,
 113     unsigned int height,
 114     unsigned int border_width,
 115     int depth,
 116     unsigned int class,                 /\&* InputOutput, InputOnly*/
 117     Visual *visual,
 118     unsigned long valuemask,
 119     XSetWindowAttributes *attributes,
 120     Multibuffer *left_return,
 121     Multibuffer *right_return);
 122 .fi
 123 .SH STRUCTURES
 124 .nf
 125 .ta 3i
 126 \fIEvents:\fP
 127 typedef struct {
 128     int type;   /\&* of event */
 129     unsigned long serial;       /\&* # of last request processed by server */
 130     int send_event;     /\&* true if this came from a SendEvent request */
 131     Display *display;   /\&* Display the event was read from */
 132     Multibuffer buffer; /\&* buffer of event */
 133     int state;  /\&* see Clobbered constants above */
 134 } XmbufClobberNotifyEvent;
 135 .LP
 136 typedef struct {
 137     int type;   /\&* of event */
 138     unsigned long serial;       /\&* # of last request processed by server */
 139     int send_event;     /\&* true if this came from a SendEvent request */
 140     Display *display;   /\&* Display the event was read from */
 141     Multibuffer buffer; /\&* buffer of event */
 142 } XmbufUpdateNotifyEvent;
 143 .LP
 144 \fIPer-window attributes that can be got:\fP
 145 typedef struct {
 146     int displayed_index;        /\&* which buffer is being displayed */
 147     int update_action;  /\&* Undefined, Background, Untouched, Copied */
 148     int update_hint;    /\&* Frequent, Intermittent, Static */
 149     int window_mode;    /\&* Mono, Stereo */
 150     int nbuffers;       /\&* Number of buffers */
 151     Multibuffer *buffers;       /\&* Buffers */
 152 } XmbufWindowAttributes;
 153 .LP
 154 \fIPer-window attributes that can be set:\fP
 155 typedef struct {
 156     int update_hint;    /\&* Frequent, Intermittent, Static */
 157 } XmbufSetWindowAttributes;
 158 .LP
 159 \fIPer-buffer attributes that can be got:\fP
 160 typedef struct {
 161     Window window;      /\&* which window this belongs to */
 162     unsigned long event_mask;   /\&* events that have been selected */
 163     int buffer_index;   /\&* which buffer is this */
 164     int side;   /\&* Mono, Left, Right */
 165 } XmbufBufferAttributes;
 166 .LP
 167 \fIPer-buffer attributes that can be set:\fP
 168 typedef struct {
 169     unsigned long event_mask;   /\&* events that have been selected */
 170 } XmbufSetBufferAttributes;
 171 .LP
 172 \fIPer-screen buffer info (there will be lists of them):\fP
 173 typedef struct {
 174     VisualID visualid;  /\&* visual usable at this depth */
 175     int max_buffers;    /\&* most buffers for this visual */
 176     int depth;  /\&* depth of buffers to be created */
 177 } XmbufBufferInfo;
 178 .fi
 179 .SH DESCRIPTION
 180 The application programming library for the
 181 \fIX11 Double-Buffering, Multi-Buffering, and Stereo Extension\fP
 182 contains the interfaces described below.
 183 With the exception of
 184 .ZN XmbufQueryExtension ,
 185 if any of these routines are
 186 called with a display that does not support the extension, the
 187 ExtensionErrorHandler (which can be set with
 188 .ZN XSetExtensionErrorHandler
 189 and functions the same way as
 190 .ZN XSetErrorHandler )
 191 will be called and the function will then return.
 192 .PP
 193 .ZN XmbufQueryExtension
 194 returns
 195 .ZN True
 196 if the multibuffering/stereo
 197 extension is available on the
 198 given display.  If the extension exists, the value of the first event
 199 code (which should be added to the event type constants
 200 .ZN MultibufferClobberNotify
 201 and
 202 .ZN MultibufferUpdateNotify
 203 to get the actual
 204 values) is stored into event_base_return and the value of the first
 205 error code (which should be added to the error type constant
 206 .ZN MultibufferBadBuffer
 207 to get the actual value) is stored into error_base_return.
 208 .PP
 209 .ZN XmbufGetVersion
 210 gets the major and minor version numbers of the extension.
 211 The return
 212 value is zero if an error occurs or non-zero if no error happens.
 213 .PP
 214 .ZN XmbufCreateBuffers
 215 requests that "count" buffers be
 216 created with the given update_action
 217 and update_hint and be associated with the indicated window.  The
 218 number of buffers created is returned (zero if an error occurred)
 219 and buffers_update is filled in with that many Multibuffer identifiers.
 220 .PP
 221 .ZN XmbufDestroyBuffers
 222 destroys the buffers associated
 223 with the given window.
 224 .PP
 225 .ZN XmbufDisplayBuffers
 226 displays the indicated buffers their
 227 appropriate windows within
 228 max_delay milliseconds after min_delay milliseconds have passed.
 229 No two buffers may be associated with the same window or else a Match
 230 error is generated.
 231 .PP
 232 .ZN XmbufGetWindowAttributes
 233 gets the multibuffering attributes that apply
 234 to all buffers associated
 235 with the given window.
 236 The list of buffers returns may be freed with
 237 .ZN XFree .
 238 Returns non-zero on success and zero if an error occurs.
 239 .PP
 240 .ZN XmbufChangeWindowAttributes
 241 sets the multibuffering attributes
 242 that apply to all buffers associated
 243 with the given window.  This is currently limited to the update_hint.
 244 .PP
 245 .ZN XmbufGetBufferAttributes
 246 gets the attributes for the indicated buffer.
 247 Returns non-zero on
 248 success and zero if an error occurs.
 249 .PP
 250 .ZN XmbufChangeBufferAttributes
 251 sets the attributes for the indicated buffer.
 252 This is currently limited to the event_mask.
 253 .PP
 254 .ZN XmbufGetScreenInfo
 255 gets the parameters controlling how
 256 mono and stereo windows may be
 257 created on the screen of the given drawable.  The numbers of sets of
 258 visual and depths are returned in nmono_return and nstereo_return.  If
 259 nmono_return is greater than zero, then mono_info_return is set to the
 260 address of an array of
 261 .ZN XmbufBufferInfo
 262 structures describing the
 263 various visuals and depths that may be used.  Otherwise,
 264 mono_info_return is set to NULL.  Similarly, stereo_info_return is set
 265 according to nstereo_return.  The storage returned in mono_info_return
 266 and stereo_info_return may be released by
 267 .ZN XFree .
 268 If no errors are
 269 encounted, non-zero will be returned.
 270 .PP
 271 .ZN XmbufCreateStereoWindow
 272 creates a stereo window in the same way that
 273 .ZN XCreateWindow
 274 creates a mono window.  The buffer ids for the left and right buffers are
 275 returned in left_return and right_return, respectively.  If an
 276 extension error handler that returns is installed,
 277 .ZN None
 278 will be returned if the extension is not available on this display.
 279 .SH PREDEFINED VALUES
 280 .sp
 281 Update_action field:
 282 .in +.5i
 283 .nf
 284 .ZN MultibufferUpdateActionUndefined
 285 .ZN MultibufferUpdateActionBackground
 286 .ZN MultibufferUpdateActionUntouched
 287 .ZN MultibufferUpdateActionCopied
 288 .in -.5i
 289 .fi
 290 .sp
 291 Update_hint field:
 292 .in +.5i
 293 .nf
 294 .ZN MultibufferUpdateHintFrequent
 295 .ZN MultibufferUpdateHintIntermittent
 296 .ZN MultibufferUpdateHintStatic
 297 .in -.5i
 298 .sp
 299 .fi
 300 Valuemask fields:
 301 .in +.5i
 302 .nf
 303 .ZN MultibufferWindowUpdateHint
 304 .ZN MultibufferBufferEventMask
 305 .in -.5i
 306 .fi
 307 .sp
 308 Mono vs. stereo and left vs. right:
 309 .in +.5i
 310 .nf
 311 .ZN MultibufferModeMono
 312 .ZN MultibufferModeStereo
 313 .ZN MultibufferSideMono
 314 .ZN MultibufferSideLeft
 315 .ZN MultibufferSideRight
 316 .in -.5i
 317 .fi
 318 .sp
 319 Clobber state:
 320 .in +.5i
 321 .nf
 322 .ZN MultibufferUnclobbered
 323 .ZN MultibufferPartiallyClobbered
 324 .ZN MultibufferFullyClobbered
 325 .in -.5i
 326 .fi
 327 .sp
 328 Event stuff:
 329 .in +.5i
 330 .nf
 331 .ZN MultibufferClobberNotifyMask
 332 .ZN MultibufferUpdateNotifyMask
 333 .ZN MultibufferClobberNotify
 334 .ZN MultibufferUpdateNotify
 335 .ZN MultibufferNumberEvents
 336 .ZN MultibufferBadBuffer
 337 .ZN MultibufferNumberErrors
 338 .in -.5i
 339 .fi
 340 .SH BUGS
 341 This manual page needs more work.
 342 .SH SEE ALSO
 343 \fIExtending X for Double Buffering, Multi-Buffering, and Stereo\fP