GLU manual pages from monolithic tree

1 files changed, 236 insertions, 0 deletions

diff --git a/doc/gl-docs/GLU/build2dmipmaps.3gl b/doc/gl-docs/GLU/build2dmipmaps.3gl
new file mode 100644
index 000000000..e7d970c64
--- /dev/null
+++ b/doc/gl-docs/GLU/build2dmipmaps.3gl
@@ -0,0 +1,236 @@
+'\" e
+'\"! eqn | mmdoc
+'\"macro stdmacro
+.ds Vn Version 1.2
+.ds Dt 6 March 1997
+.ds Re Release 1.2.0
+.ds Dp May 02 11:53
+.ds Dm 37 build2dmi
+.ds Xs 21901 10 build2dmipmaps.gl
+.TH GLUBUILD2DMIPMAPS 3G
+.SH NAME
+.B "gluBuild2DMipmaps
+\- builds a two-dimensional mipmap
+
+.SH C SPECIFICATION
+GLint \f3gluBuild2DMipmaps\fP(
+GLenum \fItarget\fP,
+.nf
+.ta \w'\f3GLint \fPgluBuild2DMipmaps( 'u
+	GLint \fIinternalFormat\fP,
+	GLsizei \fIwidth\fP,
+	GLsizei \fIheight\fP,
+	GLenum \fIformat\fP,
+	GLenum \fItype\fP,
+	const void \fI*data\fP )
+.fi
+
+.EQ
+delim $$
+.EN
+.SH PARAMETERS
+.TP \w'\fIinternalFormat\fP\ \ 'u 
+\f2target\fP
+Specifies the target texture.  Must be \%\f3GL_TEXTURE_2D\fP.
+.TP
+\f2internalFormat\fP
+Requests the internal storage  of the texture image.  The most
+current version of the SGI implementation of GLU does not check this
+value for validity before passing it on to the underlying OpenGL
+implementation.  A value that is not accepted by the OpenGL
+implementation will lead to an OpenGL error.  The benefit of not
+checking this value at the GLU level is that OpenGL extensions can add
+new internal texture formats without requiring a revision of the GLU
+implementation.  Older implementations of GLU check this value and
+raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
+symbolic constants:
+\%\f3GL_ALPHA\fP,
+\%\f3GL_ALPHA4\fP,
+\%\f3GL_ALPHA8\fP,
+\%\f3GL_ALPHA12\fP,
+\%\f3GL_ALPHA16\fP,
+\%\f3GL_LUMINANCE\fP,
+\%\f3GL_LUMINANCE4\fP,
+\%\f3GL_LUMINANCE8\fP,
+\%\f3GL_LUMINANCE12\fP,
+\%\f3GL_LUMINANCE16\fP,
+\%\f3GL_LUMINANCE_ALPHA\fP,
+\%\f3GL_LUMINANCE4_ALPHA4\fP,
+\%\f3GL_LUMINANCE6_ALPHA2\fP,
+\%\f3GL_LUMINANCE8_ALPHA8\fP,
+\%\f3GL_LUMINANCE12_ALPHA4\fP,
+\%\f3GL_LUMINANCE12_ALPHA12\fP,
+\%\f3GL_LUMINANCE16_ALPHA16\fP,
+\%\f3GL_INTENSITY\fP,
+\%\f3GL_INTENSITY4\fP,
+\%\f3GL_INTENSITY8\fP,
+\%\f3GL_INTENSITY12\fP,
+\%\f3GL_INTENSITY16\fP,
+\%\f3GL_RGB\fP,
+\%\f3GL_R3_G3_B2\fP,
+\%\f3GL_RGB4\fP,
+\%\f3GL_RGB5\fP,
+\%\f3GL_RGB8\fP,
+\%\f3GL_RGB10\fP,
+\%\f3GL_RGB12\fP,
+\%\f3GL_RGB16\fP,
+\%\f3GL_RGBA\fP,
+\%\f3GL_RGBA2\fP,
+\%\f3GL_RGBA4\fP,
+\%\f3GL_RGB5_A1\fP,
+\%\f3GL_RGBA8\fP,
+\%\f3GL_RGB10_A2\fP,
+\%\f3GL_RGBA12\fP or
+\%\f3GL_RGBA16\fP.
+.TP
+\f2width\fP, \f2height\fP
+Specifies in pixels the width and height, respectively, of the texture image. 
+.TP
+\f2format\fP
+Specifies the  of the pixel data.
+Must be one of
+\%\f3GL_COLOR_INDEX\fP,
+\%\f3GL_DEPTH_COMPONENT\fP,
+\%\f3GL_RED\fP,
+\%\f3GL_GREEN\fP,
+\%\f3GL_BLUE\fP,
+\%\f3GL_ALPHA\fP,
+\%\f3GL_RGB\fP,
+\%\f3GL_RGBA\fP,
+\%\f3GL_BGR\fP,
+\%\f3GL_BGRA\fP,
+\%\f3GL_LUMINANCE\fP, or
+\%\f3GL_LUMINANCE_ALPHA\fP.
+.TP
+\f2type\fP
+Specifies the data type for \f2data\fP.
+Must be one of
+\%\f3GL_UNSIGNED_BYTE\fP,
+\%\f3GL_BYTE\fP,
+\%\f3GL_BITMAP\fP,
+\%\f3GL_UNSIGNED_SHORT\fP,
+\%\f3GL_SHORT\fP,
+\%\f3GL_UNSIGNED_INT\fP,
+\%\f3GL_INT\fP, 
+\%\f3GL_FLOAT\fP, 
+\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
+\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
+\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
+\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
+\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
+\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
+\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
+\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, or
+\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP.
+.TP
+\f2data\fP
+Specifies a pointer to the image data in memory.
+
+
+.SH DESCRIPTION
+\%\f3gluBuild2DMipmaps\fP builds a series of prefiltered two-dimensional texture maps of decreasing
+resolutions called a mipmap. This is used for the antialiasing of
+texture-mapped primitives.
+.P
+A return value of zero indicates success, otherwise a GLU error code is
+returned (see \%\f3gluErrorString\fP).
+.P
+Initially, the \f2width\fP and \f2height\fP of \f2data\fP are checked to see if they
+are a power of 2. If not, a copy of \f2data\fP (not \f2data\fP), is scaled up
+or down to the nearest power of 2. This copy will be used for subsequent
+mipmapping operations described below. (If \f2width\fP or \f2height\fP is exactly
+between powers of 2, then the copy of \f2data\fP will scale upwards.)  For
+example, if \f2width\fP is 57 and \f2height\fP is 23 then a copy of \f2data\fP will
+scale up to 64 in \f2width\fP and down to 16 in depth, before mipmapping takes
+place.
+.P
+Then, proxy textures (see \f3glTexImage2D\fP) are used to determine if
+the implementation can fit the requested texture. If not, both dimensions
+are continually halved until it fits. (If the OpenGL version is \(<= 1.0,
+both maximum texture dimensions are clamped to the value returned
+by \f3glGetIntegerv\fP with the argument \%\f3GL_MAX_TEXTURE_SIZE\fP.)
+.P
+Next, a series of mipmap levels is built by decimating a copy of \f2data\fP
+in half along both dimensions until size $1 ~times~ 1$ is reached. At
+each level,
+each texel in the halved mipmap level is an average of the corresponding
+four texels in the larger mipmap level. (In the case of rectangular
+images, the decimation will ultimately reach an $N ~times~ 1$ or
+$1 ~times~ N$ configuration. Here, two texels are averaged instead.)
+.P
+\f3glTexImage2D\fP is called to load each of these mipmap levels.
+Level 0 is a copy of \f2data\fP.  The highest level is
+${log sub 2} ( max ("width","height"))$.  For example,
+if \f2width\fP is 64 and \f2height\fP is 16
+and the implementation can store a texture of this size, the following
+mipmap levels are built: $64 ~times~ 16$, $32 ~times~ 8$, $16 ~times~ 4$,
+$8 ~times~ 2$, $4 ~times~ 1$, $2 ~times~ 1$ and $1 ~times~ 1$. These correspond to
+levels 0 through 6, respectively.
+.P
+See the \f3glTexImage1D\fP reference page for a description of the
+acceptable values for \f2format\fP parameter. See the \f3glDrawPixels\fP 
+reference page for a description of the acceptable values 
+for \f2type\fP parameter.
+.SH NOTES
+
+Note that there is no direct way of querying the maximum level. This can
+be derived indirectly via \f3glGetTexLevelParameter\fP. First, query
+for the width and height actually used at level 0.  (The width and
+height may not be equal to \f2width\fP and \f2height\fP respectively since proxy
+textures might have scaled them to fit the implementation.)  Then the
+maximum level can be derived from the formula
+${log sub 2}( max (\f2width\fP,\f2height\fP))$.
+.SH NOTES
+Formats \%\f3GL_BGR\fP, and \%\f3GL_BGRA\fP, and types 
+\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
+\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
+\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
+\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
+\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
+\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
+\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
+\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
+\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
+\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP are only available if the GL version 
+is 1.2 or greater and if the GLU version is 1.3 or greater.
+.SH ERRORS
+\%\f3GLU_INVALID_VALUE\fP is returned if \f2width\fP, or \f2height\fP is < 1.
+.P
+\%\f3GLU_INVALID_ENUM\fP is returned if \f2internalFormat\fP, \f2format\fP, or \f2type\fP is not 
+legal.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_BYTE_3_3_2\fP or \%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP
+and \f2format\fP is not \%\f3GL_RGB\fP.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_6_5\fP or \%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP
+and \f2format\fP is not \%\f3GL_RGB\fP.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP or \%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP
+and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP or \%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP
+and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_8_8_8_8\fP or \%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP
+and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
+.P
+\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_10_10_10_2\fP or \%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP
+and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
+.SH SEE ALSO
+\f3glDrawPixels(3G)\fP,
+\f3glTexImage1D(3G)\fP,
+\f3glTexImage2D(3G)\fP, 
+\f3glTexImage3D(3G)\fP,
+\%\f3gluBuild1DMipmaps(3G)\fP,
+\%\f3gluBuild3DMipmaps(3G)\fP,
+\%\f3gluErrorString(3G)\fP, 
+\f3glGetTexImage(3G)\fP,
+\f3glGetTexLevelParameter(3G)\fP,
+\%\f3gluBuild1DMipmapLevels(3G)\fP,
+\%\f3gluBuild2DMipmapLevels(3G)\fP,
+\%\f3gluBuild3DMipmapLevels(3G)\fP