sync code with last improvements from OpenBSD

doc/gl-docs/GL/gl/gettexlevelparameter.3gl

@@ -0,0 +1,182 @@
+'\" e
+'\"! eqn | mmdoc
+'\"macro stdmacro
+.ds Vn Version 1.2
+.ds Dt 24 September 1999
+.ds Re Release 1.2.1
+.ds Dp Jan 14 18:30
+.ds Dm 01 gettexlev
+.ds Xs 50913 7 gettexlevelparameter.gl
+.TH GLGETTEXLEVELPARAMETER 3G
+.SH NAME
+.B "glGetTexLevelParameterfv, glGetTexLevelParameteriv
+\- return texture parameter values for a specific level of detail
+
+.SH C SPECIFICATION
+void \f3glGetTexLevelParameterfv\fP(
+GLenum \fItarget\fP,
+.nf
+.ta \w'\f3void \fPglGetTexLevelParameterfv( 'u
+	GLint \fIlevel\fP,
+	GLenum \fIpname\fP,
+	GLfloat \fI*params\fP )
+.fi
+void \f3glGetTexLevelParameteriv\fP(
+GLenum \fItarget\fP,
+.nf
+.ta \w'\f3void \fPglGetTexLevelParameteriv( 'u
+	GLint \fIlevel\fP,
+	GLenum \fIpname\fP,
+	GLint \fI*params\fP )
+.fi
+
+.EQ
+delim $$
+.EN
+.SH PARAMETERS
+.TP \w'\f2target\fP\ \ 'u 
+\f2target\fP
+Specifies the symbolic name of the target texture,
+either \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP, \%\f3GL_TEXTURE_3D\fP,
+\%\f3GL_PROXY_TEXTURE_1D\fP, \%\f3GL_PROXY_TEXTURE_2D\fP, or
+\%\f3GL_PROXY_TEXTURE_3D\fP.
+.TP
+\f2level\fP
+Specifies the level-of-detail number of the desired image.
+Level 0 is the base image level.
+Level $n$ is the $n$th mipmap reduction image.
+.TP
+\f2pname\fP
+Specifies the symbolic name of a texture parameter.
+\%\f3GL_TEXTURE_WIDTH\fP,
+\%\f3GL_TEXTURE_HEIGHT\fP,
+\%\f3GL_TEXTURE_DEPTH\fP,
+\%\f3GL_TEXTURE_INTERNAL_FORMAT\fP,
+\%\f3GL_TEXTURE_BORDER\fP,
+\%\f3GL_TEXTURE_RED_SIZE\fP,
+\%\f3GL_TEXTURE_GREEN_SIZE\fP,
+\%\f3GL_TEXTURE_BLUE_SIZE\fP,
+\%\f3GL_TEXTURE_ALPHA_SIZE\fP,
+\%\f3GL_TEXTURE_LUMINANCE_SIZE\fP, and
+\%\f3GL_TEXTURE_INTENSITY_SIZE\fP are accepted.
+.TP
+\f2params\fP
+Returns the requested data.
+.SH DESCRIPTION
+\%\f3glGetTexLevelParameter\fP returns in \f2params\fP texture parameter values for a specific 
+level-of-detail value,
+specified as \f2level\fP.
+\f2target\fP defines the target texture,
+either \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP, \%\f3GL_TEXTURE_3D\fP,
+\%\f3GL_PROXY_TEXTURE_1D\fP, 
+\%\f3GL_PROXY_TEXTURE_2D\fP, or
+\%\f3GL_PROXY_TEXTURE_3D\fP.
+.BR
+.P
+\%\f3GL_MAX_TEXTURE_SIZE\fP, and \%\f3GL_MAX_3D_TEXTURE_SIZE\fP are not really
+descriptive enough.
+It has to report the largest square texture image that can be
+accommodated with mipmaps and borders, 
+but a long skinny texture, or a texture without mipmaps and borders, may
+easily fit in texture memory. 
+The proxy targets allow the user to more accurately query
+whether the GL can accommodate a texture of a given configuration.
+If the texture cannot be accommodated, the texture state variables, which
+may be queried with \%\f3glGetTexLevelParameter\fP, are set to 0.  If the texture can be accommodated,
+the texture state values will be set as they would be set for a
+non-proxy target.
+.P
+\f2pname\fP specifies the texture parameter whose value or values
+will be returned.
+.P
+The accepted parameter names are as follows:
+.TP 10
+\%\f3GL_TEXTURE_WIDTH\fP
+\f2params\fP returns a single value,
+the width of the texture image.
+This value includes the border of the texture image. The initial value is
+0. 
+.TP
+\%\f3GL_TEXTURE_HEIGHT\fP
+\f2params\fP returns a single value,
+the height of the texture image.
+This value includes the border of the texture image. The initial value is
+0.
+.TP
+\%\f3GL_TEXTURE_DEPTH\fP
+\f2params\fP returns a single value,
+the depth of the texture image.
+This value includes the border of the texture image. The initial value is
+0.
+.TP
+\%\f3GL_TEXTURE_INTERNAL_FORMAT\fP
+\f2params\fP returns a single value,
+the internal  of the texture image. 
+.TP
+\%\f3GL_TEXTURE_BORDER\fP
+\f2params\fP returns a single value,
+the width in pixels of the border of the texture image. The initial value
+is 0. 
+.TP
+\%\f3GL_TEXTURE_RED_SIZE\fP,
+.TP
+\%\f3GL_TEXTURE_GREEN_SIZE\fP,
+.TP
+\%\f3GL_TEXTURE_BLUE_SIZE\fP,
+.TP
+\%\f3GL_TEXTURE_ALPHA_SIZE\fP,
+.TP
+\%\f3GL_TEXTURE_LUMINANCE_SIZE\fP, 
+.TP
+\%\f3GL_TEXTURE_INTENSITY_SIZE\fP
+The internal storage resolution of an individual component.
+The resolution chosen by the GL will be a close match for the resolution
+requested by the user with the component argument of \%\f3glTexImage1D\fP,
+\%\f3glTexImage2D\fP, \%\f3glTexImage3D\fP, \%\f3glCopyTexImage1D\fP, and
+\%\f3glCopyTexImage2D\fP. The initial value is 0. 
+.SH NOTES
+If an error is generated,
+no change is made to the contents of \f2params\fP.
+.P
+\%\f3GL_TEXTURE_INTERNAL_FORMAT\fP is available only if the GL version is
+1.1 or greater. In version 1.0, use \%\f3GL_TEXTURE_COMPONENTS\fP
+instead.
+.P
+\%\f3GL_PROXY_TEXTURE_1D\fP and \%\f3GL_PROXY_TEXTURE_2D\fP are 
+available only if the GL version is 1.1 or greater.
+.P
+\%\f3GL_TEXTURE_3D\fP, \%\f3GL_PROXY_TEXTURE_3D\fP, and \%\f3GL_TEXTURE_DEPTH\fP
+are available only if the GL version is 1.2 or greater.
+.P
+When the \%\f3GL_ARB_multitexture\fP extension is supported, \%\f3glGetTexLevelParameter\fP returns
+the texture level parameters for the active texture unit.
+.SH ERRORS
+\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP or \f2pname\fP is not an
+accepted value.
+.P
+\%\f3GL_INVALID_VALUE\fP is generated if \f2level\fP is less than 0.
+.P 
+\%\f3GL_INVALID_VALUE\fP may be generated if \f2level\fP is greater
+than $ log sub 2$ \f2max\fP,
+where \f2max\fP is the returned value of \%\f3GL_MAX_TEXTURE_SIZE\fP.
+.P
+\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glGetTexLevelParameter\fP
+is executed between the execution of \%\f3glBegin\fP
+and the corresponding execution of \%\f3glEnd\fP.
+.SH SEE ALSO
+\%\f3glActiveTextureARB(3G)\fP,
+\%\f3glGetTexParameter(3G)\fP,
+\%\f3glCopyTexImage1D(3G)\fP,
+\%\f3glCopyTexImage2D(3G)\fP,
+\%\f3glCopyTexSubImage1D(3G)\fP,
+\%\f3glCopyTexSubImage2D(3G)\fP,
+\%\f3glCopyTexSubImage3D(3G)\fP,
+\%\f3glTexEnv(3G)\fP,
+\%\f3glTexGen(3G)\fP,
+\%\f3glTexImage1D(3G)\fP,
+\%\f3glTexImage2D(3G)\fP,
+\%\f3glTexImage3D(3G)\fP,
+\%\f3glTexSubImage1D(3G)\fP,
+\%\f3glTexSubImage2D(3G)\fP,
+\%\f3glTexSubImage3D(3G)\fP,
+\%\f3glTexParameter(3G)\fP