From 22c0d71c97aa30455cc5c3d1073b2f0a5baa538f Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Tue, 12 Feb 2013 12:05:24 +0100 Subject: [PATCH] add high-level GL docs * Makefile.am: * doc/figl.texi: * doc/gl.texi: Factor GL docs into a separate file. Add documentation for the high-level interface. --- Makefile.am | 1 + doc/figl.texi | 591 ++++++++++++------------------------- doc/{figl.texi => gl.texi} | 522 ++++++++++++++++++++------------ 3 files changed, 523 insertions(+), 591 deletions(-) rewrite doc/figl.texi (64%) copy doc/{figl.texi => gl.texi} (50%) diff --git a/Makefile.am b/Makefile.am index 8c3269a..e865ec1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -43,6 +43,7 @@ EXTRA_DIST += env.in COPYING COPYING.LESSER examples upstream-doc info_TEXINFOS = doc/figl.texi figl_TEXINFOS = \ + doc/gl.texi \ doc/low-level-gl.texi \ doc/low-level-glu.texi \ doc/low-level-glx.texi \ diff --git a/doc/figl.texi b/doc/figl.texi dissimilarity index 64% index 1792ab4..8a367f3 100644 --- a/doc/figl.texi +++ b/doc/figl.texi @@ -1,403 +1,188 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename figl.info -@settitle Figl -@c %**end of header - -@set VERSION 2.0.0 -@set UPDATED 1 February 2013 - -@copying -This manual is for Figl (version @value{VERSION}, updated -@value{UPDATED}) - -Copyright 2013 Andy Wingo and others. - -@quotation -Figl is free software: you can redistribute and/or modify it and its -documentation under the terms of the GNU Lesser General Public License -as published by the Free Software Foundation, either version 3 of the -License, or (at your option) any later version. - -Figl is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General -Public License for more details. - -You should have received a copy of the GNU Lesser General Public -License along with this program. If not, see -@uref{http://www.gnu.org/licenses/}. -@end quotation - -Portions of this document were generated from the upstream OpenGL -documentation. The work as a whole is redistributable under the -license above. Sections containing generated documentation are -prefixed with a specific copyright header. -@end copying - -@dircategory The Algorithmic Language Scheme -@direntry -* Figl: (figl.info). An OpenGL interface for Guile. -@end direntry - -@titlepage -@title Figl -@subtitle version @value{VERSION}, updated @value{UPDATED} -@author Andy Wingo -@author (many others) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top Figl - -@insertcopying - -@menu -* Introduction:: The what, why, and how of Figl. - -* GL:: A Scheme interface to OpenGL. -* GLU:: The GL Utility library. -* GLX:: Using OpenGL with the X Window System. -* GLUT:: The GL Utility Toolkit. - -* FAQ:: Figl answers questions. - -* Function Index:: -@end menu - -@end ifnottex - -@iftex -@shortcontents -@end iftex - - -@node Introduction -@chapter Introduction - -Figl is the Foreign Interface to GL: an OpenGL binding for Guile. - -OpenGL is a family of APIs and layers. The following chapters discuss -the parts of OpenGL and how they are bound by Figl. - -But before that, some notes on the Figl binding as a whole. - -@menu -* About Figl:: The structure of the binding. -@end menu - - -@node About Figl -@section About Figl - -Figl is a @dfn{foreign} interface to OpenGL because it uses the -dynamic @dfn{foreign function interface} provided by Guile 2.0, -providing access to OpenGL without any C code at all. In fact, much -of Figl (and this manual) is automatically generated from upstream API -specifications and documentation. - -We have tried to do a very complete job at wrapping OpenGL, and -additionally have tried to provide a nice Scheme interface as well. -Our strategy has been to separate the binding into low-level and -high-level pieces. - -The low-level bindings correspond exactly with the GL specification, -and are well-documented. However, these interfaces are not so nice to -use from Scheme; output arguments have to be allocated by the caller, -and there is only the most basic level of type checking, and no sanity -checking at all. For example, you can pass a bytevector of image data -to the low-level @code{glTexImage2D} procedure, but no check is made -that the dimensions you specify actually correspond to the size of the -bytevector. This function could end up reading past the end of the -bytevector. Worse things can happen with procedures that write to -arrays, like @code{glGetTexImage}. - -The high-level bindings are currently a work in progress, and are -being manually written. They intend to be a complete interface to the -GL, without the need to use the low-level bindings. However, the -low-level bindings will always be available for you to use if needed, -and have the advantage that their behavior is better documented and -specified by OpenGL itself. - -Low-level bindings are accessed by loading the @code{(figl -@var{module} low-level)}, for example via: - -@example -(use-modules (figl gl low-level)) -@end example - -The high-level modules are named like @code{(figl @var{module})}, for -example @code{(figl gl)}. - - -@node GL -@chapter GL - - -@menu -* About OpenGL:: Know the past to understand the present. -* GL Contexts:: Finding a square of pixels. -* Rendering:: How to paint. -* Low-Level GL:: Primitive interface to OpenGL. -* GL Enumerations:: Enumerated values. -* GL Extensions:: Beyond core OpenGL. -@end menu - - -@node About OpenGL -@section About OpenGL - -OpenGL is a standard API for drawing three-dimensional graphics. From -its origin in Silicon Graphics's workstations the early 1990s, today -it has become ubiquitous, with implementations on mobile phones, -televisions, tablets, desktops, and even web browsers. - -OpenGL has been able to achieve such widespread adoption not just -because it co-evolved with powerful graphics hardware, but also -because it was conceived of as an interface specification and not a -piece of source code. In fact, these days it is a family of APIs, -available in several flavors and versions: - -@table @asis -@item OpenGL 1.x -This series of specifications started with the original releases in -1992, and ended with OpenGL 1.5 in 2003. This era corresponds to a -time when graphics cards were less powerful and more special-purpose, -with dedicated hardware to handle such details as fog and lighting. -As such the OpenGL 1.x API reflects the capabilities of these special -units. - -@item OpenGL 2.x -By the early 2000s, graphics hardware had become much more -general-purpose and needed a more general-purpose API. The so-called -@dfn{fixed-function rendering pipeline} of the earlier years was -replaced with a @dfn{programmable rendering pipeline}, in which -effects that would have required special hardware were instead -performed by custom programs running on the graphics card. OpenGL -added support for allocating @dfn{buffer objects} on the graphics -card, and for @dfn{shader programs}, which did the actual rendering. -In time, this buffer-focused API came to be the preferred form of -talking to the GL. - -@item OpenGL ES -OpenGL ES was a ``cut-down'' version of OpenGL 2.x, designed to be -small enough to appeal to embedded device vendors. OpenGL ES 1.x -removed some of the legacy functionality from OpenGL, while adding -interfaces to use fixed-point math, for devices without floating-point -units. OpenGL ES 2.x went farther still, removing the fixed-function -pipeline entirely. OpenGL ES 2.x is common on current smart phone -platforms. - -@item OpenGL 3.x and above -The OpenGL 3.x series followed the lead of OpenGL ES, first -deprecating (in 3.0) and then removing (in 3.1) the fixed-function -pipeline. OpenGL 3.0 was released in 2008, but the free Mesa -impementation only began supporting it in 2012, so it is currently -(@value{UPDATED}) less common. -@end table - -Figl wraps the OpenGL 2.1 API. It's a ubiquitous subset of the OpenGL -implementations that are actually deployed in the wild; its legacy API -looks back to OpenGL 1.x, while the buffer-oriented API is compatible -with OpenGL ES. - - -@node GL Contexts -@section GL Contexts - -All this talk about drawing is very well and good, but how do you -actually get a canvas? Interestingly enough, this is outside the -purview of the OpenGL specification. There are specific ways to get -an @dfn{OpenGL context} for each different windowing system that is -out there. OpenGL is all crayons and no paper. - -For the X window system, there is a standard API for creating a GL -context given a window (or a drawable), @dfn{GLX}. @xref{GLX}, for -more information on its binding in Guile. - -Bseides creating contexts from native windows or drawables, each -backend also supports functions to make a context @dfn{current}. The -OpenGL API is stateful; you can think of each call as taking an -implicit @dfn{current context} parameter, which holds the current -state of the GL and is operated on by the function in question. -Contexts are thread-specific, and one context should not be active on -more than one thread at a time. - -All calls to OpenGL functions must be made while a context is active; -otherwise the result is undefined. Hopefully while you are getting -used to this rule, your driver is nice enough not to crash on you if -you call a function outside a GL context, but it's not even required -to do that. Backend-specific functions may or may not require a -context to be current; for example, Windows requires a context to be -current, wheras GLX does not. - -There have been a few attempts at abstracting away the need for -calling API specific to a given windowing system, notably GLUT and -EGL. GLUT is the older of the two, and though it is practically -unchanged since the mid-1990s, it is still widely used on desktops. -@xref{GLUT}, for more on GLUT. - -EGL is technically part of OpenGL ES, and was designed with the modern -OpenGL API and mobile hardware in mind, though it also works on the -desktop. Figl does not yet have an EGL binding. - - -@node Rendering -@section Rendering - -To draw with OpenGL, you obtain a drawing context (@pxref{GL -Contexts}) and send @dfn{the GL} some geometry. (You can think of the -GL as a layer over your graphics card.) You can give the GL points, -lines, and triangles in three-dimensional space. You configure your -GL to render a certain part of space, and it takes your geometry, -rasterizes it, and writes it to the screen (when you tell it to). - -That's the basic idea. You can customize most parts of this -@dfn{rendering pipeline}, by specifying attributes of your geometry -with the OpenGL API, and by programmatically operating on the geometry -and the pixels with programs called @dfn{shaders}. - -GL is an @dfn{immediate-mode} graphics API, which is to say that it -doesn't keep around a scene graph of objects. Instead, at every frame -you as the OpenGL user have to tell the GL what is in the world, and -how to paint it. It's a fairly low-level interface, but a powerful -one. See -@uref{http://www.opengl.org/wiki/Rendering_Pipeline_Overview}, for -more details. - -In the old days of OpenGL 1.0, it was common to call a function to -paint each individual vertex. You'll still see this style in some old -tutorials. This quickly gets expensive if you have a lot of vertexes, -though. This style, known as @dfn{Legacy OpenGL}, was deprecated and -even removed from some versions of OpenGL. See -@uref{http://www.opengl.org/wiki/Legacy_OpenGL}, for more on the older -APIs. - -Instead, the newer thing to do is to send the geometry to the GL in a -big array buffer, and have the GL draw geometry from the buffer. The -newer functions like @code{glGenBuffers} allocate buffers, returning -an integer that @dfn{names} a buffer managed by the GL. You as a user -can update the contents of the buffer, but when drawing you reference -the buffer by name. This has the advantage of reducing the chatter -and data transfer between you and the GL, though it can be less -convenient to use. - -So which API should you use? Use what you feel like using, if you -have a choice. Legacy OpenGL isn't going away any time soon on the -desktop. Sometimes you don't have a choice, though; for example, when -targeting a device that only supports OpenGL ES 2.x, legacy OpenGL is -unavailable. - -But if you want some advice, we suggest that you use the newer APIs. -Not only will your code be future-proof and more efficient on the GL -level, reducing the number of API calls improves performance, and it -can reduce the amount of heap allocation in your program. All -floating-point numbers are currently allocated on the heap in Guile, -and doing less floating-point math in tight loops can only be a good -thing. - - -@node Low-Level GL -@section Low-Level GL -@include low-level-gl.texi - - -@node GL Enumerations -@section GL Enumerations -@include low-level-gl-enums.texi - - -@node GL Extensions -@section GL Extensions - -@quotation -The future is already here -- it's just not very evenly distributed. - --- William Gibson -@end quotation - -Before interfaces end up in core OpenGL, the are usually present as -vendor-specific or candidate extensions. Indeed, the making of an -OpenGL standard these days seems to be a matter of simply collecting a -set of mature extensions and making them coherent. - -Figl doesn't currently provide specific interfaces for extensions. -Perhaps it should, but that's a lot of work that we haven't had time -to do. Contributions are welcome. - -In the meantime, if you know enough about GL to know that you need an -extension, you can define one yourself -- after all, Figl is all a -bunch of Scheme code anyway. - -For example, let's say you decide that you need to render to a -framebuffer object. You go to @uref{http://www.opengl.org/registry/} -and pick out an extension, say -@uref{http://www.opengl.org/registry/specs/ARB/framebuffer_object.txt}. - -This extension defines a procedure, @code{GLboolean -glIsRenderBuffer(GLuint)}. So you define it: - -@example -(use-modules (figl gl runtime) (figl gl types)) -(define-gl-procedure (glIsRenderBuffer (buf GLuint) -> GLboolean) - "Render buffer predicate. Other docs here.") -@end example - -And that's that. It's a low-level binding, but what did you expect? - -Note that you'll still need to check for the availability of this -extension at runtime with @code{(glGetString GL_EXTENSIONS)}. - - -@node GLU -@chapter GLU - -@menu -* Low-Level GLU:: Primitive interface to ``glu'' functionality. -@end menu - -@node Low-Level GLU -@section Low-Level GLU -@include low-level-glu.texi - - -@node GLX -@chapter GLX - -@menu -* Low-Level GLX:: Primitive interface to ``glX'' functionality. -* GLX Enumerations:: GLX enumerated values. -@end menu - - -@node Low-Level GLX -@section Low-Level GLX -@include low-level-glx.texi - - -@node GLX Enumerations -@section GLX Enumerations -@include low-level-glx-enums.texi - - -@node GLUT -@chapter GLUT - -TODO: Write GLUT documentation. - - -@node FAQ -@chapter FAQ - -TODO: Write about things readers will want to know (instead of -commenting them in the source :) - - -@node Function Index -@unnumbered Function Index -@printindex fn -@bye +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename figl.info +@settitle Figl +@c %**end of header + +@set VERSION 2.0.0 +@set UPDATED 1 February 2013 + +@copying +This manual is for Figl (version @value{VERSION}, updated +@value{UPDATED}) + +Copyright 2013 Andy Wingo and others. + +@quotation +Figl is free software: you can redistribute and/or modify it and its +documentation under the terms of the GNU Lesser General Public License +as published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +Figl is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General +Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this program. If not, see +@uref{http://www.gnu.org/licenses/}. +@end quotation + +Portions of this document were generated from the upstream OpenGL +documentation. The work as a whole is redistributable under the +license above. Sections containing generated documentation are +prefixed with a specific copyright header. +@end copying + +@dircategory The Algorithmic Language Scheme +@direntry +* Figl: (figl.info). An OpenGL interface for Guile. +@end direntry + +@titlepage +@title Figl +@subtitle version @value{VERSION}, updated @value{UPDATED} +@author Andy Wingo +@author (many others) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top +@top Figl + +@insertcopying + +@menu +* Introduction:: The what, why, and how of Figl. + +* GL:: A Scheme interface to OpenGL. +* GLU:: The GL Utility library. +* GLX:: Using OpenGL with the X Window System. +* GLUT:: The GL Utility Toolkit. + +* FAQ:: Figl answers questions. + +* Function Index:: +@end menu + +@end ifnottex + +@iftex +@shortcontents +@end iftex + + +@node Introduction +@chapter Introduction + +Figl is the Foreign Interface to GL: an OpenGL binding for Guile. + +OpenGL is a family of APIs and layers. The following chapters discuss +the parts of OpenGL and how they are bound by Figl. + +But before that, some notes on the Figl binding as a whole. + +@menu +* About Figl:: The structure of the binding. +@end menu + + +@node About Figl +@section About Figl + +Figl is a @dfn{foreign} interface to OpenGL because it uses the +dynamic @dfn{foreign function interface} provided by Guile 2.0, +providing access to OpenGL without any C code at all. In fact, much +of Figl (and this manual) is automatically generated from upstream API +specifications and documentation. + +We have tried to do a very complete job at wrapping OpenGL, and +additionally have tried to provide a nice Scheme interface as well. +Our strategy has been to separate the binding into low-level and +high-level pieces. + +The low-level bindings correspond exactly with the GL specification, +and are well-documented. However, these interfaces are not so nice to +use from Scheme; output arguments have to be allocated by the caller, +and there is only the most basic level of type checking, and no sanity +checking at all. For example, you can pass a bytevector of image data +to the low-level @code{glTexImage2D} procedure, but no check is made +that the dimensions you specify actually correspond to the size of the +bytevector. This function could end up reading past the end of the +bytevector. Worse things can happen with procedures that write to +arrays, like @code{glGetTexImage}. + +The high-level bindings are currently a work in progress, and are +being manually written. They intend to be a complete interface to the +GL, without the need to use the low-level bindings. However, the +low-level bindings will always be available for you to use if needed, +and have the advantage that their behavior is better documented and +specified by OpenGL itself. + +Low-level bindings are accessed by loading the @code{(figl +@var{module} low-level)}, for example via: + +@example +(use-modules (figl gl low-level)) +@end example + +The high-level modules are named like @code{(figl @var{module})}, for +example @code{(figl gl)}. + + +@c Defines the GL node and chapter. +@include gl.texi + + +@node GLU +@chapter GLU + +@menu +* Low-Level GLU:: Primitive interface to ``glu'' functionality. +@end menu + +@node Low-Level GLU +@section Low-Level GLU +@include low-level-glu.texi + + +@node GLX +@chapter GLX + +@menu +* Low-Level GLX:: Primitive interface to ``glX'' functionality. +* GLX Enumerations:: GLX enumerated values. +@end menu + + +@node Low-Level GLX +@section Low-Level GLX +@include low-level-glx.texi + + +@node GLX Enumerations +@section GLX Enumerations +@include low-level-glx-enums.texi + + +@node GLUT +@chapter GLUT + +TODO: Write GLUT documentation. + + +@node FAQ +@chapter FAQ + +TODO: Write about things readers will want to know (instead of +commenting them in the source :) + + +@node Function Index +@unnumbered Function Index +@printindex fn +@bye diff --git a/doc/figl.texi b/doc/gl.texi similarity index 50% copy from doc/figl.texi copy to doc/gl.texi index 1792ab4..dee0867 100644 --- a/doc/figl.texi +++ b/doc/gl.texi @@ -1,138 +1,3 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename figl.info -@settitle Figl -@c %**end of header - -@set VERSION 2.0.0 -@set UPDATED 1 February 2013 - -@copying -This manual is for Figl (version @value{VERSION}, updated -@value{UPDATED}) - -Copyright 2013 Andy Wingo and others. - -@quotation -Figl is free software: you can redistribute and/or modify it and its -documentation under the terms of the GNU Lesser General Public License -as published by the Free Software Foundation, either version 3 of the -License, or (at your option) any later version. - -Figl is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General -Public License for more details. - -You should have received a copy of the GNU Lesser General Public -License along with this program. If not, see -@uref{http://www.gnu.org/licenses/}. -@end quotation - -Portions of this document were generated from the upstream OpenGL -documentation. The work as a whole is redistributable under the -license above. Sections containing generated documentation are -prefixed with a specific copyright header. -@end copying - -@dircategory The Algorithmic Language Scheme -@direntry -* Figl: (figl.info). An OpenGL interface for Guile. -@end direntry - -@titlepage -@title Figl -@subtitle version @value{VERSION}, updated @value{UPDATED} -@author Andy Wingo -@author (many others) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top Figl - -@insertcopying - -@menu -* Introduction:: The what, why, and how of Figl. - -* GL:: A Scheme interface to OpenGL. -* GLU:: The GL Utility library. -* GLX:: Using OpenGL with the X Window System. -* GLUT:: The GL Utility Toolkit. - -* FAQ:: Figl answers questions. - -* Function Index:: -@end menu - -@end ifnottex - -@iftex -@shortcontents -@end iftex - - -@node Introduction -@chapter Introduction - -Figl is the Foreign Interface to GL: an OpenGL binding for Guile. - -OpenGL is a family of APIs and layers. The following chapters discuss -the parts of OpenGL and how they are bound by Figl. - -But before that, some notes on the Figl binding as a whole. - -@menu -* About Figl:: The structure of the binding. -@end menu - - -@node About Figl -@section About Figl - -Figl is a @dfn{foreign} interface to OpenGL because it uses the -dynamic @dfn{foreign function interface} provided by Guile 2.0, -providing access to OpenGL without any C code at all. In fact, much -of Figl (and this manual) is automatically generated from upstream API -specifications and documentation. - -We have tried to do a very complete job at wrapping OpenGL, and -additionally have tried to provide a nice Scheme interface as well. -Our strategy has been to separate the binding into low-level and -high-level pieces. - -The low-level bindings correspond exactly with the GL specification, -and are well-documented. However, these interfaces are not so nice to -use from Scheme; output arguments have to be allocated by the caller, -and there is only the most basic level of type checking, and no sanity -checking at all. For example, you can pass a bytevector of image data -to the low-level @code{glTexImage2D} procedure, but no check is made -that the dimensions you specify actually correspond to the size of the -bytevector. This function could end up reading past the end of the -bytevector. Worse things can happen with procedures that write to -arrays, like @code{glGetTexImage}. - -The high-level bindings are currently a work in progress, and are -being manually written. They intend to be a complete interface to the -GL, without the need to use the low-level bindings. However, the -low-level bindings will always be available for you to use if needed, -and have the advantage that their behavior is better documented and -specified by OpenGL itself. - -Low-level bindings are accessed by loading the @code{(figl -@var{module} low-level)}, for example via: - -@example -(use-modules (figl gl low-level)) -@end example - -The high-level modules are named like @code{(figl @var{module})}, for -example @code{(figl gl)}. - @node GL @chapter GL @@ -142,8 +7,9 @@ example @code{(figl gl)}. * About OpenGL:: Know the past to understand the present. * GL Contexts:: Finding a square of pixels. * Rendering:: How to paint. -* Low-Level GL:: Primitive interface to OpenGL. +* GL API:: The OpenGL interface, organized by section. * GL Enumerations:: Enumerated values. +* Low-Level GL:: Primitive interface to OpenGL. * GL Extensions:: Beyond core OpenGL. @end menu @@ -205,6 +71,9 @@ implementations that are actually deployed in the wild; its legacy API looks back to OpenGL 1.x, while the buffer-oriented API is compatible with OpenGL ES. +The full OpenGL 2.1 specification is available at +@uref{http://www.opengl.org/registry/doc/glspec21.20061201.pdf}. + @node GL Contexts @section GL Contexts @@ -301,9 +170,330 @@ and doing less floating-point math in tight loops can only be a good thing. -@node Low-Level GL -@section Low-Level GL -@include low-level-gl.texi +@node GL API +@section GL API + +The procedures exported from the @code{(figl gl)} module are +documented below, organized by their corresponding section in the +OpenGL 2.1 specification. + +@example +(use-modules (figl gl)) +@end example + +See @uref{http://www.opengl.org/registry/doc/glspec21.20061201.pdf}, +for more information. + +@menu +* OpenGL Operation:: +* Rasterization:: +* Per Fragment Operations:: +* Special Functions:: +* State and State Requests:: +@end menu + + +@node OpenGL Operation +@subsection OpenGL Operation + +@subsubsection Begin/End Paradigm + +@defmac gl-begin begin-mode body ... +Begin immediate-mode drawing with @var{begin-mode}, evaluate +the sequence of @var{body} expressions, and then end drawing (as with +@code{glBegin} and @code{glEnd}). + +The values produced by the last @var{body} expression are returned to +the continuation of the @code{gl-begin}. +@end defmac + +@defun gl-edge-flag boundary? +Flag edges as either boundary or nonboundary. Note that the edge mode +is only significant if the @code{polygon-mode} is @code{line} or +@code{point}. +@end defun + +@subsubsection Vertex Specification + +@defun gl-vertex x y [z=0.0] [w=1.0] +Draw a vertex at the given coordinates. +@end defun + +The following procedures modify the current per-vertex state. Drawing +a vertex captures the current state and associates it with the +vertex. + +@defun gl-texture-coordinate s [t=0.0] [r=0.0] [q=1.0] +Set the current texture coordinate. +@end defun + +@defun gl-multi-texture-coordinate texture s [t=0.0] [r=0.0] [q=1.0] +Set the current texture coordinate for a specific texture unit. +@end defun + +@defun gl-color red green blue [alpha=1.0] +Set the current color. +@end defun + +@defun gl-vertex-attribute index x [y=0.0] [z=0.0] [w=1.0] +Set the current value of a generic vertex attribute. +@end defun + +@defun gl-normal x y z +Set the current normal vector. By default the normal should have unit +length, though setting @code{(enable-cap rescale-normal)} or +@code{(enable-cap normalize)} can change this. +@end defun + +@defun gl-fog-coordinate coord +Set the current fog coordinate. +@end defun + +@defun gl-secondary-color red green blue +Set the current secondary color. +@end defun + +@defun gl-index c +Set the current color index. +@end defun + +@subsubsection Rectangles + +@defun gl-rectangle x1 y1 x2 y2 +Draw a rectangle in immediate-mode with a given pair of corner +points. +@end defun + +@subsubsection Coordinate Transformation + +@defun gl-depth-range near-val far-val +Specify the mapping of the near and far clipping planes, respectively, +to window coordinates. +@end defun + +@defun gl-viewport x y width height +Set the viewport: the pixel position of the lower-left corner of the +viewport rectangle, and the width and height of the viewport. +@end defun + +@defun gl-load-matrix m [#:transpose=#f] +Load a matrix. @var{m} should be a packed vector in column-major +order. + +Note that Guile's two-dimensional arrays are stored in row-major +order, so you might need to transpose the matrix as it is loaded (via +the @code{#:transpose} keyword argument). +@end defun + +@defun gl-multiply-matrix m [#:transpose=#f] +Multiply the current matrix by @var{m}. As with +@code{gl-load-matrix}, you might need to transpose the matrix first. +@end defun + +@defun set-gl-matrix-mode matrix-mode +Set the current matrix mode. See the @code{matrix-mode} enumerator. +@end defun + +@defmac with-gl-push-matrix body ... +Save the current matrix, evaluate the sequence of @var{body} +expressions, and restore the saved matrix. +@end defmac + +@defun gl-load-identity +Load the identity matrix. +@end defun + +@defun gl-rotate angle x y z +Rotate the current matrix about the vector +@code{(@var{x},@var{y},@var{z})}. @var{angle} should be specified in +degrees. +@end defun + +@defun gl-translate x y z +Translate the current matrix. +@end defun + +@defun gl-scale x y z +Scale the current matrix. +@end defun + +@defun gl-frustum left right bottom top near-val far-val +Multiply the current matrix by a perspective matrix. @var{left}, +@var{right}, @var{bottom}, and @var{top} are the coordinates of the +corresponding clipping planes. @var{near-val} and @var{far-val} +specify the distances to the near and far clipping planes. +@end defun + +@defun gl-ortho left right bottom top near-val far-val +Multiply the current matrix by a perspective matrix. @var{left}, +@var{right}, @var{bottom}, and @var{top} are the coordinates of the +corresponding clipping planes. @var{near-val} and @var{far-val} +specify the distances to the near and far clipping planes. +@end defun + +@defun set-gl-active-texture texture +Set the active texture unit. +@end defun + +@defun gl-enable enable-cap +@defunx gl-disable enable-cap +Enable or disable server-side GL capabilities. +@end defun + +@subsubsection Colors and Coloring + +@defun set-gl-shade-model mode +Select flat or smooth shading. +@end defun + + +@node Rasterization +@subsection Rasterization + + +@node Per Fragment Operations +@subsection Per-Fragment Operations + +@defun set-gl-stencil-function stencil-function k [#:mask] [#:face] +Set the front and/or back function and the reference value @var{k} for +stencil testing. Without the @var{face} keyword argument, both +functions are set. The default @var{mask} is all-inclusive. +@end defun + +@defun set-gl-stencil-operation stencil-fail depth-fail depth-pass [#:face] +Set the front and/or back stencil test actions. Without the +@var{face} keyword argument, both stencil test actions are set. See +the @code{stencil-op} enumeration for possible values for +@var{stencil-fail}, @var{depth-fail}, and @var{depth-pass}. +@end defun + +@defun set-gl-blend-equation mode-rgb [mode-alpha=mode-rgb] +Set the blend equation. With one argument, set the same blend +equation for all components. Pass two arguments to specify a separate +equation for the alpha component. +@end defun + +@defun set-gl-blend-function src-rgb dest-rgb [src-alpha=src-rgb] [dest-alpha=dest-rgb] +Set the blend function. With two arguments, set the same blend +function for all components. Pass an additional two arguments to +specify separate functions for the alpha components. +@end defun + +@defun set-gl-scissor x y width height +Define the scissor box. The box is defined in window coordinates, +with (@var{x},@var{y}) being the lower-left corner of the box. +@end defun + +@defun set-gl-sample-coverage value invert +Specify multisample coverage parameters. +@end defun + +@defun set-gl-alpha-function func ref +Specify the alpha test function. See the @code{alpha-function} +enumerator. +@end defun + +@defun set-gl-depth-function func +Specify the depth test function. See the @code{depth-function} +enumerator. +p@end defun + +@defun set-gl-blend-color r g b a +Specify the blend color. +@end defun + +@defun set-gl-logic-operation opcode +Specify a logical pixel operation for color index rendering. +@end defun + +@subsubsection Whole Framebuffer Operations + +@defun set-gl-draw-buffers buffers +Specify a list of color buffers to be drawn into. @var{buffers} +should be a list of @code{draw-buffer-mode} enumerated values. +@end defun + +@defun set-gl-stencil-mask mask [#:face] +Control the writing of individual bits into the front and/or back +stencil planes. With one argument, the stencil mask for both states +are set. +@end defun + +@defun set-gl-draw-buffer mode +Specify the buffer or buffers to draw into. +@end defun + +@defun set-gl-index-mask mask +Control the writing of individual bits into the color index buffers. +@end defun + +@defun set-gl-color-mask red? green? blue? alpha? +Enable and disable writing of frame buffer color components. +@end defun + +@defun set-gl-depth-mask enable? +Enable and disable writing into the depth buffer. +@end defun + +@defun gl-clear mask +Clear a set of buffers to pre-set values. Use the +@code{clear-buffer-mask} enumerator to specify which buffers to clear. +@end defun + +@defun set-gl-clear-color r g b a +Set the clear color for the color buffers. +@end defun + +@defun set-gl-clear-index c +Set the clear index for the color index buffers. +@end defun + +@defun set-gl-clear-depth depth +Set the clear value for the depth buffer. +@end defun + +@defun set-gl-clear-stencil-value s +Set the clear value for the stencil buffer. +@end defun + +@defun set-gl-clear-accumulation-color r g b a +Set the clear color for the accumulation buffer. +@end defun + +@defun set-gl-accumulation-buffer-operation op value +Operate on the accumulation buffer. @var{op} may be one of the +@code{accum-op} enumerated values. The interpretation of @var{value} +depends on @var{op}. +@end defun + +@subsubsection Drawing, Reading and Copying Pixels + +@defun set-gl-read-buffer mode +Select a color buffer source for pixels. Use @code{read-buffer-mode} +to select a mode. +@end defun + +@defun gl-copy-pixels x y width height type +Copy pixels from a screen-aligned rectangle in the frame buffer to a +region relative to the current raster position. @var{type} selects +which buffer to copy from. +@end defun + + +@node Special Functions +@subsection Special Functions + + +@node State and State Requests +@subsection State and State Requests + +@subsubsection Querying GL State + +@defmac with-gl-push-attrib bits body ... +Save part of the current state, evaluation the sequence of @var{body} +expressions, then restore the state. Use @code{attrib-mask} to +specify which parts of the state to save. +@end defmac @node GL Enumerations @@ -311,6 +501,11 @@ thing. @include low-level-gl-enums.texi +@node Low-Level GL +@section Low-Level GL +@include low-level-gl.texi + + @node GL Extensions @section GL Extensions @@ -352,52 +547,3 @@ And that's that. It's a low-level binding, but what did you expect? Note that you'll still need to check for the availability of this extension at runtime with @code{(glGetString GL_EXTENSIONS)}. - -@node GLU -@chapter GLU - -@menu -* Low-Level GLU:: Primitive interface to ``glu'' functionality. -@end menu - -@node Low-Level GLU -@section Low-Level GLU -@include low-level-glu.texi - - -@node GLX -@chapter GLX - -@menu -* Low-Level GLX:: Primitive interface to ``glX'' functionality. -* GLX Enumerations:: GLX enumerated values. -@end menu - - -@node Low-Level GLX -@section Low-Level GLX -@include low-level-glx.texi - - -@node GLX Enumerations -@section GLX Enumerations -@include low-level-glx-enums.texi - - -@node GLUT -@chapter GLUT - -TODO: Write GLUT documentation. - - -@node FAQ -@chapter FAQ - -TODO: Write about things readers will want to know (instead of -commenting them in the source :) - - -@node Function Index -@unnumbered Function Index -@printindex fn -@bye -- 2.20.1