glGetTexLevelParameter.3   [plain text]

'\" e  
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp May 22 14:45
.ds Dm 7 May 22 14:
.ds Xs 50913     7
.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\fP,
\%\f3glGetTexParameter\fP,
\%\f3glCopyTexImage1D\fP,
\%\f3glCopyTexImage2D\fP,
\%\f3glCopyTexSubImage1D\fP,
\%\f3glCopyTexSubImage2D\fP,
\%\f3glCopyTexSubImage3D\fP,
\%\f3glTexEnv\fP,
\%\f3glTexGen\fP,
\%\f3glTexImage1D\fP,
\%\f3glTexImage2D\fP,
\%\f3glTexImage3D\fP,
\%\f3glTexSubImage1D\fP,
\%\f3glTexSubImage2D\fP,
\%\f3glTexSubImage3D\fP,
\%\f3glTexParameter\fP