generate separate modules for gl, glu, glx; add info target
[clinton/guile-figl.git] / doc / low-level-glx.texi
CommitLineData
8925f36f
AW
1
2@c %start of fragment
3
4@copying
5This section of the manual was derived from the upstream OpenGL
6documentation. Each function's documentation has its own copyright
7statement; for full details, see the upstream documentation. The
8copyright notices and licenses present in this section are as follows.
9
10Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document is
11licensed under the SGI Free Software B License. For details, see
12@uref{http://oss.sgi.com/projects/FreeB/,http://oss.sgi.com/projects/FreeB/}.
13
14@end copying
15
16The functions from this section may be had by loading the module:
17
18@example
19(use-modules (figl low-level glx))
20@end example
21
22@defun glXChooseFBConfig
23@heading return a list of GLX frame buffer configurations that match the specified attributes
24@heading Parameters
25@table @asis
26@item @var{dpy}
27Specifies the connection to the X server.
28
29@item @var{screen}
30Specifies the screen number.
31
32@item @var{attrib_list}
33Specifies a list of attribute/value pairs. The last attribute must be
34@code{None}.
35
36@item @var{nelements}
37Returns the number of elements in the list returned by
38@code{glXChooseFBConfig}.
39
40@end table
41
42@heading Description
43@code{glXChooseFBConfig} returns GLX frame buffer configurations that
44match the attributes specified in @var{attrib_list}, or @code{NULL} if
45no matches are found. If @var{attrib_list} is @code{NULL}, then
46@code{glXChooseFBConfig} returns an array of GLX frame buffer
47configurations that are available on the specified screen. If an error
48occurs, no frame buffer configurations exist on the specified screen, or
49if no frame buffer configurations match the specified attributes, then
50@code{NULL} is returned. Use @code{XFree} to free the memory returned by
51@code{glXChooseFBConfig}.
52
53All attributes in @var{attrib_list}, including boolean attributes, are
54immediately followed by the corresponding desired value. The list is
55terminated with @code{None}. If an attribute is not specified in
56@var{attrib_list}, then the default value (see below) is used (and the
57attribute is said to be specified implicitly). For example, if
58@code{GLX_STEREO} is not specified, then it is assumed to be
59@code{False}. For some attributes, the default is @code{GLX_DONT_CARE},
60meaning that any value is OK for this attribute, so the attribute will
61not be checked.
62
63Attributes are matched in an attribute-specific manner. Some of the
64attributes, such as @code{GLX_LEVEL}, must match the specified value
65exactly; others, such as, @code{GLX_RED_SIZE} must meet or exceed the
66specified minimum values. If more than one GLX frame buffer
67configuration is found, then a list of configurations, sorted according
68to the ``best'' match criteria, is returned. The match criteria for each
69attribute and the exact sorting order is defined below.
70
71The interpretations of the various GLX visual attributes are as follows:
72
73@table @asis
74@item @code{GLX_FBCONFIG_ID}
75
76
77Must be followed by a valid XID that indicates the desired GLX frame
78buffer configuration. When a @code{GLX_FBCONFIG_ID} is specified, all
79attributes are ignored. The default value is @code{GLX_DONT_CARE}.
80
81@item @code{GLX_BUFFER_SIZE}
82
83
84Must be followed by a nonnegative integer that indicates the desired
85color index buffer size. The smallest index buffer of at least the
86specified size is preferred. This attribute is ignored if
87@code{GLX_COLOR_INDEX_BIT} is not set in @code{GLX_RENDER_TYPE}. The
88default value is 0.
89
90@item @code{GLX_LEVEL}
91
92
93Must be followed by an integer buffer-level specification. This
94specification is honored exactly. Buffer level 0 corresponds to the
95default frame buffer of the display. Buffer level 1 is the first overlay
96frame buffer, level two the second overlay frame buffer, and so on.
97Negative buffer levels correspond to underlay frame buffers. The default
98value is 0.
99
100@item @code{GLX_DOUBLEBUFFER}
101
102
103Must be followed by @code{True} or @code{False}. If @code{True} is
104specified, then only double-buffered frame buffer configurations are
105considered; if @code{False} is specified, then only single-buffered
106frame buffer configurations are considered. The default value is
107@code{GLX_DONT_CARE}.
108
109@item @code{GLX_STEREO}
110
111
112Must be followed by @code{True} or @code{False}. If @code{True} is
113specified, then only stereo frame buffer configurations are considered;
114if @code{False} is specified, then only monoscopic frame buffer
115configurations are considered. The default value is @code{False}.
116
117@item @code{GLX_AUX_BUFFERS}
118
119
120Must be followed by a nonnegative integer that indicates the desired
121number of auxiliary buffers. Configurations with the smallest number of
122auxiliary buffers that meet or exceed the specified number are
123preferred. The default value is 0.
124
125@item @code{GLX_RED_SIZE}, @code{GLX_GREEN_SIZE}, @code{GLX_BLUE_SIZE}, @code{GLX_ALPHA_SIZE}
126
127
128Each attribute, if present, must be followed by a nonnegative minimum
129size specification or @code{GLX_DONT_CARE}. The largest available total
130RGBA color buffer size (sum of @code{GLX_RED_SIZE},
131@code{GLX_GREEN_SIZE}, @code{GLX_BLUE_SIZE}, and @code{GLX_ALPHA_SIZE})
132of at least the minimum size specified for each color component is
133preferred. If the requested number of bits for a color component is 0 or
134@code{GLX_DONT_CARE}, it is not considered. The default value for each
135color component is 0.
136
137@item @code{GLX_DEPTH_SIZE}
138
139
140Must be followed by a nonnegative minimum size specification. If this
141value is zero, frame buffer configurations with no depth buffer are
142preferred. Otherwise, the largest available depth buffer of at least the
143minimum size is preferred. The default value is 0.
144
145@item @code{GLX_STENCIL_SIZE}
146
147
148Must be followed by a nonnegative integer that indicates the desired
149number of stencil bitplanes. The smallest stencil buffer of at least the
150specified size is preferred. If the desired value is zero, frame buffer
151configurations with no stencil buffer are preferred. The default value
152is 0.
153
154@item @code{GLX_ACCUM_RED_SIZE}
155
156
157Must be followed by a nonnegative minimum size specification. If this
158value is zero, frame buffer configurations with no red accumulation
159buffer are preferred. Otherwise, the largest possible red accumulation
160buffer of at least the minimum size is preferred. The default value is
1610.
162
163@item @code{GLX_ACCUM_GREEN_SIZE}
164
165
166Must be followed by a nonnegative minimum size specification. If this
167value is zero, frame buffer configurations with no green accumulation
168buffer are preferred. Otherwise, the largest possible green accumulation
169buffer of at least the minimum size is preferred. The default value is
1700.
171
172@item @code{GLX_ACCUM_BLUE_SIZE}
173
174
175Must be followed by a nonnegative minimum size specification. If this
176value is zero, frame buffer configurations with no blue accumulation
177buffer are preferred. Otherwise, the largest possible blue accumulation
178buffer of at least the minimum size is preferred. The default value is
1790.
180
181@item @code{GLX_ACCUM_ALPHA_SIZE}
182
183
184Must be followed by a nonnegative minimum size specification. If this
185value is zero, frame buffer configurations with no alpha accumulation
186buffer are preferred. Otherwise, the largest possible alpha accumulation
187buffer of at least the minimum size is preferred. The default value is
1880.
189
190@item @code{GLX_RENDER_TYPE}
191
192
193Must be followed by a mask indicating which OpenGL rendering modes the
194frame buffer configuration must support. Valid bits are
195@code{GLX_RGBA_BIT} and @code{GLX_COLOR_INDEX_BIT}. If the mask is set
196to @code{GLX_RGBA_BIT} | @code{GLX_COLOR_INDEX_BIT}, then only frame
197buffer configurations that can be bound to both RGBA contexts and color
198index contexts will be considered. The default value is
199@code{GLX_RGBA_BIT}.
200
201@item @code{GLX_DRAWABLE_TYPE}
202
203
204Must be followed by a mask indicating which GLX drawable types the frame
205buffer configuration must support. Valid bits are @code{GLX_WINDOW_BIT},
206@code{GLX_PIXMAP_BIT}, and @code{GLX_PBUFFER_BIT}. For example, if mask
207is set to @code{GLX_WINDOW_BIT} | @code{GLX_PIXMAP_BIT}, only frame
208buffer configurations that support both windows and GLX pixmaps will be
209considered. The default value is @code{GLX_WINDOW_BIT}.
210
211@item @code{GLX_X_RENDERABLE}
212
213
214Must be followed by @code{True} or @code{False}. If @code{True} is
215specified, then only frame buffer configurations that have associated X
216visuals (and can be used to render to Windows and/or GLX pixmaps) will
217be considered. The default value is @code{GLX_DONT_CARE}.
218
219@item @code{GLX_X_VISUAL_TYPE}
220
221
222Must be followed by one of @code{GLX_TRUE_COLOR},
223@code{GLX_DIRECT_COLOR}, @code{GLX_PSEUDO_COLOR},
224@code{GLX_STATIC_COLOR}, @code{GLX_GRAY_SCALE}, or
225@code{GLX_STATIC_GRAY}, indicating the desired X visual type. Not all
226frame buffer configurations have an associated X visual. If
227@code{GLX_DRAWABLE_TYPE} is specified in @var{attrib_list} and the mask
228that follows does not have @code{GLX_WINDOW_BIT} set, then this value is
229ignored. It is also ignored if @code{GLX_X_RENDERABLE} is specified as
230@code{False}. RGBA rendering may be supported for visuals of type
231@code{GLX_TRUE_COLOR}, @code{GLX_DIRECT_COLOR}, @code{GLX_PSEUDO_COLOR},
232or @code{GLX_STATIC_COLOR}, but color index rendering is only supported
233for visuals of type @code{GLX_PSEUDO_COLOR} or @code{GLX_STATIC_COLOR}
234(i.e., single-channel visuals). The tokens @code{GLX_GRAY_SCALE} and
235@code{GLX_STATIC_GRAY} will not match current OpenGL enabled visuals,
236but are included for future use. The default value for
237@code{GLX_X_VISUAL_TYPE} is @code{GLX_DONT_CARE}.
238
239@item @code{GLX_CONFIG_CAVEAT}
240
241
242Must be followed by one of @code{GLX_NONE}, @code{GLX_SLOW_CONFIG},
243@code{GLX_NON_CONFORMANT_CONFIG}. If @code{GLX_NONE} is specified, then
244only frame buffer configurations with no caveats will be considered; if
245@code{GLX_SLOW_CONFIG} is specified, then only slow frame buffer
246configurations will be considered; if @code{GLX_NON_CONFORMANT_CONFIG}
247is specified, then only nonconformant frame buffer configurations will
248be considered. The default value is @code{GLX_DONT_CARE}.
249
250@item @code{GLX_TRANSPARENT_TYPE}
251
252
253Must be followed by one of @code{GLX_NONE}, @code{GLX_TRANSPARENT_RGB},
254@code{GLX_TRANSPARENT_INDEX}. If @code{GLX_NONE} is specified, then only
255opaque frame buffer configurations will be considered; if
256@code{GLX_TRANSPARENT_RGB} is specified, then only transparent frame
257buffer configurations that support RGBA rendering will be considered; if
258@code{GLX_TRANSPARENT_INDEX} is specified, then only transparent frame
259buffer configurations that support color index rendering will be
260considered. The default value is @code{GLX_NONE}.
261
262@item @code{GLX_TRANSPARENT_INDEX_VALUE}
263
264
265Must be followed by an integer value indicating the transparent index
266value; the value must be between 0 and the maximum frame buffer value
267for indices. Only frame buffer configurations that use the specified
268transparent index value will be considered. The default value is
269@code{GLX_DONT_CARE}. This attribute is ignored unless
270@code{GLX_TRANSPARENT_TYPE} is included in @var{attrib_list} and
271specified as @code{GLX_TRANSPARENT_INDEX}.
272
273@item @code{GLX_TRANSPARENT_RED_VALUE}
274
275
276Must be followed by an integer value indicating the transparent red
277value; the value must be between 0 and the maximum frame buffer value
278for red. Only frame buffer configurations that use the specified
279transparent red value will be considered. The default value is
280@code{GLX_DONT_CARE}. This attribute is ignored unless
281@code{GLX_TRANSPARENT_TYPE} is included in @var{attrib_list} and
282specified as @code{GLX_TRANSPARENT_RGB}.
283
284@item @code{GLX_TRANSPARENT_GREEN_VALUE}
285
286
287Must be followed by an integer value indicating the transparent green
288value; the value must be between 0 and the maximum frame buffer value
289for green. Only frame buffer configurations that use the specified
290transparent green value will be considered. The default value is
291@code{GLX_DONT_CARE}. This attribute is ignored unless
292@code{GLX_TRANSPARENT_TYPE} is included in @var{attrib_list} and
293specified as @code{GLX_TRANSPARENT_RGB}.
294
295@item @code{GLX_TRANSPARENT_BLUE_VALUE}
296
297
298Must be followed by an integer value indicating the transparent blue
299value; the value must be between 0 and the maximum frame buffer value
300for blue. Only frame buffer configurations that use the specified
301transparent blue value will be considered. The default value is
302@code{GLX_DONT_CARE}. This attribute is ignored unless
303@code{GLX_TRANSPARENT_TYPE} is included in @var{attrib_list} and
304specified as @code{GLX_TRANSPARENT_RGB}.
305
306@item @code{GLX_TRANSPARENT_ALPHA_VALUE}
307
308
309Must be followed by an integer value indicating the transparent alpha
310value; the value must be between 0 and the maximum frame buffer value
311for alpha. Only frame buffer configurations that use the specified
312transparent alpha value will be considered. The default value is
313@code{GLX_DONT_CARE}.
314
315@end table
316
317When more than one GLX frame buffer configuration matches the specified
318attributes, a list of matching configurations is returned. The list is
319sorted according to the following precedence rules, which are applied in
320ascending order (i.e., configurations that are considered equal by a
321lower numbered rule are sorted by the higher numbered rule):
322
323@table @asis
324@item 1.
325By @code{GLX_CONFIG_CAVEAT} where the precedence is @code{GLX_NONE},
326@code{GLX_SLOW_CONFIG}, and @code{GLX_NON_CONFORMANT_CONFIG}.
327
328@item 2.
329Larger total number of RGBA color components (@code{GLX_RED_SIZE},
330@code{GLX_GREEN_SIZE}, @code{GLX_BLUE_SIZE}, plus @code{GLX_ALPHA_SIZE})
331that have higher number of bits. If the requested number of bits in
332@var{attrib_list} is zero or @code{GLX_DONT_CARE} for a particular color
333component, then the number of bits for that component is not considered.
334
335@item 3.
336Smaller @code{GLX_BUFFER_SIZE}.
337
338@item 4.
339Single buffered configuration (@code{GLX_DOUBLEBUFFER} being
340@code{False} precedes a double buffered one.
341
342@item 5.
343Smaller @code{GLX_AUX_BUFFERS}.
344
345@item 6.
346Larger @code{GLX_DEPTH_SIZE}.
347
348@item 7.
349Smaller @code{GLX_STENCIL_SIZE}.
350
351@item 8.
352Larger total number of accumulation buffer color components
353(@code{GLX_ACCUM_RED_SIZE}, @code{GLX_ACCUM_GREEN_SIZE},
354@code{GLX_ACCUM_BLUE_SIZE}, plus @code{GLX_ACCUM_ALPHA_SIZE}) that have
355higher number of bits. If the requested number of bits in
356@var{attrib_list} is zero or @code{GLX_DONT_CARE} for a particular color
357component, then the number of bits for that component is not considered.
358
359@item 9.
360By @code{GLX_X_VISUAL_TYPE} where the precedence order is
361@code{GLX_TRUE_COLOR}, @code{GLX_DIRECT_COLOR}, @code{GLX_PSEUDO_COLOR},
362@code{GLX_STATIC_COLOR}, @code{GLX_GRAY_SCALE}, @code{GLX_STATIC_GRAY}.
363
364@end table
365
366@heading Errors
367@code{NULL} is returned if an undefined GLX attribute is encountered in
368@var{attrib_list}, if @var{screen} is invalid, or if @var{dpy} does not
369support the GLX extension.
370
371@end defun
372
373@defun glXChooseVisual
374@heading return a visual that matches specified attributes
375@heading Parameters
376@table @asis
377@item @var{dpy}
378Specifies the connection to the X server.
379
380@item @var{screen}
381Specifies the screen number.
382
383@item @var{attribList}
384Specifies a list of boolean attributes and integer attribute/value
385pairs. The last attribute must be @code{None}.
386
387@end table
388
389@heading Description
390@code{glXChooseVisual} returns a pointer to an XVisualInfo structure
391describing the visual that best meets a minimum specification. The
392boolean GLX attributes of the visual that is returned will match the
393specified values, and the integer GLX attributes will meet or exceed the
394specified minimum values. If all other attributes are equivalent, then
395TrueColor and PseudoColor visuals have priority over DirectColor and
396StaticColor visuals, respectively. If no conforming visual exists,
397@code{NULL} is returned. To free the data returned by this function, use
398@code{XFree}.
399
400All boolean GLX attributes default to @code{False} except
401@code{GLX_USE_GL}, which defaults to @code{True}. All integer GLX
402attributes default to zero. Default specifications are superseded by
403attributes included in @var{attribList}. Boolean attributes included in
404@var{attribList} are understood to be @code{True}. Integer attributes
405and enumerated type attributes are followed immediately by the
406corresponding desired or minimum value. The list must be terminated with
407@code{None}.
408
409The interpretations of the various GLX visual attributes are as follows:
410
411@table @asis
412@item @code{GLX_USE_GL}
413Ignored. Only visuals that can be rendered with GLX are considered.
414
415@item @code{GLX_BUFFER_SIZE}
416Must be followed by a nonnegative integer that indicates the desired
417color index buffer size. The smallest index buffer of at least the
418specified size is preferred. Ignored if @code{GLX_RGBA} is asserted.
419
420@item @code{GLX_LEVEL}
421Must be followed by an integer buffer-level specification. This
422specification is honored exactly. Buffer level zero corresponds to the
423main frame buffer of the display. Buffer level one is the first overlay
424frame buffer, level two the second overlay frame buffer, and so on.
425Negative buffer levels correspond to underlay frame buffers.
426
427@item @code{GLX_RGBA}
428If present, only TrueColor and DirectColor visuals are considered.
429Otherwise, only PseudoColor and StaticColor visuals are considered.
430
431@item @code{GLX_DOUBLEBUFFER}
432If present, only double-buffered visuals are considered. Otherwise, only
433single-buffered visuals are considered.
434
435@item @code{GLX_STEREO}
436If present, only stereo visuals are considered. Otherwise, only
437monoscopic visuals are considered.
438
439@item @code{GLX_AUX_BUFFERS}
440Must be followed by a nonnegative integer that indicates the desired
441number of auxiliary buffers. Visuals with the smallest number of
442auxiliary buffers that meets or exceeds the specified number are
443preferred.
444
445@item @code{GLX_RED_SIZE}
446Must be followed by a nonnegative minimum size specification. If this
447value is zero, the smallest available red buffer is preferred.
448Otherwise, the largest available red buffer of at least the minimum size
449is preferred.
450
451@item @code{GLX_GREEN_SIZE}
452Must be followed by a nonnegative minimum size specification. If this
453value is zero, the smallest available green buffer is preferred.
454Otherwise, the largest available green buffer of at least the minimum
455size is preferred.
456
457@item @code{GLX_BLUE_SIZE}
458Must be followed by a nonnegative minimum size specification. If this
459value is zero, the smallest available blue buffer is preferred.
460Otherwise, the largest available blue buffer of at least the minimum
461size is preferred.
462
463@item @code{GLX_ALPHA_SIZE}
464Must be followed by a nonnegative minimum size specification. If this
465value is zero, the smallest available alpha buffer is preferred.
466Otherwise, the largest available alpha buffer of at least the minimum
467size is preferred.
468
469@item @code{GLX_DEPTH_SIZE}
470Must be followed by a nonnegative minimum size specification. If this
471value is zero, visuals with no depth buffer are preferred. Otherwise,
472the largest available depth buffer of at least the minimum size is
473preferred.
474
475@item @code{GLX_STENCIL_SIZE}
476Must be followed by a nonnegative integer that indicates the desired
477number of stencil bitplanes. The smallest stencil buffer of at least the
478specified size is preferred. If the desired value is zero, visuals with
479no stencil buffer are preferred.
480
481@item @code{GLX_ACCUM_RED_SIZE}
482Must be followed by a nonnegative minimum size specification. If this
483value is zero, visuals with no red accumulation buffer are preferred.
484Otherwise, the largest possible red accumulation buffer of at least the
485minimum size is preferred.
486
487@item @code{GLX_ACCUM_GREEN_SIZE}
488Must be followed by a nonnegative minimum size specification. If this
489value is zero, visuals with no green accumulation buffer are preferred.
490Otherwise, the largest possible green accumulation buffer of at least
491the minimum size is preferred.
492
493@item @code{GLX_ACCUM_BLUE_SIZE}
494Must be followed by a nonnegative minimum size specification. If this
495value is zero, visuals with no blue accumulation buffer are preferred.
496Otherwise, the largest possible blue accumulation buffer of at least the
497minimum size is preferred.
498
499@item @code{GLX_ACCUM_ALPHA_SIZE}
500Must be followed by a nonnegative minimum size specification. If this
501value is zero, visuals with no alpha accumulation buffer are preferred.
502Otherwise, the largest possible alpha accumulation buffer of at least
503the minimum size is preferred.
504
505@end table
506
507@heading Errors
508@code{NULL} is returned if an undefined GLX attribute is encountered in
509@var{attribList}.
510
511@end defun
512
513@defun glXCopyContext
514@heading copy state from one rendering context to another
515@heading Parameters
516@table @asis
517@item @var{dpy}
518Specifies the connection to the X server.
519
520@item @var{src}
521Specifies the source context.
522
523@item @var{dst}
524Specifies the destination context.
525
526@item @var{mask}
527Specifies which portions of @var{src} state are to be copied to
528@var{dst}.
529
530@end table
531
532@heading Description
533@code{glXCopyContext} copies selected groups of state variables from
534@var{src} to @var{dst}. @var{mask} indicates which groups of state
535variables are to be copied. @var{mask} contains the bitwise OR of the
536same symbolic names that are passed to the GL command
537@code{glPushAttrib}. The single symbolic constant
538@code{GLX_ALL_ATTRIB_BITS} can be used to copy the maximum possible
539portion of rendering state.
540
541The copy can be done only if the renderers named by @var{src} and
542@var{dst} share an address space. Two rendering contexts share an
543address space if both are nondirect using the same server, or if both
544are direct and owned by a single process. Note that in the nondirect
545case it is not necessary for the calling threads to share an address
546space, only for their related rendering contexts to share an address
547space.
548
549Not all values for GL state can be copied. For example, pixel pack and
550unpack state, render mode state, and select and feedback state are not
551copied. The state that can be copied is exactly the state that is
552manipulated by the GL command @code{glPushAttrib}.
553
554An implicit @code{glFlush} is done by @code{glXCopyContext} if @var{src}
555is the current context for the calling thread.
556
557@heading Errors
558@code{BadMatch} is generated if rendering contexts @var{src} and
559@var{dst} do not share an address space or were not created with respect
560to the same screen.
561
562@code{BadAccess} is generated if @var{dst} is current to any thread
563(including the calling thread) at the time @code{glXCopyContext} is
564called.
565
566@code{GLXBadCurrentWindow} is generated if @var{src} is the current
567context and the current drawable is a window that is no longer valid.
568
569@code{GLXBadContext} is generated if either @var{src} or @var{dst} is
570not a valid GLX context.
571
572@end defun
573
574@defun glXCreateContext
575@heading create a new GLX rendering context
576@heading Parameters
577@table @asis
578@item @var{dpy}
579Specifies the connection to the X server.
580
581@item @var{vis}
582Specifies the visual that defines the frame buffer resources available
583to the rendering context. It is a pointer to an @code{XVisualInfo}
584structure, not a visual ID or a pointer to a @code{Visual}.
585
586@item @var{shareList}
587Specifies the context with which to share display lists. @code{NULL}
588indicates that no sharing is to take place.
589
590@item @var{direct}
591Specifies whether rendering is to be done with a direct connection to
592the graphics system if possible (@code{True}) or through the X server
593(@code{False}).
594
595@end table
596
597@heading Description
598@code{glXCreateContext} creates a GLX rendering context and returns its
599handle. This context can be used to render into both windows and GLX
600pixmaps. If @code{glXCreateContext} fails to create a rendering context,
601@code{NULL} is returned.
602
603If @var{direct} is @code{True}, then a direct rendering context is
604created if the implementation supports direct rendering, if the
605connection is to an X server that is local, and if a direct rendering
606context is available. (An implementation may return an indirect context
607when @var{direct} is @code{True}.) If @var{direct} is @code{False}, then
608a rendering context that renders through the X server is always created.
609Direct rendering provides a performance advantage in some
610implementations. However, direct rendering contexts cannot be shared
611outside a single process, and they may be unable to render to GLX
612pixmaps.
613
614If @var{shareList} is not @code{NULL}, then all display-list indexes and
615definitions are shared by context @var{shareList} and by the newly
616created context. An arbitrary number of contexts can share a single
617display-list space. However, all rendering contexts that share a single
618display-list space must themselves exist in the same address space. Two
619rendering contexts share an address space if both are nondirect using
620the same server, or if both are direct and owned by a single process.
621Note that in the nondirect case, it is not necessary for the calling
622threads to share an address space, only for their related rendering
623contexts to share an address space.
624
625If the GL version is 1.1 or greater, then all texture objects except
626object 0 are shared by any contexts that share display lists.
627
628@heading Errors
629@code{NULL} is returned if execution fails on the client side.
630
631@code{BadMatch} is generated if the context to be created would not
632share the address space or the screen of the context specified by
633@var{shareList}.
634
635@code{BadValue} is generated if @var{vis} is not a valid visual (for
636example, if a particular GLX implementation does not support it).
637
638@code{GLXBadContext} is generated if @var{shareList} is not a GLX
639context and is not @code{NULL}.
640
641@code{BadAlloc} is generated if the server does not have enough
642resources to allocate the new context.
643
644@end defun
645
646@defun glXCreateGLXPixmap
647@heading create an off-screen GLX rendering area
648@heading Parameters
649@table @asis
650@item @var{dpy}
651Specifies the connection to the X server.
652
653@item @var{vis}
654Specifies the visual that defines the structure of the rendering area.
655It is a pointer to an @code{XVisualInfo} structure, not a visual ID or a
656pointer to a @code{Visual}.
657
658@item @var{pixmap}
659Specifies the X pixmap that will be used as the front left color buffer
660of the off-screen rendering area.
661
662@end table
663
664@heading Description
665@code{glXCreateGLXPixmap} creates an off-screen rendering area and
666returns its XID. Any GLX rendering context that was created with respect
667to @var{vis} can be used to render into this off-screen area. Use
668@code{glXMakeCurrent} to associate the rendering area with a GLX
669rendering context.
670
671The X pixmap identified by @var{pixmap} is used as the front left buffer
672of the resulting off-screen rendering area. All other buffers specified
673by @var{vis}, including color buffers other than the front left buffer,
674are created without externally visible names. GLX pixmaps with
675double-buffering are supported. However, @code{glXSwapBuffers} is
676ignored by these pixmaps.
677
678Some implementations may not support GLX pixmaps with direct rendering
679contexts.
680
681@heading Errors
682@code{BadMatch} is generated if the depth of @var{pixmap} does not match
683the depth value reported by core X11 for @var{vis}, or if @var{pixmap}
684was not created with respect to the same screen as @var{vis}.
685
686@code{BadValue} is generated if @var{vis} is not a valid XVisualInfo
687pointer (for example, if a particular GLX implementation does not
688support this visual).
689
690@code{BadPixmap} is generated if @var{pixmap} is not a valid pixmap.
691
692@code{BadAlloc} is generated if the server cannot allocate the GLX
693pixmap.
694
695@end defun
696
697@defun glXCreateNewContext
698@heading create a new GLX rendering context
699@heading Parameters
700@table @asis
701@item @var{dpy}
702Specifies the connection to the X server.
703
704@item @var{config}
705Specifies the GLXFBConfig structure with the desired attributes for the
706context.
707
708@item @var{render_type}
709Specifies the type of the context to be created. Must be one of
710@code{GLX_RGBA_TYPE} or @code{GLX_COLOR_INDEX_TYPE}.
711
712@item @var{share_list}
713Specifies the context with which to share display lists. @code{NULL}
714indicates that no sharing is to take place.
715
716@item @var{share_list}
717Specifies whether rendering is to be done with a direct connection to
718the graphics system if possible (@code{True}) or through the X server
719(@code{False}).
720
721@end table
722
723@heading Description
724@code{glXCreateNewContext} creates a GLX rendering context and returns
725its handle. This context can be used to render into GLX windows,
726pixmaps, or pixel buffers. If @code{glXCreateNewContext} fails to create
727a rendering context, @code{NULL} is returned.
728
729If @var{render_type} is @code{GLX_RGBA_TYPE}, then a context that
730supports RGBA rendering is created. If @var{config} is
731@code{GLX_COLOR_INDEX_TYPE}, then context supporting color-index
732rendering is created.
733
734If @var{render_type} is not @code{NULL}, then all display-list indexes
735and definitions are shared by context @var{render_type} and by the newly
736created context. An arbitrary number of contexts can share a single
737display-list space. However, all rendering contexts that share a single
738display-list space must themselves exist in the same address space. Two
739rendering contexts share an address space if both are nondirect using
740the same server, or if both are direct and owned by a single process.
741Note that in the nondirect case, it is not necessary for the calling
742threads to share an address space, only for their related rendering
743contexts to share an address space.
744
745If @var{share_list} is @code{True}, then a direct-rendering context is
746created if the implementation supports direct rendering, if the
747connection is to an X server that is local, and if a direct-rendering
748context is available. (An implementation may return an indirect context
749when @var{share_list} is @code{True}.) If @var{share_list} is
750@code{False}, then a rendering context that renders through the X server
751is always created. Direct rendering provides a performance advantage in
752some implementations. However, direct-rendering contexts cannot be
753shared outside a single process, and they may be unable to render to GLX
754pixmaps.
755
756@heading Errors
757@code{NULL} is returned if execution fails on the client side.
758
759@code{GLXBadContext} is generated if @var{render_type} is not a GLX
760context and is not @code{NULL}.
761
762@code{GLXBadFBConfig} is generated if @var{config} is not a valid
763GLXFBConfig.
764
765@code{BadMatch} is generated if the context to be created would not
766share the address space or the screen of the context specified by
767@var{render_type}.
768
769@code{BadAlloc} is generated if the server does not have enough
770resources to allocate the new context.
771
772@code{BadValue} is generated if @var{config} is not a valid visual (for
773example, if a particular GLX implementation does not support it).
774
775@end defun
776
777@defun glXCreatePbuffer
778@heading create an off-screen rendering area
779@heading Parameters
780@table @asis
781@item @var{dpy}
782Specifies the connection to the X server.
783
784@item @var{config}
785Specifies a GLXFBConfig structure with the desired attributes for the
786window.
787
788@item @var{attrib_list}
789Specifies a list of attribute value pairs, which must be terminated with
790@code{None} or @code{NULL}. Accepted attributes are
791@code{GLX_PBUFFER_WIDTH}, @code{GLX_PBUFFER_HEIGHT},
792@code{GLX_PRESERVED_CONTENTS}, and @code{GLX_LARGEST_PBUFFER}.
793
794@end table
795
796@heading Description
797@code{glXCreatePbuffer} creates an off-screen rendering area and returns
798its XID. Any GLX rendering context that was created with respect to
799@var{config} can be used to render into this window. Use
800@code{glXMakeContextCurrent} to associate the rendering area with a GLX
801rendering context.
802
803The accepted attributes for a GLXPbuffer are:
804
805@table @asis
806@item @code{GLX_PBUFFER_WIDTH}
807Specify the pixel width of the requested GLXPbuffer. The default value
808is 0.
809
810@item @code{GLX_PBUFFER_HEIGHT}
811Specify the pixel height of the requested GLXPbuffer. The default value
812is 0.
813
814@item @code{GLX_LARGEST_PBUFFER}
815Specify to obtain the largest available pixel buffer, if the requested
816allocation would have failed. The width and height of the allocated
817pixel buffer will never exceed the specified @code{GLX_PBUFFER_WIDTH} or
818@code{GLX_PBUFFER_HEIGHT}, respectively. Use @code{glXQueryDrawable} to
819retrieve the dimensions of the allocated pixel buffer. The default value
820is @code{False}.
821
822@item @code{GLX_PRESERVED_CONTENTS}
823Specify if the contents of the pixel buffer should be preserved when a
824resource conflict occurs. If set to @code{False}, the contents of the
825pixel buffer may be lost at any time. If set to @code{True}, or not
826specified in @var{attrib_list}, then the contents of the pixel buffer
827will be preserved (most likely by copying the contents into main system
828memory from the frame buffer). In either case, the client can register
829(using @code{glXSelectEvent}, to receive pixel buffer clobber events
830that are generated when the pbuffer contents have been preserved or
831damaged.
832
833@end table
834
835GLXPbuffers contain the color and ancillary buffers specified by
836@var{config}. It is possible to create a pixel buffer with back buffers
837and to swap those buffers using @code{glXSwapBuffers}.
838
839@heading Errors
840@code{BadAlloc} is generated if there are insufficient resources to
841allocate the requested GLXPbuffer.
842
843@code{GLXBadFBConfig} is generated if @var{config} is not a valid
844GLXFBConfig.
845
846@code{BadMatch} is generated if @var{config} does not support rendering
847to pixel buffers (e.g., @code{GLX_DRAWABLE_TYPE} does not contain
848@code{GLX_PBUFFER_BIT}).
849
850@end defun
851
852@defun glXCreatePixmap
853@heading create an off-screen rendering area
854@heading Parameters
855@table @asis
856@item @var{dpy}
857Specifies the connection to the X server.
858
859@item @var{config}
860Specifies a GLXFBConfig structure with the desired attributes for the
861window.
862
863@item @var{pixmap}
864Specifies the X pixmap to be used as the rendering area.
865
866@item @var{attrib_list}
867Currently unused. This must be set to @code{NULL} or be an empty list
868(i.e., one in which the first element is @code{None}).
869
870@end table
871
872@heading Description
873@code{glXCreatePixmap} creates an off-screen rendering area and returns
874its XID. Any GLX rendering context that was created with respect to
875@var{config} can be used to render into this window. Use
876@code{glXMakeCurrent} to associate the rendering area with a GLX
877rendering context.
878
879@heading Errors
880@code{BadMatch} is generated if @var{pixmap} was not created with a
881visual that corresponds to @var{config}.
882
883@code{BadMatch} is generated if @var{config} does not support rendering
884to windows (e.g., @code{GLX_DRAWABLE_TYPE} does not contain
885@code{GLX_WINDOW_BIT}).
886
887@code{BadWindow} is generated if @var{pixmap} is not a valid window XID.
888@code{BadAlloc} is generated if there is already a GLXFBConfig
889associated with @var{pixmap}.
890
891@code{BadAlloc} is generated if the X server cannot allocate a new GLX
892window.
893
894@code{GLXBadFBConfig} is generated if @var{config} is not a valid
895GLXFBConfig.
896
897
898
899@end defun
900
901@defun glXCreateWindow
902@heading create an on-screen rendering area
903@heading Parameters
904@table @asis
905@item @var{dpy}
906Specifies the connection to the X server.
907
908@item @var{config}
909Specifies a GLXFBConfig structure with the desired attributes for the
910window.
911
912@item @var{win}
913Specifies the X window to be used as the rendering area.
914
915@item @var{attrib_list}
916Currently unused. This must be set to @code{NULL} or be an empty list
917(i.e., one in which the first element is @code{None}).
918
919@end table
920
921@heading Description
922@code{glXCreateWindow} creates an on-screen rendering area from an
923existing X window that was created with a visual matching @var{config}.
924The XID of the GLXWindow is returned. Any GLX rendering context that was
925created with respect to @var{config} can be used to render into this
926window. Use @code{glXMakeContextCurrent} to associate the rendering area
927with a GLX rendering context.
928
929@heading Errors
930@code{BadMatch} is generated if @var{win} was not created with a visual
931that corresponds to @var{config}.
932
933@code{BadMatch} is generated if @var{config} does not support rendering
934to windows (i.e., @code{GLX_DRAWABLE_TYPE} does not contain
935@code{GLX_WINDOW_BIT}).
936
937@code{BadWindow} is generated if @var{win} is not a valid pixmap XID.
938
939@code{BadAlloc} is generated if there is already a GLXFBConfig
940associated with @var{win}.
941
942@code{BadAlloc} is generated if the X server cannot allocate a new GLX
943window.
944
945@code{GLXBadFBConfig} is generated if @var{config} is not a valid
946GLXFBConfig.
947
948
949
950@end defun
951
952@defun glXDestroyContext
953@heading destroy a GLX context
954@heading Parameters
955@table @asis
956@item @var{dpy}
957Specifies the connection to the X server.
958
959@item @var{ctx}
960Specifies the GLX context to be destroyed.
961
962@end table
963
964@heading Description
965If the GLX rendering context @var{ctx} is not current to any thread,
966@code{glXDestroyContext} destroys it immediately. Otherwise, @var{ctx}
967is destroyed when it becomes not current to any thread. In either case,
968the resource ID referenced by @var{ctx} is freed immediately.
969
970@heading Errors
971@code{GLXBadContext} is generated if @var{ctx} is not a valid GLX
972context.
973
974@end defun
975
976@defun glXDestroyGLXPixmap
977@heading destroy a GLX pixmap
978@heading Parameters
979@table @asis
980@item @var{dpy}
981Specifies the connection to the X server.
982
983@item @var{pix}
984Specifies the GLX pixmap to be destroyed.
985
986@end table
987
988@heading Description
989If the GLX pixmap @var{pix} is not current to any client,
990@code{glXDestroyGLXPixmap} destroys it immediately. Otherwise, @var{pix}
991is destroyed when it becomes not current to any client. In either case,
992the resource ID is freed immediately.
993
994@heading Errors
995@code{GLXBadPixmap} is generated if @var{pix} is not a valid GLX pixmap.
996
997@end defun
998
999@defun glXDestroyPbuffer
1000@heading destroy an off-screen rendering area
1001@heading Parameters
1002@table @asis
1003@item @var{dpy}
1004Specifies the connection to the X server.
1005
1006@item @var{pbuf}
1007Specifies the GLXPbuffer to be destroyed.
1008
1009@end table
1010
1011@heading Description
1012@code{glXDestroyPbuffer} destroys a GLXPbuffer created by
1013@code{glXCreatePbuffer}.
1014
1015@heading Errors
1016@code{GLXBadPbuffer} is generated if @var{pbuf} is not a valid
1017GLXPbuffer.
1018
1019@end defun
1020
1021@defun glXDestroyPixmap
1022@heading destroy an off-screen rendering area
1023@heading Parameters
1024@table @asis
1025@item @var{dpy}
1026Specifies the connection to the X server.
1027
1028@item @var{pixmap}
1029Specifies the GLXPixmap to be destroyed.
1030
1031@end table
1032
1033@heading Description
1034@code{glXDestroyPixmap} destroys a GLXPixmap created by
1035@code{glXCreatePixmap}.
1036
1037@heading Errors
1038@code{GLXBadPixmap} is generated if @var{pixmap} is not a valid
1039GLXPixmap.
1040
1041@end defun
1042
1043@defun glXDestroyWindow
1044@heading destroy an on-screen rendering area
1045@heading Parameters
1046@table @asis
1047@item @var{dpy}
1048Specifies the connection to the X server.
1049
1050@item @var{win}
1051Specifies the GLXWindow to be destroyed.
1052
1053@end table
1054
1055@heading Description
1056@code{glXDestroyWindow} destroys a GLXWindow created by
1057@code{glXCreateWindow}.
1058
1059@heading Errors
1060@code{GLXBadWindow} is generated if @var{win} is not a valid GLXPixmap.
1061
1062@end defun
1063
1064@defun glXFreeContextEXT
1065@heading free client-side memory for imported context
1066@heading Parameters
1067@table @asis
1068@item @var{dpy}
1069Specifies the connection to the X server.
1070
1071@item @var{ctx}
1072Specifies a GLX rendering context.
1073
1074@end table
1075
1076@heading Description
1077@code{glXFreeContextEXT} frees the client-side part of a GLXContext that
1078was created with @code{glXImportContextEXT}. @code{glXFreeContextEXT}
1079does not free the server-side context information or the XID associated
1080with the server-side context.
1081
1082@code{glXFreeContextEXT} is part of the @code{EXT_import_context}
1083extension, not part of the core GLX command set. If
1084_glxextstring(EXT_import_context) is included in the string returned by
1085@code{glXQueryExtensionsString}, when called with argument
1086@code{GLX_EXTENSIONS}, extension @code{EXT_vertex_array} is supported.
1087
1088@heading Errors
1089@code{GLXBadContext} is generated if @var{ctx} does not refer to a valid
1090context.
1091
1092@end defun
1093
1094@defun glXGetClientString
1095@heading return a string describing the client
1096@heading Parameters
1097@table @asis
1098@item @var{dpy}
1099Specifies the connection to the X server.
1100
1101@item @var{name}
1102Specifies which string is returned. The symbolic constants
1103@code{GLX_VENDOR}, @code{GLX_VERSION}, and @code{GLX_EXTENSIONS} are
1104accepted.
1105
1106@end table
1107
1108@heading Description
1109@code{glXGetClientString} returns a string describing some aspect of the
1110client library. The possible values for @var{name} are
1111@code{GLX_VENDOR}, @code{GLX_VERSION}, and @code{GLX_EXTENSIONS}. If
1112@var{name} is not set to one of these values, @code{glXGetClientString}
1113returns @code{NULL}. The format and contents of the vendor string is
1114implementation dependent.
1115
1116The extensions string is null-terminated and contains a space-separated
1117list of extension names. (The extension names never contain spaces.) If
1118there are no extensions to GLX, then the empty string is returned.
1119
1120The version string is laid out as follows:
1121
1122<major_version.minor_version><space><vendor-specific info>
1123
1124Both the major and minor portions of the version number are of arbitrary
1125length. The vendor-specific information is optional. However, if it is
1126present, the format and contents are implementation specific.
1127
1128@end defun
1129
1130@defun glXGetConfig
1131@heading return information about GLX visuals
1132@heading Parameters
1133@table @asis
1134@item @var{dpy}
1135Specifies the connection to the X server.
1136
1137@item @var{vis}
1138Specifies the visual to be queried. It is a pointer to an
1139@code{XVisualInfo} structure, not a visual ID or a pointer to a
1140@code{Visual}.
1141
1142@item @var{attrib}
1143Specifies the visual attribute to be returned.
1144
1145@item @var{value}
1146Returns the requested value.
1147
1148@end table
1149
1150@heading Description
1151@code{glXGetConfig} sets @var{value} to the @var{attrib} value of
1152windows or GLX pixmaps created with respect to @var{vis}.
1153@code{glXGetConfig} returns an error code if it fails for any reason.
1154Otherwise, zero is returned.
1155
1156@var{attrib} is one of the following:
1157
1158
1159
1160@table @asis
1161@item @code{GLX_USE_GL}
1162@code{True} if OpenGL rendering is supported by this visual,
1163@code{False} otherwise.
1164
1165@item @code{GLX_BUFFER_SIZE}
1166Number of bits per color buffer. For RGBA visuals,
1167@code{GLX_BUFFER_SIZE} is the sum of @code{GLX_RED_SIZE},
1168@code{GLX_GREEN_SIZE}, @code{GLX_BLUE_SIZE}, and @code{GLX_ALPHA_SIZE}.
1169For color index visuals, @code{GLX_BUFFER_SIZE} is the size of the color
1170indexes.
1171
1172@item @code{GLX_LEVEL}
1173Frame buffer level of the visual. Level zero is the default frame
1174buffer. Positive levels correspond to frame buffers that overlay the
1175default buffer, and negative levels correspond to frame buffers that
1176underlay the default buffer.
1177
1178@item @code{GLX_RGBA}
1179@code{True} if color buffers store red, green, blue, and alpha values.
1180@code{False} if they store color indexes.
1181
1182@item @code{GLX_DOUBLEBUFFER}
1183@code{True} if color buffers exist in front/back pairs that can be
1184swapped, @code{False} otherwise.
1185
1186@item @code{GLX_STEREO}
1187@code{True} if color buffers exist in left/right pairs, @code{False}
1188otherwise.
1189
1190@item @code{GLX_AUX_BUFFERS}
1191Number of auxiliary color buffers that are available. Zero indicates
1192that no auxiliary color buffers exist.
1193
1194@item @code{GLX_RED_SIZE}
1195Number of bits of red stored in each color buffer. Undefined if
1196@code{GLX_RGBA} is @code{False}.
1197
1198@item @code{GLX_GREEN_SIZE}
1199Number of bits of green stored in each color buffer. Undefined if
1200@code{GLX_RGBA} is @code{False}.
1201
1202@item @code{GLX_BLUE_SIZE}
1203Number of bits of blue stored in each color buffer. Undefined if
1204@code{GLX_RGBA} is @code{False}.
1205
1206@item @code{GLX_ALPHA_SIZE}
1207Number of bits of alpha stored in each color buffer. Undefined if
1208@code{GLX_RGBA} is @code{False}.
1209
1210@item @code{GLX_DEPTH_SIZE}
1211Number of bits in the depth buffer.
1212
1213@item @code{GLX_STENCIL_SIZE}
1214Number of bits in the stencil buffer.
1215
1216@item @code{GLX_ACCUM_RED_SIZE}
1217Number of bits of red stored in the accumulation buffer.
1218
1219@item @code{GLX_ACCUM_GREEN_SIZE}
1220Number of bits of green stored in the accumulation buffer.
1221
1222@item @code{GLX_ACCUM_BLUE_SIZE}
1223Number of bits of blue stored in the accumulation buffer.
1224
1225@item @code{GLX_ACCUM_ALPHA_SIZE}
1226Number of bits of alpha stored in the accumulation buffer.
1227
1228@end table
1229
1230The X protocol allows a single visual ID to be instantiated with
1231different numbers of bits per pixel. Windows or GLX pixmaps that will be
1232rendered with OpenGL, however, must be instantiated with a color buffer
1233depth of @code{GLX_BUFFER_SIZE}.
1234
1235Although a GLX implementation can export many visuals that support GL
1236rendering, it must support at least one RGBA visual. This visual must
1237have at least one color buffer, a stencil buffer of at least 1 bit, a
1238depth buffer of at least 12 bits, and an accumulation buffer. Alpha
1239bitplanes are optional in this visual. However, its color buffer size
1240must be as great as that of the deepest @code{TrueColor},
1241@code{DirectColor}, @code{PseudoColor}, or @code{StaticColor} visual
1242supported on level zero, and it must itself be made available on level
1243zero.
1244
1245In addition, if the X server exports a @code{PseudoColor} or
1246@code{StaticColor} visual on framebuffer level 0, a color index visual
1247is also required on that level. It must have at least one color buffer,
1248a stencil buffer of at least 1 bit, and a depth buffer of at least 12
1249bits. This visual must have as many color bitplanes as the deepest
1250@code{PseudoColor} or @code{StaticColor} visual supported on level 0.
1251
1252Applications are best written to select the visual that most closely
1253meets their requirements. Creating windows or GLX pixmaps with
1254unnecessary buffers can result in reduced rendering performance as well
1255as poor resource allocation.
1256
1257@heading Errors
1258@code{GLX_NO_EXTENSION} is returned if @var{dpy} does not support the
1259GLX extension.
1260
1261@code{GLX_BAD_SCREEN} is returned if the screen of @var{vis} does not
1262correspond to a screen.
1263
1264@code{GLX_BAD_ATTRIBUTE} is returned if @var{attrib} is not a valid GLX
1265attribute.
1266
1267@code{GLX_BAD_VISUAL} is returned if @var{vis} doesn't support GLX and
1268an attribute other than @code{GLX_USE_GL} is requested.
1269
1270@end defun
1271
1272@defun glXGetContextIDEXT
1273@heading get the XID for a context.
1274@heading Parameters
1275@table @asis
1276@item @var{ctx}
1277Specifies a GLX rendering context.
1278
1279@end table
1280
1281@heading Description
1282@code{glXGetContextIDEXT} returns the XID associated with a GLXContext.
1283
1284No round trip is forced to the server; unlike most X calls that return a
1285value, @code{glXGetContextIDEXT} does not flush any pending events.
1286
1287@code{glXGetContextIDEXT} is part of the @code{EXT_import_context}
1288extension, not part of the core GLX command set. If
1289_glxextstring(EXT_import_context) is included in the string returned by
1290@code{glXQueryExtensionsString}, when called with argument
1291@code{GLX_EXTENSIONS}, extension @code{EXT_import_context} is supported.
1292
1293@heading Errors
1294@code{GLXBadContext} is generated if @var{ctx} does not refer to a valid
1295context.
1296
1297@end defun
1298
1299@defun glXGetCurrentContext
1300@heading return the current context
1301@heading Description
1302@code{glXGetCurrentContext} returns the current context, as specified by
1303@code{glXMakeCurrent}. If there is no current context, @code{NULL} is
1304returned.
1305
1306@code{glXGetCurrentContext} returns client-side information. It does not
1307make a round trip to the server.
1308
1309
1310
1311@end defun
1312
1313@defun glXGetCurrentDisplay
1314@heading get display for current context
1315@heading Description
1316@code{glXGetCurrentDisplay} returns the display for the current context.
1317If no context is current, @code{NULL} is returned.
1318
1319@code{glXGetCurrentDisplay} returns client-side information. It does not
1320make a round-trip to the server, and therefore does not flush any
1321pending events.
1322
1323@end defun
1324
1325@defun glXGetCurrentDrawable
1326@heading return the current drawable
1327@heading Description
1328@code{glXGetCurrentDrawable} returns the current drawable, as specified
1329by @code{glXMakeCurrent}. If there is no current drawable, @code{None}
1330is returned.
1331
1332@code{glXGetCurrentDrawable} returns client-side information. It does
1333not make a round trip to the server.
1334
1335@end defun
1336
1337@defun glXGetCurrentReadDrawable
1338@heading return the current drawable
1339@heading Description
1340@code{glXGetCurrentReadDrawable} returns the current read drawable, as
1341specified by @code{read} parameter of @code{glXMakeContextCurrent}. If
1342there is no current drawable, @code{None} is returned.
1343
1344@code{glXGetCurrentReadDrawable} returns client-side information. It
1345does not make a round-trip to the server.
1346
1347@end defun
1348
1349@defun glXGetFBConfigAttrib
1350@heading return information about a GLX frame buffer configuration
1351@heading Parameters
1352@table @asis
1353@item @var{dpy}
1354Specifies the connection to the X server.
1355
1356@item @var{config}
1357Specifies the GLX frame buffer configuration to be queried.
1358
1359@item @var{attribute}
1360Specifies the attribute to be returned.
1361
1362@item @var{value}
1363Returns the requested value.
1364
1365@end table
1366
1367@heading Description
1368@code{glXGetFBConfigAttrib} sets @var{value} to the @var{attribute}
1369value of GLX drawables created with respect to @var{config}.
1370@code{glXGetFBConfigAttrib} returns an error code if it fails for any
1371reason. Otherwise, @code{Success} is returned.
1372
1373@var{attribute} is one of the following:
1374
1375
1376
1377@table @asis
1378@item @code{GLX_FBCONFIG_ID}
1379XID of the given GLXFBConfig.
1380
1381@item @code{GLX_BUFFER_SIZE}
1382
1383
1384Number of bits per color buffer. If the frame buffer configuration
1385supports RGBA contexts, then @code{GLX_BUFFER_SIZE} is the sum of
1386@code{GLX_RED_SIZE}, @code{GLX_GREEN_SIZE}, @code{GLX_BLUE_SIZE}, and
1387@code{GLX_ALPHA_SIZE}. If the frame buffer configuration supports only
1388color index contexts, @code{GLX_BUFFER_SIZE} is the size of the color
1389indexes.
1390
1391@item @code{GLX_LEVEL}
1392
1393
1394Frame buffer level of the configuration. Level zero is the default frame
1395buffer. Positive levels correspond to frame buffers that overlay the
1396default buffer, and negative levels correspond to frame buffers that
1397underlie the default buffer.
1398
1399@item @code{GLX_DOUBLEBUFFER}
1400
1401
1402@code{True} if color buffers exist in front/back pairs that can be
1403swapped, @code{False} otherwise.
1404
1405@item @code{GLX_STEREO}
1406
1407
1408@code{True} if color buffers exist in left/right pairs, @code{False}
1409otherwise.
1410
1411@item @code{GLX_AUX_BUFFERS}
1412
1413
1414Number of auxiliary color buffers that are available. Zero indicates
1415that no auxiliary color buffers exist.
1416
1417@item @code{GLX_RED_SIZE}
1418
1419
1420Number of bits of red stored in each color buffer. Undefined if RGBA
1421contexts are not supported by the frame buffer configuration.
1422
1423@item @code{GLX_GREEN_SIZE}
1424
1425
1426Number of bits of green stored in each color buffer. Undefined if RGBA
1427contexts are not supported by the frame buffer configuration.
1428
1429@item @code{GLX_BLUE_SIZE}
1430
1431
1432Number of bits of blue stored in each color buffer. Undefined if RGBA
1433contexts are not supported by the frame buffer configuration.
1434
1435@item @code{GLX_ALPHA_SIZE}
1436
1437
1438Number of bits of alpha stored in each color buffer. Undefined if RGBA
1439contexts are not supported by the frame buffer configuration.
1440
1441@item @code{GLX_DEPTH_SIZE}
1442
1443
1444Number of bits in the depth buffer.
1445
1446@item @code{GLX_STENCIL_SIZE}
1447
1448
1449Number of bits in the stencil buffer.
1450
1451@item @code{GLX_ACCUM_RED_SIZE}
1452
1453
1454Number of bits of red stored in the accumulation buffer.
1455
1456@item @code{GLX_ACCUM_GREEN_SIZE}
1457
1458
1459Number of bits of green stored in the accumulation buffer.
1460
1461@item @code{GLX_ACCUM_BLUE_SIZE}
1462
1463
1464Number of bits of blue stored in the accumulation buffer.
1465
1466@item @code{GLX_ACCUM_ALPHA_SIZE}
1467
1468
1469Number of bits of alpha stored in the accumulation buffer.
1470
1471@item @code{GLX_RENDER_TYPE}
1472
1473
1474Mask indicating what type of GLX contexts can be made current to the
1475frame buffer configuration. Valid bits are @code{GLX_RGBA_BIT} and
1476@code{GLX_COLOR_INDEX_BIT}.
1477
1478@item @code{GLX_DRAWABLE_TYPE}
1479
1480
1481Mask indicating what drawable types the frame buffer configuration
1482supports. Valid bits are @code{GLX_WINDOW_BIT}, @code{GLX_PIXMAP_BIT},
1483and @code{GLX_PBUFFER_BIT}.
1484
1485@item @code{GLX_X_RENDERABLE}
1486
1487
1488@code{True} if drawables created with the frame buffer configuration can
1489be rendered to by X.
1490
1491@item @code{GLX_VISUAL_ID}
1492
1493
1494XID of the corresponding visual, or zero if there is no associated
1495visual (i.e., if @code{GLX_X_RENDERABLE} is @code{False} or
1496@code{GLX_DRAWABLE_TYPE} does not have the @code{GLX_WINDOW_BIT} bit
1497set).
1498
1499@item @code{GLX_X_VISUAL_TYPE}
1500
1501
1502Visual type of associated visual. The returned value will be one of:
1503@code{GLX_TRUE_COLOR}, @code{GLX_DIRECT_COLOR}, @code{GLX_PSEUDO_COLOR},
1504@code{GLX_STATIC_COLOR}, @code{GLX_GRAY_SCALE}, @code{GLX_STATIC_GRAY},
1505or @code{GLX_NONE}, if there is no associated visual (i.e., if
1506@code{GLX_X_RENDERABLE} is @code{False} or @code{GLX_DRAWABLE_TYPE} does
1507not have the @code{GLX_WINDOW_BIT} bit set).
1508
1509@item @code{GLX_CONFIG_CAVEAT}
1510
1511
1512One of @code{GLX_NONE}, @code{GLX_SLOW_CONFIG}, or
1513@code{GLX_NON_CONFORMANT_CONFIG}, indicating that the frame buffer
1514configuration has no caveats, some aspect of the frame buffer
1515configuration runs slower than other frame buffer configurations, or
1516some aspect of the frame buffer configuration is nonconformant,
1517respectively.
1518
1519@item @code{GLX_TRANSPARENT_TYPE}
1520
1521
1522One of @code{GLX_NONE}, @code{GLX_TRANSPARENT_RGB},
1523@code{GLX_TRANSPARENT_INDEX}, indicating that the frame buffer
1524configuration is opaque, is transparent for particular values of red,
1525green, and blue, or is transparent for particular index values,
1526respectively.
1527
1528@item @code{GLX_TRANSPARENT_INDEX_VALUE}
1529
1530
1531Integer value between 0 and the maximum frame buffer value for indices,
1532indicating the transparent index value for the frame buffer
1533configuration. Undefined if @code{GLX_TRANSPARENT_TYPE} is not
1534@code{GLX_TRANSPARENT_INDEX}.
1535
1536@item @code{GLX_TRANSPARENT_RED_VALUE}
1537
1538
1539Integer value between 0 and the maximum frame buffer value for red,
1540indicating the transparent red value for the frame buffer configuration.
1541Undefined if @code{GLX_TRANSPARENT_TYPE} is not
1542@code{GLX_TRANSPARENT_RGB}.
1543
1544@item @code{GLX_TRANSPARENT_GREEN_VALUE}
1545
1546
1547Integer value between 0 and the maximum frame buffer value for green,
1548indicating the transparent green value for the frame buffer
1549configuration. Undefined if @code{GLX_TRANSPARENT_TYPE} is not
1550@code{GLX_TRANSPARENT_RGB}.
1551
1552@item @code{GLX_TRANSPARENT_BLUE_VALUE}
1553
1554
1555Integer value between 0 and the maximum frame buffer value for blue,
1556indicating the transparent blue value for the frame buffer
1557configuration. Undefined if @code{GLX_TRANSPARENT_TYPE} is not
1558@code{GLX_TRANSPARENT_RGB}.
1559
1560@item @code{GLX_TRANSPARENT_ALPHA_VALUE}
1561
1562
1563Integer value between 0 and the maximum frame buffer value for alpha,
1564indicating the transparent blue value for the frame buffer
1565configuration. Undefined if @code{GLX_TRANSPARENT_TYPE} is not
1566@code{GLX_TRANSPARENT_RGB}.
1567
1568@item @code{GLX_MAX_PBUFFER_WIDTH}
1569
1570
1571The maximum width that can be specified to @code{glXCreatePbuffer}.
1572
1573@item @code{GLX_MAX_PBUFFER_HEIGHT}
1574
1575
1576The maximum height that can be specified to @code{glXCreatePbuffer}.
1577
1578@item @code{GLX_MAX_PBUFFER_PIXELS}
1579
1580
1581The maximum number of pixels (width times height) for a pixel buffer.
1582Note that this value may be less than @code{GLX_MAX_PBUFFER_WIDTH} times
1583@code{GLX_MAX_PBUFFER_HEIGHT}. Also, this value is static and assumes
1584that no other pixel buffers or X resources are contending for the frame
1585buffer memory. As a result, it may not be possible to allocate a pixel
1586buffer of the size given by @code{GLX_MAX_PBUFFER_PIXELS}.
1587
1588@end table
1589
1590Applications should choose the frame buffer configuration that most
1591closely meets their requirements. Creating windows, GLX pixmaps, or GLX
1592pixel buffers with unnecessary buffers can result in reduced rendering
1593performance as well as poor resource allocation.
1594
1595@heading Errors
1596@code{GLX_NO_EXTENSION} is returned if @var{dpy} does not support the
1597GLX extension. @code{GLX_BAD_ATTRIBUTE} is returned if @var{attribute}
1598is not a valid GLX attribute.
1599
1600@end defun
1601
1602@defun glXGetFBConfigs
1603@heading list all GLX frame buffer configurations for a given screen
1604@heading Parameters
1605@table @asis
1606@item @var{dpy}
1607Specifies the connection to the X server.
1608
1609@item @var{screen}
1610Specifies the screen number.
1611
1612@item @var{nelements}
1613Returns the number of GLXFBConfigs returned.
1614
1615@end table
1616
1617@heading Description
1618@code{glXGetFBConfigs} returns a list of all GLXFBConfigs available on
1619the screen specified by @var{screen}. Use @code{glXGetFBConfigAttrib} to
1620obtain attribute values from a specific GLXFBConfig.
1621
1622@end defun
1623
1624@defun glXGetProcAddress
1625@heading obtain a pointer to an OpenGL or GLX function
1626@heading Parameters
1627@table @asis
1628@item @var{procName}
1629Specifies the name of the OpenGL or GLX function whose address is to be
1630returned.
1631
1632@end table
1633
1634@heading Description
1635@code{glXGetProcAddress} returns the address of the function specified
1636in @var{procName}. This is necessary in environments where the OpenGL
1637link library exports a different set of functions than the runtime
1638library.
1639
1640@end defun
1641
1642@defun glXGetSelectedEvent
1643@heading returns GLX events that are selected for a window or a GLX pixel buffer
1644@heading Parameters
1645@table @asis
1646@item @var{dpy}
1647Specifies the connection to the X server.
1648
1649@item @var{draw}
1650Specifies a GLX drawable. Must be a GLX pixel buffer or a window.
1651
1652@item @var{event_mask}
1653Returns the events that are selected for @var{draw}.
1654
1655@end table
1656
1657@heading Description
1658@code{glXGetSelectedEvent} returns in @var{event_mask} the events
1659selected for @var{draw}.
1660
1661@heading Errors
1662@code{GLXBadDrawable} is generated if @var{draw} is not a valid window
1663or a valid GLX pixel buffer.
1664
1665@end defun
1666
1667@defun glXGetVisualFromFBConfig
1668@heading return visual that is associated with the frame buffer configuration
1669@heading Parameters
1670@table @asis
1671@item @var{dpy}
1672Specifies the connection to the X server.
1673
1674@item @var{config}
1675Specifies the GLX frame buffer configuration.
1676
1677@end table
1678
1679@heading Description
1680If @var{config} is a valid GLX frame buffer configuration and it has an
1681associated X Visual, then information describing that visual is
1682returned; otherwise @code{NULL} is returned. Use @code{XFree} to free
1683the data returned.
1684
1685@heading Errors
1686Returns @code{NULL} if @var{config} is not a valid GLXFBConfig.
1687
1688@end defun
1689
1690@defun glXImportContextEXT
1691@heading import another process's indirect rendering context.
1692@heading Parameters
1693@table @asis
1694@item @var{dpy}
1695Specifies the connection to the X server.
1696
1697@item @var{contextID}
1698Specifies a GLX rendering context.
1699
1700@end table
1701
1702@heading Description
1703@code{glXImportContextEXT} creates a GLXContext given the XID of an
1704existing GLXContext. It may be used in place of @code{glXCreateContext},
1705to share another process's indirect rendering context.
1706
1707Only the server-side context information can be shared between X
1708clients; client-side state, such as pixel storage modes, cannot be
1709shared. Thus, @code{glXImportContextEXT} must allocate memory to store
1710client-side information. This memory is freed by calling
1711@code{glXFreeContextEXT}.
1712
1713This call does not create a new XID. It merely makes an existing object
1714available to the importing client (Display *). Like any XID, it goes
1715away when the creating client drops its connection or the ID is
1716explicitly deleted. Note that this is when the XID goes away. The object
1717goes away when the XID goes away AND the context is not current to any
1718thread.
1719
1720If @var{contextID} refers to a direct rendering context then no error is
1721generated but @code{glXImportContextEXT} returns NULL.
1722
1723@code{glXImportContextEXT} is part of the @code{EXT_import_context}
1724extension, not part of the core GLX command set. If
1725_glxextstring(EXT_import_context) is included in the string returned by
1726@code{glXQueryExtensionsString}, when called with argument
1727@code{GLX_EXTENSIONS}, extension @code{EXT_import_context} is supported.
1728
1729@heading Errors
1730@code{GLXBadContext} is generated if @var{contextID} does not refer to a
1731valid context.
1732
1733@end defun
1734
1735@defun glXIntro
1736@heading Introduction to OpenGL in the X window system
1737@end defun
1738
1739@defun glXIsDirect
1740@heading indicate whether direct rendering is enabled
1741@heading Parameters
1742@table @asis
1743@item @var{dpy}
1744Specifies the connection to the X server.
1745
1746@item @var{ctx}
1747Specifies the GLX context that is being queried.
1748
1749@end table
1750
1751@heading Description
1752@code{glXIsDirect} returns @code{True} if @var{ctx} is a direct
1753rendering context, @code{False} otherwise. Direct rendering contexts
1754pass rendering commands directly from the calling process's address
1755space to the rendering system, bypassing the X server. Nondirect
1756rendering contexts pass all rendering commands to the X server.
1757
1758@heading Errors
1759@code{GLXBadContext} is generated if @var{ctx} is not a valid GLX
1760context.
1761
1762@end defun
1763
1764@defun glXMakeContextCurrent
1765@heading attach a GLX context to a GLX drawable
1766@heading Parameters
1767@table @asis
1768@item @var{display}
1769Specifies the connection to the X server.
1770
1771@item @var{draw}
1772Specifies a GLX drawable to render into. Must be an XID representing a
1773GLXWindow, GLXPixmap, or GLXPbuffer.
1774
1775@item @var{read}
1776Specifies a GLX drawable to read from. Must be an XID representing a
1777GLXWindow, GLXPixmap, or GLXPbuffer.
1778
1779@item @var{ctx}
1780Specifies the GLX context to be bound to @var{read} and @var{ctx}.
1781
1782@end table
1783
1784@heading Description
1785@code{glXMakeContextCurrent} binds @var{ctx} to the current rendering
1786thread and to the @var{draw} and @var{read} GLX drawables. @var{draw}
1787and @var{read} may be the same.
1788
1789@var{draw} is used for all OpenGL operations except:
1790
1791Any pixel data that are read based on the value of
1792@code{GLX_READ_BUFFER}. Note that accumulation operations use the value
1793of @code{GLX_READ_BUFFER}, but are not allowed unless @var{draw} is
1794identical to @var{read}.
1795
1796Any depth values that are retrieved by @code{glReadPixels} or
1797@code{glCopyPixels}.
1798
1799Any stencil values that are retrieved by @code{glReadPixels} or
1800@code{glCopyPixels}.
1801
1802Frame buffer values are taken from @var{draw}.
1803
1804If the current rendering thread has a current rendering context, that
1805context is flushed and replaced by @var{ctx}.
1806
1807The first time that @var{ctx} is made current, the viewport and scissor
1808dimensions are set to the size of the @var{draw} drawable. The viewport
1809and scissor are not modified when @var{ctx} is subsequently made
1810current.
1811
1812To release the current context without assigning a new one, call
1813@code{glXMakeContextCurrent} with @var{draw} and @var{read} set to
1814@code{None} and @var{ctx} set to @code{NULL}.
1815
1816@code{glXMakeContextCurrent} returns @code{True} if it is successful,
1817@code{False} otherwise. If @code{False} is returned, the previously
1818current rendering context and drawable (if any) remain unchanged.
1819
1820@heading Errors
1821@code{BadMatch} is generated if @var{draw} and @var{read} are not
1822compatible.
1823
1824@code{BadAccess} is generated if @var{ctx} is current to some other
1825thread.
1826
1827@code{GLXContextState} is generated if there is a current rendering
1828context and its render mode is either @code{GLX_FEEDBACK} or
1829@code{GLX_SELECT}.
1830
1831@code{GLXBadContext} is generated if @var{ctx} is not a valid GLX
1832rendering context.
1833
1834@code{GLXBadDrawable} is generated if @var{draw} or @var{read} is not a
1835valid GLX drawable.
1836
1837@code{GLXBadWindow} is generated if the underlying X window for either
1838@var{draw} or @var{read} is no longer valid.
1839
1840@code{GLXBadCurrentDrawable} is generated if the previous context of the
1841calling thread has unflushed commands and the previous drawable is no
1842longer valid.
1843
1844@code{BadAlloc} is generated if the X server does not have enough
1845resources to allocate the buffers.
1846
1847@code{BadMatch} is generated if:
1848
1849@var{draw} and @var{read} cannot fit into frame buffer memory
1850simultaneously.
1851
1852@var{draw} or @var{read} is a GLXPixmap and @var{ctx} is a
1853direct-rendering context.
1854
1855@var{draw} or @var{read} is a GLXPixmap and @var{ctx} was previously
1856bound to a GLXWindow or GLXPbuffer.
1857
1858@var{draw} or @var{read} is a GLXWindow or GLXPbuffer and @var{ctx} was
1859previously bound to a GLXPixmap.
1860
1861@end defun
1862
1863@defun glXMakeCurrent
1864@heading attach a GLX context to a window or a GLX pixmap
1865@heading Parameters
1866@table @asis
1867@item @var{dpy}
1868Specifies the connection to the X server.
1869
1870@item @var{drawable}
1871Specifies a GLX drawable. Must be either an X window ID or a GLX pixmap
1872ID.
1873
1874@item @var{ctx}
1875Specifies a GLX rendering context that is to be attached to
1876@var{drawable}.
1877
1878@end table
1879
1880@heading Description
1881@code{glXMakeCurrent} does two things: It makes @var{ctx} the current
1882GLX rendering context of the calling thread, replacing the previously
1883current context if there was one, and it attaches @var{ctx} to a GLX
1884drawable, either a window or a GLX pixmap. As a result of these two
1885actions, subsequent GL rendering calls use rendering context @var{ctx}
1886to modify GLX drawable @var{drawable} (for reading and writing). Because
1887@code{glXMakeCurrent} always replaces the current rendering context with
1888@var{ctx}, there can be only one current context per thread.
1889
1890Pending commands to the previous context, if any, are flushed before it
1891is released.
1892
1893The first time @var{ctx} is made current to any thread, its viewport is
1894set to the full size of @var{drawable}. Subsequent calls by any thread
1895to @code{glXMakeCurrent} with @var{ctx} have no effect on its viewport.
1896
1897To release the current context without assigning a new one, call
1898@code{glXMakeCurrent} with @var{drawable} set to @code{None} and
1899@var{ctx} set to @code{NULL}.
1900
1901@code{glXMakeCurrent} returns @code{True} if it is successful,
1902@code{False} otherwise. If @code{False} is returned, the previously
1903current rendering context and drawable (if any) remain unchanged.
1904
1905@heading Errors
1906@code{BadMatch} is generated if @var{drawable} was not created with the
1907same X screen and visual as @var{ctx}. It is also generated if
1908@var{drawable} is @code{None} and @var{ctx} is not @code{NULL}.
1909
1910@code{BadAccess} is generated if @var{ctx} was current to another thread
1911at the time @code{glXMakeCurrent} was called.
1912
1913@code{GLXBadDrawable} is generated if @var{drawable} is not a valid GLX
1914drawable.
1915
1916@code{GLXBadContext} is generated if @var{ctx} is not a valid GLX
1917context.
1918
1919@code{GLXBadContextState} is generated if @code{glXMakeCurrent} is
1920executed between the execution of @code{glBegin} and the corresponding
1921execution of @code{glEnd}.
1922
1923@code{GLXBadContextState} is also generated if the rendering context
1924current to the calling thread has GL renderer state @code{GLX_FEEDBACK}
1925or @code{GLX_SELECT}.
1926
1927@code{GLXBadCurrentWindow} is generated if there are pending GL commands
1928for the previous context and the current drawable is a window that is no
1929longer valid.
1930
1931@code{BadAlloc} may be generated if the server has delayed allocation of
1932ancillary buffers until @code{glXMakeCurrent} is called, only to find
1933that it has insufficient resources to complete the allocation.
1934
1935@end defun
1936
1937@defun glXQueryContextInfoEXT
1938@heading query context information
1939@heading Parameters
1940@table @asis
1941@item @var{dpy}
1942Specifies the connection to the X server.
1943
1944@item @var{ctx}
1945Specifies a GLX rendering context.
1946
1947@item @var{attribute}
1948Specifies that a context parameter should be retrieved. Must be one of
1949@code{GLX_SHARED_CONTEXT_EXT}, @code{GLX_VISUAL_ID_EXT}, or
1950@code{GLX_SCREEN_EXT}.
1951
1952@item @var{value}
1953Contains the return value for @var{attribute}.
1954
1955@end table
1956
1957@heading Description
1958@code{glXQueryContextInfoEXT} sets @var{value} to the value of
1959@var{attribute} with respect to @var{ctx}. @code{glXQueryContextInfoEXT}
1960returns an error code if it fails for any reason. Otherwise,
1961@code{Success} is returned.
1962
1963@var{attribute} may be one of the following:
1964
1965@table @asis
1966@item @code{GLX_SHARED_CONTEXT_EXT}
1967Returns the XID of the share list context associated with @var{ctx} at
1968its creation.
1969
1970@item @code{GLX_VISUAL_ID_EXT}
1971Returns the XID of the GLX Visual associated with @var{ctx}.
1972
1973@item @code{GLX_SCREEN_EXT}
1974Returns the screen number associated with @var{ctx}.
1975
1976@end table
1977
1978This call may cause a round-trip to the server.
1979
1980@code{glXQueryContextInfoEXT} is part of the @code{EXT_import_context}
1981extension, not part of the core GLX command set. If
1982_glxextstring(EXT_import_context) is included in the string returned by
1983@code{glXQueryExtensionsString}, when called with argument
1984@code{GLX_EXTENSIONS}, extension @code{EXT_import_context} is supported.
1985
1986@heading Errors
1987@code{GLXBadContext} is generated if @var{ctx} does not refer to a valid
1988context.
1989
1990@code{GLX_BAD_ATTRIBUTE} is returned if @var{attribute} is not a valid
1991GLX context attribute.
1992
1993fred @code{GLX_BAD_CONTEXT} is returned if @var{attribute} is not a
1994valid context.
1995
1996@end defun
1997
1998@defun glXQueryContext
1999@heading query context information
2000@heading Parameters
2001@table @asis
2002@item @var{dpy}
2003Specifies the connection to the X server.
2004
2005@item @var{ctx}
2006Specifies a GLX rendering context.
2007
2008@item @var{attribute}
2009Specifies that a context parameter should be retrieved. Must be one of
2010@code{GLX_FBCONFIG_ID}, @code{GLX_RENDER_TYPE}, or @code{GLX_SCREEN}.
2011
2012@item @var{value}
2013Contains the return value for @var{attribute}.
2014
2015@end table
2016
2017@heading Description
2018@code{glXQueryContext} sets @var{value} to the value of @var{attribute}
2019with respect to @var{ctx}. @var{attribute} may be one of the following:
2020
2021@table @asis
2022@item @code{GLX_FBCONFIG_ID}
2023Returns the XID of the GLXFBConfig associated with @var{ctx}.
2024
2025@item @code{GLX_RENDER_TYPE}
2026Returns the rendering type supported by @var{ctx}.
2027
2028@item @code{GLX_SCREEN}
2029Returns the screen number associated with @var{ctx}.
2030
2031@end table
2032
2033@code{Success} is returned unless @var{attribute} is not a valid GLX
2034context attribute, in which case @code{GLX_BAD_ATTRIBUTE} is returned.
2035
2036This call may cause a round-trip to the server.
2037
2038@heading Errors
2039@code{GLXBadContext} is generated if @var{ctx} does not refer to a valid
2040context.
2041
2042@end defun
2043
2044@defun glXQueryDrawable
2045@heading returns an attribute assoicated with a GLX drawable
2046@heading Parameters
2047@table @asis
2048@item @var{dpy}
2049Specifies the connection to the X server.
2050
2051@item @var{draw}
2052Specifies the GLX drawable to be queried.
2053
2054@item @var{attribute}
2055Specifies the attribute to be returned. Must be one of @code{GLX_WIDTH},
2056@code{GLX_HEIGHT}, @code{GLX_PRESERVED_CONTENTS},
2057@code{GLX_LARGEST_PBUFFER}, or @code{GLX_FBCONFIG_ID}.
2058
2059@item @var{value}
2060Contains the return value for @var{attribute}.
2061
2062@end table
2063
2064@heading Description
2065@code{glXQueryDrawable} sets @var{value} to the value of @var{attribute}
2066with respect to the GLXDrawable @var{draw}.
2067
2068@var{attribute} may be one of the following:
2069
2070@table @asis
2071@item @code{GLX_WIDTH}
2072Returns the width of @var{ctx}.
2073
2074@item @code{GLX_HEIGHT}
2075Returns the height of @var{ctx}.
2076
2077@item @code{GLX_PRESERVED_CONTENTS}
2078Returns @code{True} if the contents of a GLXPbuffer are preserved when a
2079resource conflict occurs; @code{False} otherwise.
2080
2081@item @code{GLX_LARGEST_PBUFFER}
2082Returns the value set when @code{glXCreatePbuffer} was called to create
2083the GLXPbuffer. If @code{False} is returned, then the call to
2084@code{glXCreatePbuffer} will fail to create a GLXPbuffer if the
2085requested size is larger than the implementation maximum or available
2086resources. If @code{True} is returned, a GLXPbuffer of the maximum
2087availble size (if less than the requested width and height) is created.
2088
2089@item @code{GLX_FBCONFIG_ID}
2090Returns the XID for @var{draw}.
2091
2092@end table
2093
2094If @var{draw} is a GLXWindow or GLXPixmap and @var{attribute} is set to
2095@code{GLX_PRESERVED_CONTENTS} or @code{GLX_LARGETST_PBUFFER}, the
2096contents of @var{value} are undefined. If @var{attribute} is not one of
2097the attributes listed above, the contents of @var{value} are unedfined.
2098
2099@heading Errors
2100A @code{GLXBadDrawable} is generated if @var{draw} is not a valid
2101GLXDrawable.
2102
2103@end defun
2104
2105@defun glXQueryExtensionsString
2106@heading return list of supported extensions
2107@heading Parameters
2108@table @asis
2109@item @var{dpy}
2110Specifies the connection to the X server.
2111
2112@item @var{screen}
2113Specifies the screen number.
2114
2115@end table
2116
2117@heading Description
2118@code{glXQueryExtensionsString} returns a pointer to a string describing
2119which GLX extensions are supported on the connection. The string is
2120null-terminated and contains a space-separated list of extension names.
2121(The extension names themselves never contain spaces.) If there are no
2122extensions to GLX, then the empty string is returned.
2123
2124@end defun
2125
2126@defun glXQueryExtension
2127@heading indicate whether the GLX extension is supported
2128@heading Parameters
2129@table @asis
2130@item @var{dpy}
2131Specifies the connection to the X server.
2132
2133@item @var{errorBase}
2134Returns the base error code of the GLX server extension.
2135
2136@item @var{eventBase}
2137Returns the base event code of the GLX server extension.
2138
2139@end table
2140
2141@heading Description
2142@code{glXQueryExtension} returns @code{True} if the X server of
2143connection @var{dpy} supports the GLX extension, @code{False} otherwise.
2144If @code{True} is returned, then @var{errorBase} and @var{eventBase}
2145return the error base and event base of the GLX extension. These values
2146should be added to the constant error and event values to determine the
2147actual event or error values. Otherwise, @var{errorBase} and
2148@var{eventBase} are unchanged.
2149
2150@var{errorBase} and @var{eventBase} do not return values if they are
2151specified as @code{NULL}.
2152
2153@end defun
2154
2155@defun glXQueryServerString
2156@heading return string describing the server
2157@heading Parameters
2158@table @asis
2159@item @var{dpy}
2160Specifies the connection to the X server.
2161
2162@item @var{screen}
2163Specifies the screen number.
2164
2165@item @var{name}
2166Specifies which string is returned: one of @code{GLX_VENDOR},
2167@code{GLX_VERSION}, or @code{GLX_EXTENSIONS}.
2168
2169@end table
2170
2171@heading Description
2172@code{glXQueryServerString} returns a pointer to a static,
2173null-terminated string describing some aspect of the server's GLX
2174extension. The possible values for @var{name} and the format of the
2175strings is the same as for @code{glXGetClientString}. If @var{name} is
2176not set to a recognized value, @code{NULL} is returned.
2177
2178@end defun
2179
2180@defun glXQueryVersion
2181@heading return the version numbers of the GLX extension
2182@heading Parameters
2183@table @asis
2184@item @var{dpy}
2185Specifies the connection to the X server.
2186
2187@item @var{major}
2188Returns the major version number of the GLX server extension.
2189
2190@item @var{minor}
2191Returns the minor version number of the GLX server extension.
2192
2193@end table
2194
2195@heading Description
2196@code{glXQueryVersion} returns the major and minor version numbers of
2197the GLX extension implemented by the server associated with connection
2198@var{dpy}. Implementations with the same major version number are upward
2199compatible, meaning that the implementation with the higher minor number
2200is a superset of the version with the lower minor number.
2201
2202@var{major} and @var{minor} do not return values if they are specified
2203as @code{NULL}.
2204
2205@heading Errors
2206@code{glXQueryVersion} returns @code{False} if it fails, @code{True}
2207otherwise.
2208
2209@var{major} and @var{minor} are not updated when @code{False} is
2210returned.
2211
2212@end defun
2213
2214@defun glXSelectEvent
2215@heading select GLX events for a window or a GLX pixel buffer
2216@heading Parameters
2217@table @asis
2218@item @var{dpy}
2219Specifies the connection to the X server.
2220
2221@item @var{draw}
2222Specifies a GLX drawable. Must be a GLX pixel buffer or a window.
2223
2224@item @var{event_mask}
2225Specifies the events to be returned for @var{draw}.
2226
2227@end table
2228
2229@heading Description
2230@code{glXSelectEvent} sets the GLX event mask for a GLX pixel buffer or
2231a window. Calling @code{glXSelectEvent} overrides any previous event
2232mask that was set by the client for @var{draw}. Note that it does not
2233affect the event masks that other clients may have specified for
2234@var{draw} since each client rendering to @var{draw} has a separate
2235event mask for it.
2236
2237Currently, only one GLX event, @code{GLX_PBUFFER_CLOBBER_MASK}, can be
2238selected. The following data is returned to the client when a
2239@code{GLX_PBUFFER_CLOBBER_MASK} event occurs:
2240
2241typedef struct @{
2242
2243@table @asis
2244@item
2245int @var{event_type};
2246/* GLX_DAMAGED or GLX_SAVED */
2247
2248@item
2249int @var{draw_type};
2250/* GLX_WINDOW or GLX_PBUFFER */
2251
2252@item
2253unsigned long @var{serial};
2254/* # of last request processed by server */
2255
2256@item
2257Bool @var{send_event};
2258/* true if this came for SendEvent request */
2259
2260@item
2261Display @var{*display};
2262/* display the event was read from */
2263
2264@item
2265GLXDrawable @var{drawable};
2266/* i.d. of Drawable */
2267
2268@item
2269unsigned int @var{buffer_mask};
2270/* mask indicating affected buffers */
2271
2272@item
2273int @var{x, y};
2274
2275
2276@item
2277int @var{width, height};
2278
2279
2280@item
2281int @var{count};
2282/* if nonzero, at least this many more */
2283
2284@end table
2285
2286@} GLXPbufferClobberEvent; The valid bit masks used in @var{buffer_mask}
2287are:
2288
2289
2290
2291@table @asis
2292@item @strong{Bitmask}
2293@strong{Corresponding Buffer}
2294
2295@item @code{GLX_FRONT_LEFT_BUFFER_BIT}
2296Front left color buffer
2297
2298@item @code{GLX_FRONT_RIGHT_BUFFER_BIT}
2299Front right color buffer
2300
2301@item @code{GLX_BACK_LEFT_BUFFER_BIT}
2302Back left color buffer
2303
2304@item @code{GLX_BACK_RIGHT_BUFFER_BIT}
2305Back right color buffer
2306
2307@item @code{GLX_AUX_BUFFERS_BIT}
2308Auxiliary buffer
2309
2310@item @code{GLX_DEPTH_BUFFER_BIT}
2311Depth buffer
2312
2313@item @code{GLX_STENCIL_BUFFER_BIT}
2314Stencil buffer
2315
2316@item @code{GLX_ACCUM_BUFFER_BIT}
2317Accumulation buffer
2318
2319@end table
2320
2321A single X server operation can cause several buffer clobber events to
2322be sent. (e.g., a single GLX pixel buffer may be damaged and cause
2323multiple buffer clobber events to be generated). Each event specifies
2324one region of the GLX drawable that was affected by the X Server
2325operation. The @var{buffer_mask} field indicates which color buffers and
2326ancillary buffers were affected. All the buffer clobber events generated
2327by a single X server action are guaranteed to be contiguous in the event
2328queue. The conditions under which this event is generated and the
2329@var{event_type} varies, depending on the type of the GLX drawable.
2330
2331When the @code{GLX_AUX_BUFFERS_BIT} is set in @var{buffer_mask}, then
2332@var{aux_buffer} is set to indicate which buffer was affected. If more
2333than one aux buffer was affected, then additional events are generated
2334as part of the same contiguous event group. Each additional event will
2335have only the @code{GLX_AUX_BUFFERS_BIT} set in @var{buffer_mask}, and
2336the @var{aux_buffer} field will be set appropriately. For nonstereo
2337drawables, @code{GLX_FRONT_LEFT_BUFFER_BIT} and
2338@code{GLX_BACK_LEFT_BUFFER_BIT} are used to specify the front and back
2339color buffers.
2340
2341For preserved GLX pixel buffers, a buffer clobber event with type
2342@code{GLX_SAVED} is generated whenever the contents of the GLX pixel
2343buffer is moved out of offscreen memory. The event(s) describes which
2344portions of the GLX pixel buffer were affected. Clients who receive many
2345buffer clobber events, referring to different save actions, should
2346consider freeing the GLX pixel buffer resource in order to prevent the
2347system from thrashing due to insufficient resources.
2348
2349For an unpreserved GLXPbuffer, a buffer clobber event, with type
2350@code{GLX_DAMAGED}, is generated whenever a portion of the GLX pixel
2351buffer becomes invalid. The client may wish to regenerate the invalid
2352portions of the GLX pixel buffer.
2353
2354For Windows, buffer clobber events, with type @code{GLX_SAVED}, occur
2355whenever an ancillary buffer, associated with the window, gets clobbered
2356or moved out of off-screen memory. The event contains information
2357indicating which color buffers and ancillary buffers\(emand which
2358portions of those buffers\(emwere affected.
2359
2360@heading Errors
2361@code{GLXBadDrawable} is generated if @var{draw} is not a valid window
2362or a valid GLX pixel buffer.
2363
2364@end defun
2365
2366@defun glXSwapBuffers
2367@heading exchange front and back buffers
2368@heading Parameters
2369@table @asis
2370@item @var{dpy}
2371Specifies the connection to the X server.
2372
2373@item @var{drawable}
2374Specifies the drawable whose buffers are to be swapped.
2375
2376@end table
2377
2378@heading Description
2379@code{glXSwapBuffers} promotes the contents of the back buffer of
2380@var{drawable} to become the contents of the front buffer of
2381@var{drawable}. The contents of the back buffer then become undefined.
2382The update typically takes place during the vertical retrace of the
2383monitor, rather than immediately after @code{glXSwapBuffers} is called.
2384
2385@code{glXSwapBuffers} performs an implicit @code{glFlush} before it
2386returns. Subsequent OpenGL commands may be issued immediately after
2387calling @code{glXSwapBuffers}, but are not executed until the buffer
2388exchange is completed.
2389
2390If @var{drawable} was not created with respect to a double-buffered
2391visual, @code{glXSwapBuffers} has no effect, and no error is generated.
2392
2393@heading Errors
2394@code{GLXBadDrawable} is generated if @var{drawable} is not a valid GLX
2395drawable.
2396
2397@code{GLXBadCurrentWindow} is generated if @var{dpy} and @var{drawable}
2398are respectively the display and drawable associated with the current
2399context of the calling thread, and @var{drawable} identifies a window
2400that is no longer valid.
2401
2402@end defun
2403
2404@defun glXUseXFont
2405@heading create bitmap display lists from an X font
2406@heading Parameters
2407@table @asis
2408@item @var{font}
2409Specifies the font from which character glyphs are to be taken.
2410
2411@item @var{first}
2412Specifies the index of the first glyph to be taken.
2413
2414@item @var{count}
2415Specifies the number of glyphs to be taken.
2416
2417@item @var{listBase}
2418Specifies the index of the first display list to be generated.
2419
2420@end table
2421
2422@heading Description
2423@code{glXUseXFont} generates @var{count} display lists, named
2424@var{listBase} through @math{@var{listBase}+@var{count}-1}, each
2425containing a single @code{glBitmap} command. The parameters of the
2426@code{glBitmap} command of display list @math{@var{listBase}+@var{i}}
2427are derived from glyph @math{@var{first}+@var{i}}. Bitmap parameters
2428@math{@var{xorig}}, @math{@var{yorig}}, @math{@var{width}}, and
2429@math{@var{height}} are computed from font metrics as
2430@math{@var{descent}-1}, @math{-@var{lbearing}},
2431@math{@var{rbearing}-@var{lbearing}}, and
2432@math{@var{ascent}+@var{descent}}, respectively. @math{@var{xmove}} is
2433taken from the glyph's @math{@var{width}} metric, and @math{@var{ymove}}
2434is set to zero. Finally, the glyph's image is converted to the
2435appropriate format for @code{glBitmap}.
2436
2437Using @code{glXUseXFont} may be more efficient than accessing the X font
2438and generating the display lists explicitly, both because the display
2439lists are created on the server without requiring a round trip of the
2440glyph data, and because the server may choose to delay the creation of
2441each bitmap until it is accessed.
2442
2443Empty display lists are created for all glyphs that are requested and
2444are not defined in @var{font}. @code{glXUseXFont} is ignored if there is
2445no current GLX context.
2446
2447@heading Errors
2448@code{BadFont} is generated if @var{font} is not a valid font.
2449
2450@code{GLXBadContextState} is generated if the current GLX context is in
2451display-list construction mode.
2452
2453@code{GLXBadCurrentWindow} is generated if the drawable associated with
2454the current context of the calling thread is a window, and that window
2455is no longer valid.
2456
2457@end defun
2458
2459@defun glXWaitGL
2460@heading complete GL execution prior to subsequent X calls
2461@heading Description
2462GL rendering calls made prior to @code{glXWaitGL} are guaranteed to be
2463executed before X rendering calls made after @code{glXWaitGL}. Although
2464this same result can be achieved using @code{glFinish}, @code{glXWaitGL}
2465does not require a round trip to the server, and it is therefore more
2466efficient in cases where client and server are on separate machines.
2467
2468@code{glXWaitGL} is ignored if there is no current GLX context.
2469
2470@heading Errors
2471@code{GLXBadCurrentWindow} is generated if the drawable associated with
2472the current context of the calling thread is a window, and that window
2473is no longer valid.
2474
2475@end defun
2476
2477@defun glXWaitX
2478@heading complete X execution prior to subsequent GL calls
2479@heading Description
2480X rendering calls made prior to @code{glXWaitX} are guaranteed to be
2481executed before GL rendering calls made after @code{glXWaitX}. Although
2482the same result can be achieved using @code{XSync}, @code{glXWaitX} does
2483not require a round trip to the server, and it is therefore more
2484efficient in cases where client and server are on separate machines.
2485
2486@code{glXWaitX} is ignored if there is no current GLX context.
2487
2488@heading Errors
2489@code{GLXBadCurrentWindow} is generated if the drawable associated with
2490the current context of the calling thread is a window, and that window
2491is no longer valid.
2492
2493@end defun
2494
2495
2496@c %end of fragment