📄 appendixb.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-2">
<META NAME="GENERATOR" CONTENT="Mozilla/4.07 [en] (Win98; I) [Netscape]">
<META NAME="Author" CONTENT="Goran UnreaL Krajnovic">
<TITLE>Appendix B - OpenGL Programming Guide (Addison-Wesley Publishing Company)</TITLE>
</HEAD>
<BODY BGCOLOR="#EFEFEF" LINK="#0000FF" VLINK="#551A8B" ALINK="#FF0000">
<DIV ALIGN=right><IMG SRC="figures/SGI_ID.gif" ALT="Silicon Graphics" NOSAVE HEIGHT=43 WIDTH=151 ALIGN=TEXTTOP></DIV>
<HR>
<H1>
Appendix B<BR>
OpenGL State Variables</H1>
This appendix lists the queryable OpenGL state variables, their default
values, and the commands for obtaining the values of these variables. It
also describes OpenGL's error handling facility, and how to save and restore
sets of state variables. The <I>OpenGL Reference Manual</I> contains detailed
information on all the commands and constants discussed in this appendix.
This appendix has these major sections:
<UL>"The Query Commands"
<BR>
<P>"Error Handling"
<BR>
<P>"Saving and Restoring Sets of State Variables"
<BR>
<P>"OpenGL State Variables"</UL>
<HR>
<H2>
<A NAME="X"></A>The Query Commands</H2>
There are four commands for obtaining simple state variables, and one for
determining whether a particular state is enabled or disabled.void <B>glGetBooleanv</B>(GLenum
<B>pname</B>, GLboolean *<B>params</B>);
<BR>void <B>glGetIntegerv</B>(GLenum <B>pname</B>, GLint *<B>params</B>);
<BR>void <B>glGetFloatv</B>(GLenum <B>pname</B>, GLfloat *<B>params</B>);
<BR>void <B>glGetDoublev</B>(GLenum <B>pname</B>, GLdouble *<B>params</B>);
<P>Obtains Boolean, integer, floating-point, or double-precision state
variables. The <B>pname</B> argument is a symbolic constant indicating
the state variable to return, and <B>params</B> is a pointer to an array
of the indicated type in which to place the returned data. The possible
values for <B>pname</B> are listed in the tables in "OpenGL State Variables."
A type conversion is performed if necessary to return the desired variable
as the requested data type.
<P>GLboolean <B>glIsEnabled</B>(GLenum <B>cap</B>)
<P>Returns GL_TRUE if the mode specified by <B>cap</B> is enabled; otherwise,
returns GL_FALSE. The possible values for <B>cap</B> are listed in the
tables in "OpenGL State Variables"
<P>Other specialized commands return specific state variables. The prototypes
for these commands are listed here; to find out when you need to use these
commands, use the tables in "OpenGL State Variables" Also see the <I>OpenGL
Reference Manual</I>. OpenGL's error handling facility and the <B>glGetError()</B>
command are described in more detail in the next section.
<DL>
<DT>
void <B>glGetClipPlane</B>(GLenum <B>plane</B>, GLdouble *<B>equation</B>);</DT>
<DD>
</DD>
<DT>
</DT>
<BR>GLenum <B>glGetError</B>(void);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetLight</B>{if}<B>v</B>(GLenum <B>light</B>, GLenum <B>pname</B>,
<B>TYPE</B> *<B>params</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetMap</B>{ifd}<B>v</B>(GLenum <B>target</B>, GLenum <B>query</B>,
<B>TYPE</B> *<B>v</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetMaterial</B>{if}<B>v</B>(GLenum <B>face</B>, GLenum <B>pname</B>,
<B>TYPE</B> *<B>params</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetPixelMap</B>{f ui us}<B>v</B>(GLenum <B>map</B>, <B>TYPE</B>
*<B>values</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetPolygonStipple</B>(GLubyte *<B>mask</B>);
<DD>
</DD>
<DT>
</DT>
<BR>const GLubyte * <B>glGetString</B>(GLenum <B>name</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetTexEnv</B>{if}<B>v</B>(GLenum <B>target</B>, GLenum <B>pname</B>,
<B>TYPE</B> *<B>params</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetTexGen</B>{ifd}<B>v</B>(GLenum <B>coord</B>, GLenum <B>pname</B>,
<B>TYPE</B> *<B>params</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetTexImage</B>(GLenum <B>target</B>, GLint <B>level</B>,
GLenum <B>format</B>, GLenum <B>type</B>, GLvoid *<B>pixels</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetTexLevelParameter</B>{if}<B>v</B>(GLenum <B>target</B>,
GLint <B>level</B>, GLenum <B>pname</B>, <B>TYPE</B> *<B>params</B>);
<DD>
</DD>
<DT>
</DT>
<BR>void <B>glGetTexParameter</B>{if}<B>v</B>(GLenum <B>target</B>, GLenum
<B>pname</B>, <B>TYPE</B> *<B>params</B>);
<DD>
</DD>
</DL>
<HR>
<H2>
Error Handling</H2>
When OpenGL detects an error, it records a current error code. The command
that caused the error is ignored, so it has no effect on OpenGL state or
on the framebuffer contents. (If the error recorded was GL_OUT_OF_MEMORY,
however, the results of the command are undefined.) Once recorded, the
current error code isn't cleared - that is, additional errors aren't recorded
- until you call the query command <B>glGetError()</B>, which returns the
current error code. In distributed implementations of OpenGL, there might
be multiple current error codes, each of which remains set until queried.
Once you've queried all the current error codes, or if there's no error,
<B>glGetError()</B> returns GL_NO_ERROR. Thus, if you obtain an error code,
it's good practice to continue to call <B>glGetError()</B> until GL_NO_ERROR
is returned to be sure you've discovered all the errors. Table B-1 lists
the defined OpenGL error codes.
<P>You can use the GLU routine <B>gluErrorString()</B> to obtain a descriptive
string corresponding to the error code passed in. This routine is described
in more detail in "Describing Errors." Note that GLU routines often return
error values if an error is detected. Also, the GLU defines the error codes
GLU_INVALID_ENUM, GLU_INVALID_VALUE, and GLU_OUT_OF_MEMORY, which have
the same meaning as the related OpenGL codes.
<TABLE BORDER CELLPADDING=10 >
<CAPTION ALIGN=TOP><B>Table B-1 : </B>OpenGL Error Codes</CAPTION>
<TR ALIGN=LEFT VALIGN=TOP>
<TH>Error Code</TH>
<TH>Description</TH>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_INVALID_ENUM</TD>
<TD>GLenum argument out of range</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_INVALID_VALUE</TD>
<TD>Numeric argument out of range</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_INVALID_OPERATION</TD>
<TD>Operation illegal in current state</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_STACK_OVERFLOW</TD>
<TD>Command would cause a stack overflow</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_STACK_UNDERFLOW</TD>
<TD>Command would cause a stack underflow</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_OUT_OF_MEMORY</TD>
<TD>Not enough memory left to execute command</TD>
</TR>
</TABLE>
<BR>
<P>
<HR>
<H2>
Saving and Restoring Sets of State Variables</H2>
You can save and restore the values of a collection of state variables
on an attribute stack with the commands <B>glPushAttrib()</B> and <B>glPopAttrib()</B>.
The attribute stack has a depth of at least 16, and the actual depth can
be obtained using GL_MAX_ATTRIB_STACK_DEPTH with <B>glGetIntegerv()</B>.
Pushing a full stack or popping an empty one generates an error.
<P>In general, it's faster to use <B>glPushAttrib()</B> and <B>glPopAttrib()</B>
than to get and restore the values yourself. Some values might be pushed
and popped in the hardware, and saving and restoring them might be expensive.
Also, if you're operating on a remote client, all the attribute data has
to be transferred across the network connection and back as it's saved
and restored. However, your OpenGL implementation keeps the attribute stack
on the server, avoiding unnecessary network delays. void <B>glPushAttrib</B>(GLbitfield
<B>mask</B>);
<P>Saves all the attributes indicated by bits in <B>mask</B> by pushing
them onto the attribute stack. Table B-2 lists the possible mask bits that
can be logically ORed together to save any combination of attributes. Each
bit corresponds to a collection of individual state variables. For example,
GL_LIGHTING_BIT refers to all the state variables related to lighting,
which include the current material color, the ambient, diffuse, specular,
and emitted light, a list of the lights that are enabled, and the directions
of the spotlights. When <B>glPopAttrib()</B> is called, all those variables
are restored. To find out exactly which attributes are saved for particular
mask values, see the tables in "OpenGL State Variables."
<TABLE BORDER CELLPADDING=10 >
<CAPTION ALIGN=TOP><B>Table B-2 : </B>Attribute Groups</CAPTION>
<TR ALIGN=LEFT VALIGN=TOP>
<TH>Mask Bit</TH>
<TH>Attribute Group</TH>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_ACCUM_BUFFER_BIT</TD>
<TD>accum-buffer</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_ALL_ATTRIB_BITS</TD>
<TD>--</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_COLOR_BUFFER_BIT</TD>
<TD>color-buffer</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_BIT</TD>
<TD>current</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_DEPTH_BUFFER_BIT</TD>
<TD>depth-buffer</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_ENABLE_BIT</TD>
<TD>enable</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_EVAL_BIT</TD>
<TD>eval</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_FOG_BIT</TD>
<TD>fog</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_HINT_BIT</TD>
<TD>hint</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_LIGHTING_BIT </TD>
<TD>lighting</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_LINE_BIT</TD>
<TD>line</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_LIST_BIT</TD>
<TD>list</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_PIXEL_MODE_BIT</TD>
<TD>pixel</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_POINT_BIT</TD>
<TD>point</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_POLYGON_BIT</TD>
<TD>polygon</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_POLYGON_STIPPLE_BIT</TD>
<TD>polygon-stipple</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_SCISSOR_BIT</TD>
<TD>scissor</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_STENCIL_BUFFER_BIT</TD>
<TD>stencil-buffer</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_TEXTURE_BIT</TD>
<TD>texture</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_TRANSFORM_BIT</TD>
<TD>transform</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_VIEWPORT_BIT </TD>
<TD>viewport</TD>
</TR>
</TABLE>
<BR>
<P>void <B>glPopAttrib</B>(void);
<P>Restores the values of those state variables that were saved with the
last <B>glPushAttrib()</B>.
<P>
<HR>
<H2>
OpenGL State Variables</H2>
The following pages contain tables that list the names of queryable state
variables. For each variable, the tables list a description of it, its
attribute group, its initial or minimum value, and the suggested <B>glGet*()</B>
command to use for obtaining it. State variables that can be obtained using
<B>glGetBooleanv()</B>, <B>glGetIntegerv()</B>, <B>glGetFloatv()</B>, or
<B>glGetDoublev()</B> are listed with just one of these commands - the
one that's most appropriate given the type of data to be returned. These
state variables can't be obtained using <B>glIsEnabled()</B>. However,
state variables for which <B>glIsEnabled()</B> is listed as the query command
can also be obtained using <B>glGetBooleanv()</B>, <B>glGetIntegerv()</B>,
<B>glGetFloatv()</B>, and <B>glGetDoublev()</B>. State variables for which
any other command is listed as the query command can be obtained only by
using that command. If no attribute group is listed, the variable doesn't
belong to any group. All queryable state variables except the implementation-dependent
ones have initial values. If no initial value is listed, you need to consult
the section where that variable is discussed (or the <I>OpenGL Reference
Manual</I>) to determine its initial value.
<P>
<HR>
<H3>
Current Values and Associated Data</H3>
<TABLE BORDER CELLPADDING=10 >
<CAPTION ALIGN=TOP><B>Table B-3 : </B>State Variables for Current Values
and Associated Data</CAPTION>
<TR ALIGN=LEFT VALIGN=TOP>
<TH>State Variable</TH>
<TH>Description</TH>
<TH>Attribute Group</TH>
<TH>Initial Value</TH>
<TH>Get Command</TH>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_COLOR</TD>
<TD>Current color</TD>
<TD>current</TD>
<TD>1, 1, 1, 1</TD>
<TD>glGetIntegerv() , glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_INDEX</TD>
<TD>Current color index</TD>
<TD>current</TD>
<TD>1</TD>
<TD>glGetIntegerv() , glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_TEXTURE_COORDS</TD>
<TD>Current texture coordinates</TD>
<TD>current</TD>
<TD>0, 0, 0, 1</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_NORMAL</TD>
<TD>Current normal</TD>
<TD>current</TD>
<TD>0, 0, 1</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_POSITION</TD>
<TD>Current raster position</TD>
<TD>current</TD>
<TD>0, 0, 0, 1</TD>
<TD>glGetFloatv()
<BR>
<BR>
<BR> </TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_DISTANCE</TD>
<TD>Current raster distance</TD>
<TD>current</TD>
<TD>0</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_COLOR</TD>
<TD>Color associated with raster position</TD>
<TD>current</TD>
<TD>1, 1, 1, 1</TD>
<TD>glGetIntegerv() , glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_INDEX</TD>
<TD>Color index associated with raster position</TD>
<TD>current</TD>
<TD>1</TD>
<TD>glGetIntegerv() , glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_TEXTURE_ COORDS</TD>
<TD>Texture coordinates associated with raster position</TD>
<TD>current</TD>
<TD>0, 0, 0, 1</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CURRENT_RASTER_POSITION_ VALID</TD>
<TD>Raster position valid bit</TD>
<TD>current</TD>
<TD>GL_TRUE</TD>
<TD>glGetBooleanv( )</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_EDGE_FLAG</TD>
<TD>Edge flag</TD>
<TD>current</TD>
<TD>GL_TRUE</TD>
<TD>glGetBooleanv( )</TD>
</TR>
</TABLE>
<BR>
<P>
<HR>
<H3>
Transformation</H3>
<TABLE BORDER CELLPADDING=10 >
<CAPTION ALIGN=TOP><B>Table B-4 : </B>Transformation State Variables</CAPTION>
<TR ALIGN=LEFT VALIGN=TOP>
<TH>State Variable</TH>
<TH>Description</TH>
<TH>Attribute Group</TH>
<TH>Initial Value</TH>
<TH>Get Command</TH>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_MODELVIEW_MATRIX</TD>
<TD>Modelview matrix stack</TD>
<TD>--</TD>
<TD>Identity</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_PROJECTION_MATRIX</TD>
<TD>Projection matrix stack</TD>
<TD>--</TD>
<TD>Identity</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_TEXTURE_MATRIX</TD>
<TD>Texture matrix stack</TD>
<TD>--</TD>
<TD>Identity</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_VIEWPORT</TD>
<TD>Viewport origin and extent</TD>
<TD>viewport</TD>
<TD>--</TD>
<TD>glGetIntegerv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_DEPTH_RANGE</TD>
<TD>Depth range near and far</TD>
<TD>viewport</TD>
<TD>0, 1</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_MODELVIEW_STACK_DEPTH</TD>
<TD>Modelview matrix stack pointer</TD>
<TD>--</TD>
<TD>1</TD>
<TD>glGetIntegerv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_PROJECTION_STACK_DEPTH</TD>
<TD>Projection matrix stack pointer</TD>
<TD>--</TD>
<TD>1</TD>
<TD>glGetIntegerv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_TEXTURE_STACK_DEPTH</TD>
<TD>Texture matrix stack pointer</TD>
<TD>--</TD>
<TD>1</TD>
<TD>glGetIntegerv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_MATRIX_MODE</TD>
<TD>Current matrix mode</TD>
<TD>transform</TD>
<TD>GL_MODELVI EW</TD>
<TD>glGetIntegerv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_NORMALIZE</TD>
<TD>Current normal normalization on/off</TD>
<TD>transform/ enable</TD>
<TD>GL_FALSE</TD>
<TD>glIsEnabled()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CLIP_PLANE<B>i</B></TD>
<TD>User clipping plane coefficients</TD>
<TD>transform</TD>
<TD>0, 0, 0, 0</TD>
<TD>glGetClipPlane()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_CLIP_PLANE<B>i</B></TD>
<TD><B>i</B>th user clipping plane enabled</TD>
<TD>transform/ enable</TD>
<TD>GL_FALSE</TD>
<TD>glIsEnabled()</TD>
</TR>
</TABLE>
<BR>
<P>
<HR>
<H3>
Coloring</H3>
<TABLE BORDER CELLPADDING=10 >
<CAPTION ALIGN=TOP><B>Table B-5 : </B>Coloring State Variables</CAPTION>
<TR ALIGN=LEFT VALIGN=TOP>
<TH>State Variable</TH>
<TH>Description</TH>
<TH>Attribute Group</TH>
<TH>Initial Value</TH>
<TH>Get Command</TH>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_FOG_COLOR</TD>
<TD>Fog color</TD>
<TD>fog</TD>
<TD>0, 0, 0, 0</TD>
<TD>glGetFloatv()</TD>
</TR>
<TR ALIGN=LEFT VALIGN=TOP>
<TD>GL_FOG_INDEX</TD>
<TD>Fog index</TD>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -