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