ryujinx/Opentk
1
0
Fork 0
mirror of https://github.com/Ryujinx/Opentk.git synced 2024-12-23 16:15:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added support for inline OpenGL documentation.

Browse source
This commit is contained in:
the_fiddler 2009-03-08 00:46:58 +00:00
parent c2d9b32ff1
commit 875263e46a
341 changed files with 104262 additions and 4929 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
Source/Bind/DocProcessor.cs Normal file
View file

@ -0,0 +1,52 @@
using System;
using System.Collections.Generic;
using System.Text;
using System.Text.RegularExpressions;
using System.IO;
using System.Xml;
using System.Xml.Xsl;
using System.Xml.XPath;
namespace Bind
{
class DocProcessor
{
static readonly Regex remove_doctype = new Regex("<!DOCTYPE.*/>", RegexOptions.Compiled | RegexOptions.Multiline);
static readonly Regex remove_mathml = new Regex(@"<(mml:math)[^>]*?>(?:.|\n)*?</\s*\1\s*>",
RegexOptions.Compiled | RegexOptions.Multiline | RegexOptions.IgnorePatternWhitespace);
static readonly StreamWriter output_stream = new StreamWriter(new MemoryStream());
static readonly XslCompiledTransform xslt = new System.Xml.Xsl.XslCompiledTransform();
static readonly XmlReaderSettings settings = new XmlReaderSettings();
public DocProcessor(string transform_file)
{
xslt.Load(transform_file);
settings.ProhibitDtd = false;
settings.XmlResolver = null;
}
public string ProcessFile(string file)
{
string text = File.ReadAllText(file);
Match m = remove_mathml.Match(text);
while (m.Length > 0)
{
text = text.Remove(m.Index, m.Length);
m = remove_mathml.Match(text);
}
//text = remove_doctype.Replace(sb.ToString(), String.Empty, 1), String.Empty);
// The pure XmlReader is ~20x faster than the XmlTextReader.
var doc = XmlReader.Create(new StringReader(text), settings);
//var doc = new XmlTextReader(new StringReader(text));
using (StringWriter sw = new StringWriter())
{
xslt.Transform(doc, null, sw);
return sw.ToString();
}
}
}
}

28
Source/Bind/GL2/Generator.cs
View file

@ -35,6 +35,8 @@ namespace Bind.GL2
protected static Regex enumToDotNet = new Regex("_[a-z|A-Z]?", RegexOptions.Compiled);
DocProcessor doc_processor = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile));
#endregion
#region --- Constructors ---
@ -70,10 +72,6 @@ namespace Bind.GL2
Bind.Structures.Function.Initialize();
Bind.Structures.Delegate.Initialize(glSpec, glSpecExt);
// Process enums and delegates - create wrappers.
Trace.WriteLine("Processing specs, please wait...");
//this.Translate();
this.WriteBindings(
Bind.Structures.Delegate.Delegates,
Bind.Structures.Function.Wrappers,
@ -460,6 +458,7 @@ namespace Bind.GL2
if (!Directory.Exists(Settings.OutputPath))
Directory.CreateDirectory(Settings.OutputPath);
// Enums
using (BindStreamWriter sw = new BindStreamWriter(Path.Combine(Settings.OutputPath, enumsFile)))
{
WriteLicense(sw, Resources.License);
@ -487,6 +486,8 @@ namespace Bind.GL2
sw.WriteLine("}");
}
// Delegates
using (BindStreamWriter sw = new BindStreamWriter(Path.Combine(Settings.OutputPath, delegatesFile)))
{
WriteLicense(sw, Resources.License);
@ -503,6 +504,8 @@ namespace Bind.GL2
sw.Unindent();
sw.WriteLine("}");
}
// Core
using (BindStreamWriter sw = new BindStreamWriter(Path.Combine(Settings.OutputPath, importsFile)))
{
WriteLicense(sw, Resources.License);
@ -518,6 +521,8 @@ namespace Bind.GL2
sw.Unindent();
sw.WriteLine("}");
}
// Wrappers
using (BindStreamWriter sw = new BindStreamWriter(Path.Combine(Settings.OutputPath, wrappersFile)))
{
WriteLicense(sw, Resources.License);
@ -632,6 +637,9 @@ namespace Bind.GL2
sw.Indent();
//sw.WriteLine("static {0}() {1} {2}", className, "{", "}"); // Static init in GLHelper.cs
sw.WriteLine();
int current = 0;
int y = Console.CursorTop;
foreach (string key in wrappers.Keys)
{
if (((Settings.Compatibility & Settings.Legacy.NoSeparateFunctionNamespaces) == Settings.Legacy.None) && key != "Core")
@ -651,6 +659,18 @@ namespace Bind.GL2
foreach (Function f in wrappers[key])
{
if ((Settings.Compatibility & Settings.Legacy.NoDocumentation) == 0)
{
Console.SetCursorPosition(0, y);
Console.WriteLine("Creating docs for #{0} ({1}) ", current++, f.Name);
try
{
sw.WriteLine(doc_processor.ProcessFile(Path.Combine(Settings.DocPath, "gl" + f.WrappedDelegate.Name + ".xml")));
}
catch (FileNotFoundException)
{ }
}
if (!f.CLSCompliant)
{
sw.WriteLine("[System.CLSCompliant(false)]");

18
Source/Bind/Settings.cs
View file

@ -12,13 +12,20 @@ namespace Bind
{
static class Settings
{
public static string InputPath = DefaultInputPath;
public static string OutputPath = DefaultOutputPath;
public static string OutputNamespace = DefaultOutputNamespace;
// Disable BeforeFieldInit.
static Settings() { }
public const string DefaultInputPath = "..\\..\\..\\Source\\Bind\\Specifications";
public const string DefaultOutputPath = "..\\..\\..\\Source\\OpenTK\\OpenGL\\Bindings";
public const string DefaultOutputNamespace = "OpenTK.Graphics";
public static string DefaultDocPath = "..\\..\\..\\Source\\Bind\\Specifications\\Docs";
public static string DefaultDocFile = "ToInlineDocs.xslt";
public static string InputPath = DefaultInputPath;
public static string OutputPath = DefaultOutputPath;
public static string OutputNamespace = DefaultOutputNamespace;
public static string DocPath = DefaultDocPath;
public static string DocFile = DefaultDocFile;
public static string GLClass = "GL"; // Needed by Glu for the AuxEnumsClass. Can be set through -gl:"xxx".
public static string OutputClass = "GL"; // The real output class. Can be set through -class:"xxx".
@ -113,6 +120,8 @@ namespace Bind
NoBoolParameters = 0x100,
/// <summary>Keep all enum tokens, even if same value (e.g. FooARB, FooEXT and FooSGI).</summary>
NoDropMultipleTokens = 0x200,
/// <summary>Do not emit inline documentation.</summary>
NoDocumentation = 0x400,
Tao = ConstIntEnums |
NoAdvancedEnumProcessing |
NoPublicUnsafeFunctions |
@ -122,7 +131,8 @@ namespace Bind
TurnVoidPointersToIntPtr |
NestedEnums |
NoBoolParameters |
NoDropMultipleTokens,
NoDropMultipleTokens |
NoDocumentation
/*GenerateAllPermutations,*/
}

38
Source/Bind/Specifications/Docs/ToInlineDocs.xslt Normal file
View file

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output omit-xml-declaration="yes"/>
<xsl:template match="/">
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<xsl:variable name="lowercase" select="'abcdefghijklmnopqrstuvwxyz'"/>
<xsl:variable name="uppercase" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
<xsl:template name ="summary" match="refentry">
/// <summary>
/// <xsl:value-of select="concat(translate(
substring(refnamediv/refpurpose, 1, 1), $lowercase, $uppercase),
substring(refnamediv/refpurpose, 2, string-length(refnamediv/refpurpose) - 1))"/>
/// </summary>
<xsl:for-each select="refsect1/variablelist/varlistentry">
<xsl:choose>
<xsl:when test="../../@id = 'parameters'">
/// <param name="{term/parameter}">
<xsl:for-each select="listitem/para">
/// <para>
/// <xsl:value-of select="normalize-space(.)"/>
/// </para>
</xsl:for-each>
/// </param>
</xsl:when>
</xsl:choose>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>

300
Source/Bind/Specifications/Docs/glAccum.xml Normal file
View file

@ -0,0 +1,300 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glAccum">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glAccum</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glAccum</refname>
<refpurpose>operate on the accumulation buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glAccum</function></funcdef>
<paramdef>GLenum <parameter>op</parameter></paramdef>
<paramdef>GLfloat <parameter>value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>op</parameter></term>
<listitem>
<para>
Specifies the accumulation buffer operation.
Symbolic constants
<constant>GL_ACCUM</constant>,
<constant>GL_LOAD</constant>,
<constant>GL_ADD</constant>,
<constant>GL_MULT</constant>,
and
<constant>GL_RETURN</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
Specifies a floating-point value used in the accumulation buffer operation.
<parameter>op</parameter> determines how <parameter>value</parameter> is used.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The accumulation buffer is an extended-range color buffer.
Images are not rendered into it.
Rather,
images rendered into one of the color buffers
are added to the contents of the accumulation buffer after rendering.
Effects such as antialiasing (of points, lines, and polygons),
motion blur,
and depth of field can be created
by accumulating images generated with different transformation matrices.
</para>
<para>
Each pixel in the accumulation buffer consists of
red, green, blue, and alpha values.
The number of bits per component in the accumulation buffer
depends on the implementation. You can examine this number
by calling <citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> four times,
with arguments <constant>GL_ACCUM_RED_BITS</constant>,
<constant>GL_ACCUM_GREEN_BITS</constant>,
<constant>GL_ACCUM_BLUE_BITS</constant>,
and <constant>GL_ACCUM_ALPHA_BITS</constant>.
Regardless of the number of bits per component,
the range of values stored by each component is
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.
</para>
<para>
<function>glAccum</function> operates on the accumulation buffer.
The first argument, <parameter>op</parameter>,
is a symbolic constant that selects an accumulation buffer operation.
The second argument, <parameter>value</parameter>,
is a floating-point value to be used in that operation.
Five operations are specified:
<constant>GL_ACCUM</constant>, <constant>GL_LOAD</constant>, <constant>GL_ADD</constant>,
<constant>GL_MULT</constant>, and <constant>GL_RETURN</constant>.
</para>
<para>
All accumulation buffer operations are limited
to the area of the current scissor box and applied identically to
the red, green, blue, and alpha components of each pixel.
If a <function>glAccum</function> operation results in a value outside the range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
the contents of an accumulation buffer pixel component are undefined.
</para>
<para>
The operations are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_ACCUM</constant></term>
<listitem>
<para>
Obtains R, G, B, and A values
from the buffer currently selected for reading (see <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>).
Each component value is divided by
<inlineequation><mml:math>
<!-- eqn: 2 sup n - 1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
is the number of bits allocated to each color component
in the currently selected buffer.
The result is a floating-point value in the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
which is multiplied by <parameter>value</parameter> and added to the corresponding pixel component
in the accumulation buffer,
thereby updating the accumulation buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LOAD</constant></term>
<listitem>
<para>
Similar to <constant>GL_ACCUM</constant>,
except that the current value in the accumulation buffer is not used
in the calculation of the new value.
That is, the R, G, B, and A values from the currently selected buffer
are divided by
<inlineequation><mml:math>
<!-- eqn: 2 sup n - 1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
multiplied by <parameter>value</parameter>,
and then stored in the corresponding accumulation buffer cell,
overwriting the current value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_ADD</constant></term>
<listitem>
<para>
Adds <parameter>value</parameter> to each R, G, B, and A
in the accumulation buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_MULT</constant></term>
<listitem>
<para>
Multiplies each R, G, B, and A
in the accumulation buffer by <parameter>value</parameter> and returns the scaled component
to its corresponding accumulation buffer location.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_RETURN</constant></term>
<listitem>
<para>
Transfers accumulation buffer values
to the color buffer or buffers currently selected for writing.
Each R, G, B, and A component is multiplied by <parameter>value</parameter>,
then multiplied by
<inlineequation><mml:math>
<!-- eqn: 2 sup n - 1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0, 2 sup n - 1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>,
and stored
in the corresponding display buffer cell.
The only fragment operations that are applied to this transfer are
pixel ownership,
scissor,
dithering,
and color writemasks.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
To clear the accumulation buffer, call <citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry> with R, G, B,
and A values to set it to, then call <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> with the
accumulation buffer enabled.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Only pixels within the current scissor box are updated by a
<function>glAccum</function> operation.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>op</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if there is no accumulation buffer.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glAccum</function>
is executed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_RED_BITS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_GREEN_BITS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_BLUE_BITS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_ALPHA_BITS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

93
Source/Bind/Specifications/Docs/glActiveTexture.xml Normal file
View file

@ -0,0 +1,93 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glActiveTexture">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glActiveTexture</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glActiveTexture</refname>
<refpurpose>select active texture unit</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glActiveTexture</function></funcdef>
<paramdef>GLenum <parameter>texture</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>texture</parameter></term>
<listitem>
<para>
Specifies which texture unit to make active. The number
of texture units is implementation dependent, but must be at least
two. <parameter>texture</parameter> must be one of
<constant>GL_TEXTURE</constant><inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
where
i ranges from 0 to the larger of (<constant>GL_MAX_TEXTURE_COORDS</constant> - 1)
and (<constant>GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS</constant> - 1).
The initial value is <constant>GL_TEXTURE0</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glActiveTexture</function> selects which texture unit subsequent texture state calls will
affect. The number of texture units an implementation supports is
implementation dependent, but must be at least 2.
</para>
<para>
Vertex arrays are client-side GL resources, which are selected by the
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry> routine.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glActiveTexture</function> is only supported if the GL version is 1.3 or greater, or if
<code>ARB_multitexture</code> is included in the string returned by
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry> when called with the argument <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>texture</parameter> is not one of
<constant>GL_TEXTURE</constant><inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
where i ranges from 0 to the larger of (<constant>GL_MAX_TEXTURE_COORDS</constant> - 1)
and (<constant>GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS</constant> - 1).
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACTIVE_TEXTURE</constant>, <constant>GL_MAX_TEXTURE_COORDS</constant>, or <constant>GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

210
Source/Bind/Specifications/Docs/glAlphaFunc.xml Normal file
View file

@ -0,0 +1,210 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glAlphaFunc">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glAlphaFunc</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glAlphaFunc</refname>
<refpurpose>specify the alpha test function</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glAlphaFunc</function></funcdef>
<paramdef>GLenum <parameter>func</parameter></paramdef>
<paramdef>GLclampf <parameter>ref</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>func</parameter></term>
<listitem>
<para>
Specifies the alpha comparison function.
Symbolic constants
<constant>GL_NEVER</constant>,
<constant>GL_LESS</constant>,
<constant>GL_EQUAL</constant>,
<constant>GL_LEQUAL</constant>,
<constant>GL_GREATER</constant>,
<constant>GL_NOTEQUAL</constant>,
<constant>GL_GEQUAL</constant>, and
<constant>GL_ALWAYS</constant> are accepted. The initial value is <constant>GL_ALWAYS</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ref</parameter></term>
<listitem>
<para>
Specifies the reference value that incoming alpha values are compared to.
This value is clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
where 0 represents the lowest possible alpha value
and 1 the highest possible value.
The initial reference value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The alpha test discards fragments depending on the outcome of a comparison
between an incoming fragment's alpha value and a constant reference value.
<function>glAlphaFunc</function> specifies the reference value and the comparison function.
The comparison is performed only if alpha testing is enabled. By
default, it is not enabled.
(See
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> of <constant>GL_ALPHA_TEST</constant>.)
</para>
<para>
<parameter>func</parameter> and <parameter>ref</parameter> specify the conditions under which
the pixel is drawn.
The incoming alpha value is compared to <parameter>ref</parameter>
using the function specified by <parameter>func</parameter>.
If the value passes the comparison,
the incoming fragment is drawn
if it also passes subsequent stencil and depth buffer tests.
If the value fails the comparison,
no change is made to the frame buffer at that pixel location. The
comparison functions are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_NEVER</constant></term>
<listitem>
<para>
Never passes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LESS</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is less than the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_EQUAL</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is equal to the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is less than or equal to the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_GREATER</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is greater than the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_NOTEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is not equal to the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_GEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming alpha value is greater than or equal to
the reference value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_ALWAYS</constant></term>
<listitem>
<para>
Always passes (initial value).
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<function>glAlphaFunc</function> operates on all pixel write operations,
including those resulting from the scan conversion of points,
lines,
polygons,
and bitmaps,
and from pixel draw and copy operations.
<function>glAlphaFunc</function> does not affect screen clear operations.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Alpha testing is performed only in RGBA mode.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>func</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glAlphaFunc</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ALPHA_TEST_FUNC</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ALPHA_TEST_REF</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_ALPHA_TEST</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

145
Source/Bind/Specifications/Docs/glAreTexturesResident.xml Normal file
View file

@ -0,0 +1,145 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glAreTexturesResident">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glAreTexturesResident</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glAreTexturesResident</refname>
<refpurpose>determine if textures are loaded in texture memory</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>GLboolean <function>glAreTexturesResident</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLuint * <parameter>textures</parameter></paramdef>
<paramdef>GLboolean * <parameter>residences</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of textures to be queried.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>textures</parameter></term>
<listitem>
<para>
Specifies an array containing the names of the textures to be queried.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>residences</parameter></term>
<listitem>
<para>
Specifies an array in which the texture residence status is returned.
The residence status of a texture named by an element of <parameter>textures</parameter> is
returned in the corresponding element of <parameter>residences</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
GL establishes
a ``working set'' of textures that are resident in texture memory.
These textures can be bound to a texture target much more efficiently
than textures that are not resident.
</para>
<para>
<function>glAreTexturesResident</function> queries the texture residence status of the <parameter>n</parameter> textures named by
the elements of <parameter>textures</parameter>.
If all the named textures are resident,
<function>glAreTexturesResident</function> returns <constant>GL_TRUE</constant>,
and the contents of <parameter>residences</parameter> are undisturbed.
If not all the named textures are resident, <function>glAreTexturesResident</function> returns <constant>GL_FALSE</constant>,
and detailed status is returned in the <parameter>n</parameter> elements of <parameter>residences</parameter>.
If an element of <parameter>residences</parameter> is <constant>GL_TRUE</constant>, then the texture named by
the corresponding element of <parameter>textures</parameter> is resident.
</para>
<para>
The residence status of a single bound texture may also be queried
by calling
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry> with the <emphasis>target</emphasis> argument set to the
target to which the texture is bound, and the <emphasis>pname</emphasis> argument
set to <constant>GL_TEXTURE_RESIDENT</constant>.
This is the only way that the residence status of a default texture can be
queried.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glAreTexturesResident</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<function>glAreTexturesResident</function> returns the residency status of the textures at the time of
invocation. It does not guarantee that the textures will remain
resident at any other time.
</para>
<para>
If textures reside in virtual memory (there is no texture memory), they
are considered always resident.
</para>
<para>
Some implementations may not load a texture until the first use of
that texture.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if any element in <parameter>textures</parameter>
is 0 or does not name a texture. In that case, the function returns
<constant>GL_FALSE</constant> and the contents of <parameter>residences</parameter> is indeterminate.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glAreTexturesResident</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry> with parameter name <constant>GL_TEXTURE_RESIDENT</constant>
retrieves the residence status of a currently bound texture.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPrioritizeTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

113
Source/Bind/Specifications/Docs/glArrayElement.xml Normal file
View file

@ -0,0 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glArrayElement">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glArrayElement</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glArrayElement</refname>
<refpurpose>render a vertex using the specified vertex array element</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glArrayElement</function></funcdef>
<paramdef>GLint <parameter>i</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>i</parameter></term>
<listitem>
<para>
Specifies an index into the enabled vertex data arrays.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glArrayElement</function> commands are used within <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>/<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> pairs to
specify vertex and attribute data for point, line, and polygon
primitives. If <constant>GL_VERTEX_ARRAY</constant> is enabled when <function>glArrayElement</function> is called, a
single vertex is drawn, using
vertex and attribute data taken from location <parameter>i</parameter> of the enabled
arrays. If <constant>GL_VERTEX_ARRAY</constant> is not enabled, no drawing occurs but
the attributes corresponding to the enabled arrays are modified.
</para>
<para>
Use <function>glArrayElement</function> to construct primitives by indexing vertex data, rather than
by streaming through arrays of data in first-to-last order. Because
each call specifies only a single vertex, it is possible to explicitly
specify per-primitive attributes such as a single normal for each
triangle.
</para>
<para>
Changes made to array data between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the
corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> may affect calls to <function>glArrayElement</function> that are made
within the same <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>/<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> period in nonsequential ways.
That is, a call to
<function>glArrayElement</function> that precedes a change to array data may
access the changed data, and a call that follows a change to array data
may access original data.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glArrayElement</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<function>glArrayElement</function> is included in display lists. If <function>glArrayElement</function> is entered into a
display list, the necessary array data (determined by the array
pointers and enables) is also entered into the display list. Because
the array pointers and enables are client-side state, their values
affect display lists when the lists are created, not when the lists
are executed.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if <parameter>i</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an
enabled array and the buffer object's data store is currently mapped.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

115
Source/Bind/Specifications/Docs/glAttachShader.xml Normal file
View file

@ -0,0 +1,115 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glAttachShader">
<refmeta>
<refentrytitle>glAttachShader</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glAttachShader</refname>
<refpurpose>Attaches a shader object to a program object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glAttachShader</function></funcdef>
<paramdef>GLuint <parameter>program</parameter></paramdef>
<paramdef>GLuint <parameter>shader</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>program</parameter></term>
<listitem>
<para>Specifies the program object to which a shader
object will be attached.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>shader</parameter></term>
<listitem>
<para>Specifies the shader object that is to be attached.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>In order to create an executable, there must be a way to
specify the list of things that will be linked together. Program
objects provide this mechanism. Shaders that are to be linked
together in a program object must first be attached to that
program object. <function>glAttachShader</function> attaches the
shader object specified by <parameter>shader</parameter> to the
program object specified by <parameter>program</parameter>. This
indicates that <parameter>shader</parameter> will be included in
link operations that will be performed on
<parameter>program</parameter>.</para>
<para>All operations that can be performed on a shader object
are valid whether or not the shader object is attached to a
program object. It is permissible to attach a shader object to a
program object before source code has been loaded into the
shader object or before the shader object has been compiled. It
is permissible to attach multiple shader objects of the same
type because each may contain a portion of the complete shader.
It is also permissible to attach a shader object to more than
one program object. If a shader object is deleted while it is
attached to a program object, it will be flagged for deletion,
and deletion will not occur until
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>
is called to detach it from all program objects to which it is
attached.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glAttachShader</function>
is available only if the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if either
<parameter>program</parameter> or <parameter>shader</parameter>
is not a value generated by OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>program</parameter> is not a program object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>shader</parameter> is not a shader object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>shader</parameter> is already attached to
<parameter>program</parameter>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glAttachShader</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
with the handle of a valid program object</para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glShaderSource</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

619
Source/Bind/Specifications/Docs/glBegin.xml Normal file
View file

@ -0,0 +1,619 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBegin">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBegin</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBegin</refname>
<refpurpose>delimit the vertices of a primitive or a group of like primitives</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBegin</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies the primitive or primitives that will be created from vertices
presented between <function>glBegin</function> and the subsequent <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
Ten symbolic constants are accepted:
<constant>GL_POINTS</constant>,
<constant>GL_LINES</constant>,
<constant>GL_LINE_STRIP</constant>,
<constant>GL_LINE_LOOP</constant>,
<constant>GL_TRIANGLES</constant>,
<constant>GL_TRIANGLE_STRIP</constant>,
<constant>GL_TRIANGLE_FAN</constant>,
<constant>GL_QUADS</constant>,
<constant>GL_QUAD_STRIP</constant>, and
<constant>GL_POLYGON</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEnd</function></funcdef>
<paramdef><parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBegin</function> and <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> delimit the vertices that define a primitive or
a group of like primitives.
<function>glBegin</function> accepts a single argument that specifies in which of ten ways the
vertices are interpreted.
Taking
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
as an integer count starting at one,
and
<inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>
as the total number of vertices specified,
the interpretations are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_POINTS</constant></term>
<listitem>
<para>
Treats each vertex as a single point.
Vertex
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
defines point
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>
points are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LINES</constant></term>
<listitem>
<para>
Treats each pair of vertices as an independent line segment.
Vertices
<inlineequation><mml:math>
<!-- eqn: 2n - 1:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: 2n:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
define line
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N/2:-->
<mml:mfrac>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mn>2</mml:mn>
</mml:mfrac>
</mml:math></inlineequation>
lines are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LINE_STRIP</constant></term>
<listitem>
<para>
Draws a connected group of line segments from the first vertex
to the last.
Vertices
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: n + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define line
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
lines are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LINE_LOOP</constant></term>
<listitem>
<para>
Draws a connected group of line segments from the first vertex
to the last,
then back to the first.
Vertices
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: n + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define line
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
The last line, however, is defined by vertices
<inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: 1:-->
<mml:mn>1</mml:mn>
</mml:math></inlineequation>.
<inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>
lines are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_TRIANGLES</constant></term>
<listitem>
<para>
Treats each triplet of vertices as an independent triangle.
Vertices
<inlineequation><mml:math>
<!-- eqn: 3n - 2:-->
<mml:mrow>
<mml:mn>3</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: 3n - 1:-->
<mml:mrow>
<mml:mn>3</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: 3n:-->
<mml:mrow>
<mml:mn>3</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
define triangle
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N/3:-->
<mml:mfrac>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mn>3</mml:mn>
</mml:mfrac>
</mml:math></inlineequation>
triangles are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_TRIANGLE_STRIP</constant></term>
<listitem>
<para>
Draws a connected group of triangles. One triangle is defined for each
vertex presented after the first two vertices. For odd
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
vertices
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: n + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: n + 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define triangle
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
For even
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
vertices
<inlineequation><mml:math>
<!-- eqn: n + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: n + 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define triangle
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N - 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
triangles are
drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_TRIANGLE_FAN</constant></term>
<listitem>
<para>
Draws a connected group of triangles.
One triangle is defined for each vertex presented after the first two vertices.
Vertices
<inlineequation><mml:math>
<!-- eqn: 1:-->
<mml:mn>1</mml:mn>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: n + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: n + 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define triangle
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N - 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
triangles are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_QUADS</constant></term>
<listitem>
<para>
Treats each group of four vertices as an independent quadrilateral.
Vertices
<inlineequation><mml:math>
<!-- eqn: 4n - 3:-->
<mml:mrow>
<mml:mn>4</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>3</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: 4n - 2:-->
<mml:mrow>
<mml:mn>4</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: 4n - 1:-->
<mml:mrow>
<mml:mn>4</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: 4n:-->
<mml:mrow>
<mml:mn>4</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
define quadrilateral
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N/4:-->
<mml:mfrac>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mn>4</mml:mn>
</mml:mfrac>
</mml:math></inlineequation>
quadrilaterals are drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_QUAD_STRIP</constant></term>
<listitem>
<para>
Draws a connected group of quadrilaterals.
One quadrilateral is defined for each pair of vertices presented
after the first pair.
Vertices
<inlineequation><mml:math>
<!-- eqn: 2n - 1:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: 2n:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: 2n + 2:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>2</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: 2n + 1:-->
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
define quadrilateral
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
<inlineequation><mml:math>
<!-- eqn: N/2 - 1:-->
<mml:mrow>
<mml:mfrac>
<mml:mi mathvariant="italic">N</mml:mi>
<mml:mn>2</mml:mn>
</mml:mfrac>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
quadrilaterals are drawn.
Note that the order in which vertices are used to construct a quadrilateral
from strip data is different from that used with independent data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_POLYGON</constant></term>
<listitem>
<para>
Draws a single,
convex polygon.
Vertices
<inlineequation><mml:math>
<!-- eqn: 1:-->
<mml:mn>1</mml:mn>
</mml:math></inlineequation>
through
<inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>
define this polygon.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Only a subset of GL commands can be used between <function>glBegin</function> and <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
The commands are
<citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormal</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>.
Also,
it is acceptable to use
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry> to execute
display lists that include only the preceding commands.
If any other GL command is executed between <function>glBegin</function> and <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
the error flag is set and the command is ignored.
</para>
<para>
Regardless of the value chosen for <parameter>mode</parameter>,
there is no limit to the number of vertices that can be defined
between <function>glBegin</function> and <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
Lines,
triangles,
quadrilaterals,
and polygons that are incompletely specified are not drawn.
Incomplete specification results when either too few vertices are
provided to specify even a single primitive or when an incorrect multiple
of vertices is specified. The incomplete primitive is ignored; the rest are drawn.
</para>
<para>
The minimum specification of vertices
for each primitive is as follows:
1 for a point,
2 for a line,
3 for a triangle,
4 for a quadrilateral,
and 3 for a polygon.
Modes that require a certain multiple of vertices are
<constant>GL_LINES</constant> (2),
<constant>GL_TRIANGLES</constant> (3),
<constant>GL_QUADS</constant> (4),
and <constant>GL_QUAD_STRIP</constant> (2).
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is set to an unaccepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBegin</function> is executed between a
<function>glBegin</function>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> is executed without being
preceded by a <function>glBegin</function>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a command other than
<citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormal</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry> is executed between
the execution of <function>glBegin</function> and the corresponding
execution <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Execution of
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> is not allowed after a call to <function>glBegin</function> and before
the corresponding call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
but an error may or may not be generated.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormal</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

154
Source/Bind/Specifications/Docs/glBeginQuery.xml Normal file
View file

@ -0,0 +1,154 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBeginQuery">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBeginQuery</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBeginQuery</refname>
<refpurpose>delimit the boundaries of a query object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBeginQuery</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLuint <parameter>id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target type of query object established between
<function>glBeginQuery</function> and the subsequent <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>.
The symbolic constant must be <constant>GL_SAMPLES_PASSED</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem>
<para>
Specifies the name of a query object.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEndQuery</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target type of query object to be concluded.
The symbolic constant must be <constant>GL_SAMPLES_PASSED</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBeginQuery</function> and <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry> delimit the
boundaries of a query object. If a query object with name <parameter>id</parameter> does not yet exist it is created.
</para>
<para>
When <function>glBeginQuery</function> is executed, the query object's samples-passed counter is reset to 0. Subsequent
rendering will increment the counter once for every sample that passes the depth test. When <function>glEndQuery</function>
is executed, the samples-passed counter is assigned to the query object's result value. This value can be queried by
calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
<constant>GL_QUERY_RESULT</constant>.
</para>
<para>
Querying the <constant>GL_QUERY_RESULT</constant> implicitly flushes the GL pipeline until the rendering delimited by the
query object has completed and the result is available. <constant>GL_QUERY_RESULT_AVAILABLE</constant> can be queried to
determine if the result is immediately available or if the rendering is not yet complete.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
If the samples-passed count exceeds the maximum value representable in the number of available bits, as reported by
<citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry> with <parameter>pname</parameter>
<constant>GL_QUERY_COUNTER_BITS</constant>, the count becomes undefined.
</para>
<para>
An implementation may support 0 bits in its samples-passed counter, in which case query results are always undefined
and essentially useless.
</para>
<para>
When <constant>GL_SAMPLE_BUFFERS</constant> is 0, the samples-passed counter will increment once for each fragment that passes
the depth test. When <constant>GL_SAMPLE_BUFFERS</constant> is 1, an implementation may either increment the samples-passed
counter individually for each sample of a fragment that passes the depth test, or it may choose to increment the counter for
all samples of a fragment if any one of them passes the depth test.
</para>
<para>
<function>glBeginQuery</function> and <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>
are available only if the GL version is 1.5 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_SAMPLES_PASSED</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginQuery</function> is executed while
a query object of the same <parameter>target</parameter> is already active.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>
is executed when a query object of the same <parameter>target</parameter> is not active.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is 0.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of an already active query object.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginQuery</function> or
<citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry> is executed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIsQuery</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

196
Source/Bind/Specifications/Docs/glBindAttribLocation.xml Normal file
View file

@ -0,0 +1,196 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBindAttribLocation">
<refmeta>
<refentrytitle>glBindAttribLocation</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBindAttribLocation</refname>
<refpurpose>Associates a generic vertex attribute index with a named attribute variable</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBindAttribLocation</function></funcdef>
<paramdef>GLuint <parameter>program</parameter></paramdef>
<paramdef>GLuint <parameter>index</parameter></paramdef>
<paramdef>const GLchar *<parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>program</parameter></term>
<listitem>
<para>Specifies the handle of the program object in
which the association is to be made.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>index</parameter></term>
<listitem>
<para>Specifies the index of the generic vertex
attribute to be bound.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>Specifies a null terminated string containing
the name of the vertex shader attribute variable to
which <parameter>index</parameter> is to be
bound.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glBindAttribLocation</function> is used to
associate a user-defined attribute variable in the program
object specified by <parameter>program</parameter> with a
generic vertex attribute index. The name of the user-defined
attribute variable is passed as a null terminated string in
<parameter>name</parameter>. The generic vertex attribute index
to be bound to this variable is specified by
<parameter>index</parameter>. When
<parameter>program</parameter> is made part of current state,
values provided via the generic vertex attribute
<parameter>index</parameter> will modify the value of the
user-defined attribute variable specified by
<parameter>name</parameter>.</para>
<para>If <parameter>name</parameter> refers to a matrix
attribute variable, <parameter>index</parameter> refers to the
first column of the matrix. Other matrix columns are then
automatically bound to locations <parameter>index+1</parameter>
for a matrix of type mat2; <parameter>index+1</parameter> and
<parameter>index+2</parameter> for a matrix of type mat3; and
<parameter>index+1</parameter>, <parameter>index+2</parameter>,
and <parameter>index+3</parameter> for a matrix of type
mat4.</para>
<para>This command makes it possible for vertex shaders to use
descriptive names for attribute variables rather than generic
variables that are numbered from 0 to
<constant>GL_MAX_VERTEX_ATTRIBS</constant> -1. The values sent
to each generic attribute index are part of current state, just
like standard vertex attributes such as color, normal, and
vertex position. If a different program object is made current
by calling
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
the generic vertex attributes are tracked in such a way that the
same values will be observed by attributes in the new program
object that are also bound to
<parameter>index</parameter>.</para> <para>Attribute variable
name-to-generic attribute index bindings for a program object
can be explicitly assigned at any time by calling
<function>glBindAttribLocation</function>. Attribute bindings do
not go into effect until
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
is called. After a program object has been linked successfully,
the index values for generic attributes remain fixed (and their
values can be queried) until the next link command
occurs.</para>
<para>Applications are not allowed to bind any of the standard
OpenGL vertex attributes using this command, as they are bound
automatically when needed. Any attribute binding that occurs
after the program object has been linked will not take effect
until the next time the program object is linked.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glBindAttribLocation</function> is available
only if the GL version is 2.0 or greater.</para>
<para><function>glBindAttribLocation</function> can be called
before any vertex shader objects are bound to the specified
program object. It is also permissible to bind a generic
attribute index to an attribute variable name that is never used
in a vertex shader.</para>
<para>If <parameter>name</parameter> was bound previously, that
information is lost. Thus you cannot bind one user-defined
attribute variable to multiple indices, but you can bind
multiple user-defined attribute variables to the same
index.</para>
<para>Applications are allowed to bind more than one
user-defined attribute variable to the same generic vertex
attribute index. This is called <emphasis>aliasing</emphasis>,
and it is allowed only if just one of the aliased attributes is
active in the executable program, or if no path through the
shader consumes more than one attribute of a set of attributes
aliased to the same location. The compiler and linker are
allowed to assume that no aliasing is done and are free to
employ optimizations that work only in the absence of aliasing.
OpenGL implementations are not required to do error checking to
detect aliasing. Because there is no way to bind standard
attributes, it is not possible to alias generic attributes with
conventional ones (except for generic attribute 0).</para>
<para>Active attributes that are not explicitly bound will be
bound by the linker when
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
is called. The locations assigned can be queried by calling
<citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>.</para>
<para>OpenGL copies the <parameter>name</parameter> string when
<function>glBindAttribLocation</function> is called, so an
application may free its copy of the <parameter>name</parameter>
string immediately after the function returns.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>index</parameter> is greater than or equal to
<constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>name</parameter> starts with the reserved prefix
&quot;gl_&quot;.</para>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>program</parameter> is not a value generated by
OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>program</parameter> is not a program object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glBindAttribLocation</function> is executed between
the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
<para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
with argument <parameter>program</parameter></para>
<para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and
<parameter>name</parameter></para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

206
Source/Bind/Specifications/Docs/glBindBuffer.xml Normal file
View file

@ -0,0 +1,206 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBindBuffer">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBindBuffer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBindBuffer</refname>
<refpurpose>bind a named buffer object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBindBuffer</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLuint <parameter>buffer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target to which the buffer object is bound.
The symbolic constant must be
<constant>GL_ARRAY_BUFFER</constant>,
<constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
<constant>GL_PIXEL_PACK_BUFFER</constant>, or
<constant>GL_PIXEL_UNPACK_BUFFER</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
Specifies the name of a buffer object.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBindBuffer</function> lets you create or use a named buffer object. Calling <function>glBindBuffer</function> with
<parameter>target</parameter> set to
<constant>GL_ARRAY_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>, <constant>GL_PIXEL_PACK_BUFFER</constant> or
<constant>GL_PIXEL_UNPACK_BUFFER</constant> and <parameter>buffer</parameter> set to the name
of the new buffer object binds the buffer object name to the target.
When a buffer object is bound to a target, the previous binding for that
target is automatically broken.
</para>
<para>
Buffer object names are unsigned integers. The value zero is reserved, but
there is no default buffer object for each buffer object target. Instead, <parameter>buffer</parameter> set to zero
effectively unbinds any buffer object previously bound, and restores client memory usage for that buffer object target.
Buffer object names and the corresponding buffer object contents are local to
the shared display-list space (see <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>) of the current
GL rendering context;
two rendering contexts share buffer object names only if they
also share display lists.
</para>
<para>
You may use <citerefentry><refentrytitle>glGenBuffers</refentrytitle></citerefentry> to generate a set of new buffer object names.
</para>
<para>
The state of a buffer object immediately after it is first bound is an unmapped zero-sized memory buffer with
<constant>GL_READ_WRITE</constant> access and <constant>GL_STATIC_DRAW</constant> usage.
</para>
<para>
While a non-zero buffer object name is bound, GL operations on the target to which it is
bound affect the bound buffer object, and queries of the target to which it is bound return state
from the bound buffer object. While buffer object name zero is bound, as in the initial state,
attempts to modify or query state on the target to which it is bound generates an
<constant>GL_INVALID_OPERATION</constant> error.
</para>
<para>
When vertex array pointer state is changed, for example by a call to
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
the current buffer object binding (<constant>GL_ARRAY_BUFFER_BINDING</constant>) is copied into the
corresponding client state for the vertex array type being changed, for example
<constant>GL_NORMAL_ARRAY_BUFFER_BINDING</constant>. While a non-zero buffer object is bound to the
<constant>GL_ARRAY_BUFFER</constant> target, the vertex array pointer parameter that is traditionally
interpreted as a pointer to client-side memory is instead interpreted as an offset within the
buffer object measured in basic machine units.
</para>
<para>
While a non-zero buffer object is bound to the <constant>GL_ELEMENT_ARRAY_BUFFER</constant> target,
the indices parameter of <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> that is traditionally
interpreted as a pointer to client-side memory is instead interpreted as an offset within the
buffer object measured in basic machine units.
</para>
<para>
While a non-zero buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target,
the following commands are affected: <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetHistogram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetMinmax</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPixelMap</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPolygonStipple</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetSeparableFilter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>. The pointer parameter that is
traditionally interpreted as a pointer to client-side memory where the pixels are to be packed is instead
interpreted as an offset within the buffer object measured in basic machine units.
</para>
<para>
While a non-zero buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target,
the following commands are affected: <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorSubTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPolygonStipple</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>. The pointer parameter that is
traditionally interpreted as a pointer to client-side memory from which the pixels are to be unpacked is
instead interpreted as an offset within the buffer object measured in basic machine units.
</para>
<para>
A buffer object binding created with <function>glBindBuffer</function> remains active until a different
buffer object name is bound to the same target, or until the bound buffer object is
deleted with <citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry>.
</para>
<para>
Once created, a named buffer object may be re-bound to any target as often as needed. However,
the GL implementation may make choices about how to optimize the storage of a buffer object based
on its initial binding target.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBindBuffer</function> is available only if the GL version is 1.5 or greater.
</para>
<para>
<constant>GL_PIXEL_PACK_BUFFER</constant> and <constant>GL_PIXEL_UNPACK_BUFFER</constant> are
available only if the GL version is 2.1 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBindBuffer</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ELEMENT_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIsBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

168
Source/Bind/Specifications/Docs/glBindTexture.xml Normal file
View file

@ -0,0 +1,168 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBindTexture">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBindTexture</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBindTexture</refname>
<refpurpose>bind a named texture to a texturing target</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBindTexture</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLuint <parameter>texture</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target to which the texture is bound.
Must be either
<constant>GL_TEXTURE_1D</constant>,
<constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_3D</constant>, or
<constant>GL_TEXTURE_CUBE_MAP</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>texture</parameter></term>
<listitem>
<para>
Specifies the name of a texture.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBindTexture</function> lets you create or use a named texture. Calling <function>glBindTexture</function> with
<parameter>target</parameter> set to
<constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant> or
<constant>GL_TEXTURE_CUBE_MAP</constant> and <parameter>texture</parameter> set to the name
of the new texture binds the texture name to the target.
When a texture is bound to a target, the previous binding for that
target is automatically broken.
</para>
<para>
Texture names are unsigned integers. The value zero is reserved to
represent the default texture for each texture target.
Texture names and the corresponding texture contents are local to
the shared display-list space (see <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>) of the current
GL rendering context;
two rendering contexts share texture names only if they
also share display lists.
</para>
<para>
You may use <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry> to generate a set of new texture names.
</para>
<para>
When a texture is first bound, it assumes the specified target:
A texture first bound to <constant>GL_TEXTURE_1D</constant> becomes one-dimensional texture, a
texture first bound to <constant>GL_TEXTURE_2D</constant> becomes two-dimensional texture, a
texture first bound to <constant>GL_TEXTURE_3D</constant> becomes three-dimensional texture, and a
texture first bound to <constant>GL_TEXTURE_CUBE_MAP</constant>
becomes a cube-mapped texture. The state of a one-dimensional texture
immediately after it is first bound is equivalent to the state of the
default <constant>GL_TEXTURE_1D</constant> at GL initialization, and similarly for two-
and three-dimensional textures and cube-mapped textures.
</para>
<para>
While a texture is bound, GL operations on the target to which it is
bound affect the bound texture, and queries of the target to which it
is bound return state from the bound texture. If texture mapping is active
on the target to which a texture is bound, the bound texture is used.
In effect, the texture targets become aliases for the textures currently
bound to them, and the texture name zero refers to the default textures
that were bound to them at initialization.
</para>
<para>
A texture binding created with <function>glBindTexture</function> remains active until a different
texture is bound to the same target, or until the bound texture is
deleted with <citerefentry><refentrytitle>glDeleteTextures</refentrytitle></citerefentry>.
</para>
<para>
Once created, a named texture may be re-bound to its same original target as often as needed.
It is usually much faster to use <function>glBindTexture</function> to bind an existing named
texture to one of the texture targets than it is to reload the texture image
using <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>.
For additional control over performance, use
<citerefentry><refentrytitle>glPrioritizeTextures</refentrytitle></citerefentry>.
</para>
<para>
<function>glBindTexture</function> is included in display lists.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBindTexture</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<constant>GL_TEXTURE_CUBE_MAP</constant> is available only if the GL version is 1.3 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> was previously created with a target
that doesn't match that of <parameter>target</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBindTexture</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_BINDING_1D</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_BINDING_2D</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_BINDING_3D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glAreTexturesResident</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIsTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPrioritizeTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

276
Source/Bind/Specifications/Docs/glBitmap.xml Normal file
View file

@ -0,0 +1,276 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBitmap">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBitmap</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBitmap</refname>
<refpurpose>draw a bitmap</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBitmap</function></funcdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLfloat <parameter>xorig</parameter></paramdef>
<paramdef>GLfloat <parameter>yorig</parameter></paramdef>
<paramdef>GLfloat <parameter>xmove</parameter></paramdef>
<paramdef>GLfloat <parameter>ymove</parameter></paramdef>
<paramdef>const GLubyte * <parameter>bitmap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>width</parameter></term>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specify the pixel width and height of the bitmap image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xorig</parameter></term>
<term><parameter>yorig</parameter></term>
<listitem>
<para>
Specify the location of the origin in the bitmap image.
The origin is measured from the lower left corner of the bitmap,
with right and up being the positive axes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xmove</parameter></term>
<term><parameter>ymove</parameter></term>
<listitem>
<para>
Specify the <emphasis>x</emphasis> and <emphasis>y</emphasis> offsets to be added to the current raster position
after the bitmap is drawn.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bitmap</parameter></term>
<listitem>
<para>
Specifies the address of the bitmap image.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
A bitmap is a binary image.
When drawn,
the bitmap is positioned relative to the current raster position,
and frame buffer pixels corresponding to 1's in the bitmap are
written using the current raster color or index.
Frame buffer pixels corresponding to 0's in the bitmap are not modified.
</para>
<para>
<function>glBitmap</function> takes seven arguments.
The first pair specifies the width and height of the bitmap image.
The second pair specifies the location of the bitmap origin relative
to the lower left corner of the bitmap image.
The third pair of arguments specifies <emphasis>x</emphasis> and <emphasis>y</emphasis> offsets to be added
to the current raster position after the bitmap has been drawn.
The final argument is a pointer to the bitmap image itself.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a bitmap image is
specified, <parameter>bitmap</parameter> is treated as a byte offset into the buffer object's data store.
</para>
<para>
The bitmap image is interpreted like image data for the <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>
command,
with <parameter>width</parameter> and <parameter>height</parameter> corresponding to the width and height arguments
of that command,
and with <emphasis>type</emphasis> set to <constant>GL_BITMAP</constant>
and <emphasis>format</emphasis> set to <constant>GL_COLOR_INDEX</constant>.
Modes specified using <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> affect the
interpretation of bitmap image data;
modes specified using <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> do not.
</para>
<para>
If the current raster position is invalid, <function>glBitmap</function> is ignored.
Otherwise,
the lower left corner of the bitmap image is positioned at the window coordinates
</para>
<para>
<inlineequation><mml:math>
<!-- eqn: x sub w = \(lf x sub r - x sub o \(rf:-->
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">w</mml:mi>
</mml:msub>
<mml:mo>=</mml:mo>
<mml:mfenced open="&LeftFloor;" close="&RightFloor;">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">o</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>
</para>
<para>
<inlineequation><mml:math>
<!-- eqn: y sub w = \(lf y sub r - y sub o \(rf:-->
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">w</mml:mi>
</mml:msub>
<mml:mo>=</mml:mo>
<mml:mfenced open="&LeftFloor;" close="&RightFloor;">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">o</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>
</para>
<para>
where
<inlineequation><mml:math>
<!-- eqn: ( x sub r , y sub r ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the raster position
and
<inlineequation><mml:math>
<!-- eqn: ( x sub o , y sub o ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">o</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">o</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the bitmap origin.
Fragments are then generated for each pixel corresponding to a 1 (one)
in the bitmap image.
These fragments are generated using the current raster <emphasis>z</emphasis> coordinate,
color or color index, and current raster texture coordinates.
They are then treated just as if they had been generated
by a point, line, or polygon,
including texture mapping,
fogging,
and all per-fragment operations such as alpha and depth testing.
</para>
<para>
After the bitmap has been drawn,
the <emphasis>x</emphasis> and <emphasis>y</emphasis> coordinates of the current raster position are offset by
<parameter>xmove</parameter> and <parameter>ymove</parameter>.
No change is made to the <emphasis>z</emphasis> coordinate of the current raster position,
or to the current raster color, texture coordinates, or index.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
To set a valid raster position outside the viewport, first set a valid
raster position inside the viewport, then call <function>glBitmap</function> with NULL
as the <parameter>bitmap</parameter> parameter and with <parameter>xmove</parameter> and <parameter>ymove</parameter> set to
the offsets of the new raster position. This technique is useful when
panning an image around the viewport.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>height</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBitmap</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_COLOR</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_SECONDARY_COLOR</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_DISTANCE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_INDEX</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_TEXTURE_COORDS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

98
Source/Bind/Specifications/Docs/glBlendColor.xml Normal file
View file

@ -0,0 +1,98 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBlendColor">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBlendColor</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBlendColor</refname>
<refpurpose>set the blend color</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBlendColor</function></funcdef>
<paramdef>GLclampf <parameter>red</parameter></paramdef>
<paramdef>GLclampf <parameter>green</parameter></paramdef>
<paramdef>GLclampf <parameter>blue</parameter></paramdef>
<paramdef>GLclampf <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>red</parameter></term>
<term><parameter>green</parameter></term>
<term><parameter>blue</parameter></term>
<term><parameter>alpha</parameter></term>
<listitem>
<para>
specify the components of <constant>GL_BLEND_COLOR</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The <constant>GL_BLEND_COLOR</constant> may be used to calculate the source and destination
blending factors. The color components are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
before being stored. See <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry> for a complete description of the
blending operations.
Initially the <constant>GL_BLEND_COLOR</constant> is set to (0, 0, 0, 0).
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBlendColor</function> is part of the <code>ARB_imaging</code> subset. <function>glBlendColor</function> is present only
if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry> is called with
<constant>GL_EXTENSIONS</constant> as its argument.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBlendColor</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with an argument of <constant>GL_BLEND_COLOR</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBlendEquation</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

849
Source/Bind/Specifications/Docs/glBlendEquation.xml Normal file
View file

@ -0,0 +1,849 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBlendEquation">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBlendEquation</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBlendEquation</refname>
<refpurpose>specify the equation used for both the RGB blend equation and the Alpha blend equation</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBlendEquation</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
specifies how source and destination colors are combined.
It must be <constant>GL_FUNC_ADD</constant>, <constant>GL_FUNC_SUBTRACT</constant>,
<constant>GL_FUNC_REVERSE_SUBTRACT</constant>, <constant>GL_MIN</constant>, <constant>GL_MAX</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The blend equations determine how a new pixel (the ''source'' color)
is combined with a pixel already in the framebuffer (the ''destination''
color). This function sets both the RGB blend equation and the alpha
blend equation to a single equation.
</para>
<para>
These equations use the source and destination blend factors
specified by either <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>.
See <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>
for a description of the various blend factors.
</para>
<para>
In the equations that follow, source and destination
color components are referred to as
<inlineequation><mml:math>
<!-- eqn: ( R sub s, G sub s, B sub s, A sub s ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: ( R sub d, G sub d, B sub d, A sub d ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>,
respectively.
The result color is referred to as
<inlineequation><mml:math>
<!-- eqn: ( R sub r, G sub r, B sub r, A sub r ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>.
The source and destination blend factors are denoted
<inlineequation><mml:math>
<!-- eqn: ( s sub R, s sub G, s sub B, s sub A ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: ( d sub R, d sub G, d sub B, d sub A ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>,
respectively.
For these equations all color components are understood to have values
in the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
<informaltable frame="topbot">
<tgroup cols="3" align="left">
<colspec colwidth="1.1*" />
<colspec colwidth="1*" />
<colspec colwidth="1*" />
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Mode
</emphasis></entry>
<entry rowsep="1" align="left"><emphasis role="bold">
RGB Components
</emphasis></entry>
<entry rowsep="1" align="left"><emphasis role="bold">
Alpha Component
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_FUNC_ADD</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = min (1, R sub s s sub R + R sub d d sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = min (1, G sub s s sub G + G sub d d sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = min (1, B sub s s sub B + B sub d d sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = min (1, A sub s s sub A + A sub d d sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_FUNC_SUBTRACT</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max (0 , R sub s s sub R - R sub d d sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max (0 , G sub s s sub G - G sub d d sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max (0 , B sub s s sub B - B sub d d sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max (0 , A sub s s sub A - A sub d d sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_FUNC_REVERSE_SUBTRACT</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max (0 , R sub d d sub R - R sub s s sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max (0 , G sub d d sub G - G sub s s sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max (0 , B sub d d sub B - B sub s s sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max (0 , A sub d d sub A - A sub s s sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_MIN</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = min ( R sub s, R sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = min ( G sub s, G sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = min ( B sub s, B sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = min ( A sub s, A sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_MAX</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max ( R sub s, R sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max ( G sub s, G sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max ( B sub s, B sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max ( A sub s, A sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The results of these equations are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
<para>
The <constant>GL_MIN</constant> and <constant>GL_MAX</constant> equations are useful for applications
that analyze image data (image thresholding against a constant color,
for example).
The <constant>GL_FUNC_ADD</constant> equation is useful
for antialiasing and transparency, among other things.
</para>
<para>
Initially, both the RGB blend equation and the alpha blend equation are set to <constant>GL_FUNC_ADD</constant>.
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
The <constant>GL_MIN</constant>, and <constant>GL_MAX</constant> equations do not use
the source or destination factors, only the source and destination colors.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not one of
<constant>GL_FUNC_ADD</constant>, <constant>GL_FUNC_SUBTRACT</constant>, <constant>GL_FUNC_REVERSE_SUBTRACT</constant>,
<constant>GL_MAX</constant>, or <constant>GL_MIN</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBlendEquation</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with an argument of <constant>GL_BLEND_EQUATION_RGB</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with an argument of <constant>GL_BLEND_EQUATION_ALPHA</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>
<citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

863
Source/Bind/Specifications/Docs/glBlendEquationSeparate.xml Normal file
View file

@ -0,0 +1,863 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBlendEquationSeparate">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBlendEquationSeparate</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBlendEquationSeparate</refname>
<refpurpose>set the RGB blend equation and the alpha blend equation separately</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBlendEquationSeparate</function></funcdef>
<paramdef>GLenum <parameter>modeRGB</parameter></paramdef>
<paramdef>GLenum <parameter>modeAlpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>modeRGB</parameter></term>
<listitem>
<para>
specifies the RGB blend equation, how the red, green, and blue components of the source and destination colors are combined.
It must be <constant>GL_FUNC_ADD</constant>, <constant>GL_FUNC_SUBTRACT</constant>,
<constant>GL_FUNC_REVERSE_SUBTRACT</constant>, <constant>GL_MIN</constant>, <constant>GL_MAX</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>modeAlpha</parameter></term>
<listitem>
<para>
specifies the alpha blend equation, how the alpha component of the source and destination colors are combined.
It must be <constant>GL_FUNC_ADD</constant>, <constant>GL_FUNC_SUBTRACT</constant>,
<constant>GL_FUNC_REVERSE_SUBTRACT</constant>, <constant>GL_MIN</constant>, <constant>GL_MAX</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The blend equations determines how a new pixel (the ''source'' color)
is combined with a pixel already in the framebuffer (the ''destination''
color). This function specifies one blend equation for the RGB-color
components and one blend equation for the alpha component.
</para>
<para>
The blend equations use the source and destination blend factors
specified by either <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>.
See <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>
for a description of the various blend factors.
</para>
<para>
In the equations that follow, source and destination
color components are referred to as
<inlineequation><mml:math>
<!-- eqn: ( R sub s, G sub s, B sub s, A sub s ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: ( R sub d, G sub d, B sub d, A sub d ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>,
respectively.
The result color is referred to as
<inlineequation><mml:math>
<!-- eqn: ( R sub r, G sub r, B sub r, A sub r ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>.
The source and destination blend factors are denoted
<inlineequation><mml:math>
<!-- eqn: ( s sub R, s sub G, s sub B, s sub A ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: ( d sub R, d sub G, d sub B, d sub A ):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>,
respectively.
For these equations all color components are understood to have values
in the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
<informaltable frame="topbot">
<tgroup cols="3" align="left">
<colspec colwidth="1.1*" />
<colspec colwidth="1*" />
<colspec colwidth="1*" />
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Mode
</emphasis></entry>
<entry rowsep="1" align="left"><emphasis role="bold">
RGB Components
</emphasis></entry>
<entry rowsep="1" align="left"><emphasis role="bold">
Alpha Component
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_FUNC_ADD</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = min (1, R sub s s sub R + R sub d d sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = min (1, G sub s s sub G + G sub d d sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = min (1, B sub s s sub B + B sub d d sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = min (1, A sub s s sub A + A sub d d sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>1</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_FUNC_SUBTRACT</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max (0 , R sub s s sub R - R sub d d sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max (0 , G sub s s sub G - G sub d d sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max (0 , B sub s s sub B - B sub d d sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max (0 , A sub s s sub A - A sub d d sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_FUNC_REVERSE_SUBTRACT</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max (0 , R sub d d sub R - R sub s s sub R ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">R</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max (0 , G sub d d sub G - G sub s s sub G ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">G</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max (0 , B sub d d sub B - B sub s s sub B ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max (0 , A sub d d sub A - A sub s s sub A ):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">d</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">s</mml:mi>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_MIN</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = min ( R sub s, R sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = min ( G sub s, G sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = min ( B sub s, B sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = min ( A sub s, A sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">min</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_MAX</constant>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Rr = max ( R sub s, R sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Rr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">R</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Gr = max ( G sub s, G sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Gr</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">G</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
<informalequation><mml:math>
<!-- eqn: Br = max ( B sub s, B sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Br</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">B</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
<entry align="left">
<informalequation><mml:math>
<!-- eqn: Ar = max ( A sub s, A sub d):-->
<mml:mrow>
<mml:mi mathvariant="italic">Ar</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">max</mml:mi>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">s</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">A</mml:mi>
<mml:mi mathvariant="italic">d</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The results of these equations are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
<para>
The <constant>GL_MIN</constant> and <constant>GL_MAX</constant> equations are useful for applications
that analyze image data (image thresholding against a constant color,
for example).
The <constant>GL_FUNC_ADD</constant> equation is useful
for antialiasing and transparency, among other things.
</para>
<para>
Initially, both the RGB blend equation and the alpha blend equation are set to <constant>GL_FUNC_ADD</constant>.
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBlendEquationSeparate</function> is available only if the GL version is 2.0 or greater.
</para>
<para>
The <constant>GL_MIN</constant>, and <constant>GL_MAX</constant> equations do not use
the source or destination factors, only the source and destination colors.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if either <parameter>modeRGB</parameter> or <parameter>modeAlpha</parameter> is not one of
<constant>GL_FUNC_ADD</constant>, <constant>GL_FUNC_SUBTRACT</constant>, <constant>GL_FUNC_REVERSE_SUBTRACT</constant>,
<constant>GL_MAX</constant>, or <constant>GL_MIN</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBlendEquationSeparate</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with an argument of <constant>GL_BLEND_EQUATION_RGB</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with an argument of <constant>GL_BLEND_EQUATION_ALPHA</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBlendFuncSeparate</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2006 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

1256
Source/Bind/Specifications/Docs/glBlendFunc.xml Normal file
View file

File diff suppressed because it is too large Load diff

1315
Source/Bind/Specifications/Docs/glBlendFuncSeparate.xml Normal file
View file

File diff suppressed because it is too large Load diff

221
Source/Bind/Specifications/Docs/glBufferData.xml Normal file
View file

@ -0,0 +1,221 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBufferData">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBufferData</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBufferData</refname>
<refpurpose>creates and initializes a buffer object's data store</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBufferData</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLsizeiptr <parameter>size</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
<paramdef>GLenum <parameter>usage</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target buffer object.
The symbolic constant must be <constant>GL_ARRAY_BUFFER</constant>,
<constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
<constant>GL_PIXEL_PACK_BUFFER</constant>, or
<constant>GL_PIXEL_UNPACK_BUFFER</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
Specifies the size in bytes of the buffer object's new data store.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to data that will be copied into the data store for initialization,
or <constant>NULL</constant> if no data is to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>usage</parameter></term>
<listitem>
<para>
Specifies the expected usage pattern of the data store. The symbolic constant must be
<constant>GL_STREAM_DRAW</constant>, <constant>GL_STREAM_READ</constant>, <constant>GL_STREAM_COPY</constant>,
<constant>GL_STATIC_DRAW</constant>, <constant>GL_STATIC_READ</constant>, <constant>GL_STATIC_COPY</constant>,
<constant>GL_DYNAMIC_DRAW</constant>, <constant>GL_DYNAMIC_READ</constant>, or <constant>GL_DYNAMIC_COPY</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBufferData</function> creates a new data store for the buffer object currently bound to
<parameter>target</parameter>. Any pre-existing data store is deleted. The new data store is created with the
specified <parameter>size</parameter> in bytes and <parameter>usage</parameter>. If <parameter>data</parameter>
is not <constant>NULL</constant>, the data store is initialized with data from this pointer. In its initial
state, the new data store is not mapped, it has a <constant>NULL</constant> mapped pointer, and its mapped access
is <constant>GL_READ_WRITE</constant>.
</para>
<para>
<parameter>usage</parameter> is a hint to the GL implementation as to how a buffer object's data store will be
accessed. This enables the GL implementation to make more intelligent decisions that may significantly
impact buffer object performance. It does not, however, constrain the actual usage of the data store.
<parameter>usage</parameter> can be broken down into two parts: first, the frequency of access (modification
and usage), and second, the nature of that access. The frequency of access may be one of these:
</para>
<variablelist>
<varlistentry>
<term>STREAM</term>
<listitem>
<para>
The data store contents will be modified once and used at most a few times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>STATIC</term>
<listitem>
<para>
The data store contents will be modified once and used many times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DYNAMIC</term>
<listitem>
<para>
The data store contents will be modified repeatedly and used many times.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The nature of access may be one of these:
</para>
<variablelist>
<varlistentry>
<term>DRAW</term>
<listitem>
<para>
The data store contents are modified by the application, and used as the source for GL drawing and
image specification commands.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>READ</term>
<listitem>
<para>
The data store contents are modified by reading data from the GL, and used to return that data
when queried by the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>COPY</term>
<listitem>
<para>
The data store contents are modified by reading data from the GL, and used as the source for GL
drawing and image specification commands.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBufferData</function> is available only if the GL version is 1.5 or greater.
</para>
<para>
Targets <constant>GL_PIXEL_PACK_BUFFER</constant> and <constant>GL_PIXEL_UNPACK_BUFFER</constant> are available
only if the GL version is 2.1 or greater.
</para>
<para>
If <parameter>data</parameter> is <constant>NULL</constant>, a data store of the specified size is still created,
but its contents remain uninitialized and thus undefined.
</para>
<para>
Clients must align data elements consistent with the requirements of the client
platform, with an additional base-level requirement that an offset within a buffer to
a datum comprising <inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi> bytes be a
multiple of <mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_ARRAY_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
<constant>GL_PIXEL_PACK_BUFFER</constant>, or <constant>GL_PIXEL_UNPACK_BUFFER</constant>.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>usage</parameter> is not
<constant>GL_STREAM_DRAW</constant>, <constant>GL_STREAM_READ</constant>, <constant>GL_STREAM_COPY</constant>,
<constant>GL_STATIC_DRAW</constant>, <constant>GL_STATIC_READ</constant>, <constant>GL_STATIC_COPY</constant>,
<constant>GL_DYNAMIC_DRAW</constant>, <constant>GL_DYNAMIC_READ</constant>, or <constant>GL_DYNAMIC_COPY</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the reserved buffer object name 0 is bound to <parameter>target</parameter>.
</para>
<para>
<constant>GL_OUT_OF_MEMORY</constant> is generated if the GL is unable to create a data store with the specified <parameter>size</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBufferData</function>
is executed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetBufferSubData</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGetBufferParameteriv</refentrytitle></citerefentry> with argument <constant>GL_BUFFER_SIZE</constant> or <constant>GL_BUFFER_USAGE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBufferSubData</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

152
Source/Bind/Specifications/Docs/glBufferSubData.xml Normal file
View file

@ -0,0 +1,152 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glBufferSubData">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glBufferSubData</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBufferSubData</refname>
<refpurpose>updates a subset of a buffer object's data store</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBufferSubData</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLintptr <parameter>offset</parameter></paramdef>
<paramdef>GLsizeiptr <parameter>size</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target buffer object.
The symbolic constant must be <constant>GL_ARRAY_BUFFER</constant>,
<constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
<constant>GL_PIXEL_PACK_BUFFER</constant>, or
<constant>GL_PIXEL_UNPACK_BUFFER</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
Specifies the offset into the buffer object's data store where data replacement will begin,
measured in bytes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
Specifies the size in bytes of the data store region being replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the new data that will be copied into the data store.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glBufferSubData</function> redefines some or all of the data store for the buffer object currently
bound to <parameter>target</parameter>. Data starting at byte offset <parameter>offset</parameter> and
extending for <parameter>size</parameter> bytes is copied to the data store from the memory pointed to by
<parameter>data</parameter>. An error is thrown if <parameter>offset</parameter> and <parameter>size</parameter>
together define a range beyond the bounds of the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glBufferSubData</function> is available only if the GL version is 1.5 or greater.
</para>
<para>
Targets <constant>GL_PIXEL_PACK_BUFFER</constant> and <constant>GL_PIXEL_UNPACK_BUFFER</constant> are available
only if the GL version is 2.1 or greater.
</para>
<para>
When replacing the entire data store, consider using <function>glBufferSubData</function> rather
than completely recreating the data store with <function>glBufferData</function>. This avoids the cost of
reallocating the data store.
</para>
<para>
Consider using multiple buffer objects to avoid stalling the rendering pipeline during data store updates.
If any rendering in the pipeline makes reference to data in the buffer object being updated by
<function>glBufferSubData</function>, especially from the specific region being updated, that rendering must
drain from the pipeline before the data store can be updated.
</para>
<para>
Clients must align data elements consistent with the requirements of the client
platform, with an additional base-level requirement that an offset within a buffer to
a datum comprising <inlineequation><mml:math><mml:mi mathvariant="italic">N</mml:mi> bytes be a
multiple of <mml:mi mathvariant="italic">N</mml:mi></mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_ARRAY_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
<constant>GL_PIXEL_PACK_BUFFER</constant>, or <constant>GL_PIXEL_UNPACK_BUFFER</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>offset</parameter> or
<parameter>size</parameter> is negative, or if together they define a region of memory
that extends beyond the buffer object's allocated data store.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the reserved buffer object name 0 is bound to <parameter>target</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the buffer object being updated is mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBufferSubData</function>
is executed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetBufferSubData</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

100
Source/Bind/Specifications/Docs/glCallList.xml Normal file
View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCallList">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCallList</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCallList</refname>
<refpurpose>execute a display list</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCallList</function></funcdef>
<paramdef>GLuint <parameter>list</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>list</parameter></term>
<listitem>
<para>
Specifies the integer name of the display list to be executed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCallList</function> causes the named display list to be executed.
The commands saved in the display list are executed in order,
just as if they were called without using a display list.
If <parameter>list</parameter> has not been defined as a display list,
<function>glCallList</function> is ignored.
</para>
<para>
<function>glCallList</function> can appear inside a display list.
To avoid the possibility of infinite recursion resulting from display lists
calling one another,
a limit is placed on the nesting level of display
lists during display-list execution.
This limit is at least 64, and it depends on the implementation.
</para>
<para>
GL state is not saved and restored across a call to <function>glCallList</function>.
Thus,
changes made to GL state during the execution of a display list
remain after execution of the display list is completed.
Use <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to preserve GL state across <function>glCallList</function> calls.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Display lists can be executed between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
as long as the display list includes only commands that are allowed
in this interval.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_LIST_NESTING</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<function>glCallLists</function>,
<citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

284
Source/Bind/Specifications/Docs/glCallLists.xml Normal file
View file

@ -0,0 +1,284 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCallLists">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCallLists</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCallLists</refname>
<refpurpose>execute a list of display lists</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCallLists</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>lists</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of display lists to be executed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies the type of values in <parameter>lists</parameter>.
Symbolic constants
<constant>GL_BYTE</constant>,
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_INT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_2_BYTES</constant>,
<constant>GL_3_BYTES</constant>, and
<constant>GL_4_BYTES</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>lists</parameter></term>
<listitem>
<para>
Specifies the address of an array of name offsets in the display list.
The pointer type is void because the offsets can be bytes,
shorts,
ints,
or floats,
depending on the value of <parameter>type</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCallLists</function> causes each display list in the list of names passed as <parameter>lists</parameter>
to be executed.
As a result,
the commands saved in each display list are executed in order,
just as if they were called without using a display list.
Names of display lists that have not been defined are ignored.
</para>
<para>
<function>glCallLists</function> provides an efficient means for executing more than one display list.
<parameter>type</parameter> allows lists with various name formats to be accepted.
The formats are as
follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_BYTE</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of signed bytes,
each in the range
<inlineequation><mml:math>
<!-- eqn: -128:-->
<mml:mn>-128</mml:mn>
</mml:math></inlineequation>
through 127.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_UNSIGNED_BYTE</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned bytes,
each in the range 0 through 255.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_SHORT</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of signed two-byte integers,
each in the range
<inlineequation><mml:math>
<!-- eqn: -32768:-->
<mml:mn>-32768</mml:mn>
</mml:math></inlineequation>
through 32767.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_UNSIGNED_SHORT</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned two-byte integers,
each in the range 0 through 65535.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_INT</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of signed four-byte integers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_UNSIGNED_INT</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned four-byte integers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FLOAT</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of four-byte floating-point values.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_2_BYTES</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned bytes.
Each pair of bytes specifies a single display-list name.
The value of the pair is computed as 256 times the unsigned value
of the first byte plus the unsigned value of the second byte.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_3_BYTES</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned bytes.
Each triplet of bytes specifies a single display-list name.
The value of the triplet is computed as 65536 times the unsigned value
of the first byte,
plus 256 times the unsigned value of the second byte,
plus the unsigned value of the third byte.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_4_BYTES</constant></term>
<listitem>
<para>
<parameter>lists</parameter> is treated as an array of unsigned bytes.
Each quadruplet of bytes specifies a single display-list name.
The value of the quadruplet is computed as 16777216 times the unsigned value
of the first byte,
plus 65536 times the unsigned value of the second byte,
plus 256 times the unsigned value of the third byte,
plus the unsigned value of the fourth byte.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The list of display-list names is not null-terminated.
Rather,
<parameter>n</parameter> specifies how many names are to be taken from <parameter>lists</parameter>.
</para>
<para>
An additional level of indirection is made available with the
<citerefentry><refentrytitle>glListBase</refentrytitle></citerefentry> command,
which specifies an unsigned offset that is added to each display-list
name specified in <parameter>lists</parameter> before that display list is executed.
</para>
<para>
<function>glCallLists</function> can appear inside a display list.
To avoid the possibility of infinite recursion resulting from display lists
calling one another,
a limit is placed on the nesting level of display
lists during display-list execution.
This limit must be at least 64, and it depends on the implementation.
</para>
<para>
GL state is not saved and restored across a call to <function>glCallLists</function>.
Thus,
changes made to GL state during the execution of the display lists
remain after execution is completed.
Use <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to preserve GL state across <function>glCallLists</function> calls.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Display lists can be executed between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
as long as the display list includes only commands that are allowed
in this interval.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of
<constant>GL_BYTE</constant>,
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_INT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_2_BYTES</constant>,
<constant>GL_3_BYTES</constant>,
<constant>GL_4_BYTES</constant>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LIST_BASE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_LIST_NESTING</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glListBase</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

167
Source/Bind/Specifications/Docs/glClear.xml Normal file
View file

@ -0,0 +1,167 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClear">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClear</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClear</refname>
<refpurpose>clear buffers to preset values</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClear</function></funcdef>
<paramdef>GLbitfield <parameter>mask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mask</parameter></term>
<listitem>
<para>
Bitwise OR of masks that indicate the buffers to be cleared.
The four masks are
<constant>GL_COLOR_BUFFER_BIT</constant>,
<constant>GL_DEPTH_BUFFER_BIT</constant>,
<constant>GL_ACCUM_BUFFER_BIT</constant>, and
<constant>GL_STENCIL_BUFFER_BIT</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClear</function> sets the bitplane area of the window to values previously selected
by <function>glClearColor</function>, <function>glClearIndex</function>, <function>glClearDepth</function>,
<function>glClearStencil</function>, and <function>glClearAccum</function>.
Multiple color buffers can be cleared simultaneously by selecting
more than one buffer at a time using <citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>.
</para>
<para>
The pixel ownership test,
the scissor test,
dithering, and the buffer writemasks affect the operation of <function>glClear</function>.
The scissor box bounds the cleared region.
Alpha function,
blend function,
logical operation,
stenciling,
texture mapping,
and depth-buffering are ignored by <function>glClear</function>.
</para>
<para>
<function>glClear</function> takes a single argument that is the bitwise OR of several
values indicating which buffer is to be cleared.
</para>
<para>
The values are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_COLOR_BUFFER_BIT</constant></term>
<listitem>
<para>
Indicates the buffers currently enabled for color
writing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_DEPTH_BUFFER_BIT</constant></term>
<listitem>
<para>
Indicates the depth buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_ACCUM_BUFFER_BIT</constant></term>
<listitem>
<para>
Indicates the accumulation buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_STENCIL_BUFFER_BIT</constant></term>
<listitem>
<para>
Indicates the stencil buffer.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The value to which each buffer is cleared depends on the setting of the
clear value for that buffer.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
If a buffer is not present,
then a <function>glClear</function> directed at that buffer has no effect.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if any bit other than the four defined
bits is set in <parameter>mask</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClear</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_STENCIL_CLEAR_VALUE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<function>glClearAccum</function>,
<function>glClearColor</function>,
<function>glClearDepth</function>,
<function>glClearIndex</function>,
<function>glClearStencil</function>,
<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilMask</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

90
Source/Bind/Specifications/Docs/glClearAccum.xml Normal file
View file

@ -0,0 +1,90 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearAccum">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClearAccum</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearAccum</refname>
<refpurpose>specify clear values for the accumulation buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearAccum</function></funcdef>
<paramdef>GLfloat <parameter>red</parameter></paramdef>
<paramdef>GLfloat <parameter>green</parameter></paramdef>
<paramdef>GLfloat <parameter>blue</parameter></paramdef>
<paramdef>GLfloat <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>red</parameter></term>
<term><parameter>green</parameter></term>
<term><parameter>blue</parameter></term>
<term><parameter>alpha</parameter></term>
<listitem>
<para>
Specify the red, green, blue, and alpha values used when the
accumulation buffer is cleared.
The initial values are all 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClearAccum</function> specifies the red, green, blue, and alpha values used by <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
to clear the accumulation buffer.
</para>
<para>
Values specified by <function>glClearAccum</function> are clamped to the
range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClearAccum</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_CLEAR_VALUE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glAccum</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

88
Source/Bind/Specifications/Docs/glClearColor.xml Normal file
View file

@ -0,0 +1,88 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearColor">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClearColor</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearColor</refname>
<refpurpose>specify clear values for the color buffers</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearColor</function></funcdef>
<paramdef>GLclampf <parameter>red</parameter></paramdef>
<paramdef>GLclampf <parameter>green</parameter></paramdef>
<paramdef>GLclampf <parameter>blue</parameter></paramdef>
<paramdef>GLclampf <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>red</parameter></term>
<term><parameter>green</parameter></term>
<term><parameter>blue</parameter></term>
<term><parameter>alpha</parameter></term>
<listitem>
<para>
Specify the red, green, blue, and alpha values used when the
color buffers are cleared.
The initial values are all 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClearColor</function> specifies the red,
green,
blue,
and alpha values used by <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> to clear the color buffers.
Values specified by <function>glClearColor</function> are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClearColor</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_CLEAR_VALUE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

78
Source/Bind/Specifications/Docs/glClearDepth.xml Normal file
View file

@ -0,0 +1,78 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearDepth">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClearDepth</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearDepth</refname>
<refpurpose>specify the clear value for the depth buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearDepth</function></funcdef>
<paramdef>GLclampd <parameter>depth</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>depth</parameter></term>
<listitem>
<para>
Specifies the depth value used when the depth buffer is cleared. The
initial value is 1.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClearDepth</function> specifies the depth value used by <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> to clear the depth buffer.
Values specified by <function>glClearDepth</function> are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClearDepth</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_CLEAR_VALUE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

93
Source/Bind/Specifications/Docs/glClearIndex.xml Normal file
View file

@ -0,0 +1,93 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearIndex">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClearIndex</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearIndex</refname>
<refpurpose>specify the clear value for the color index buffers</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearIndex</function></funcdef>
<paramdef>GLfloat <parameter>c</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>c</parameter></term>
<listitem>
<para>
Specifies the index used when the color index buffers are cleared.
The initial value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClearIndex</function> specifies the index used by <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
to clear the color index buffers.
<parameter>c</parameter> is not clamped.
Rather,
<parameter>c</parameter> is converted to a fixed-point value with unspecified precision
to the right of the binary point.
The integer part of this value is then masked with
<inlineequation><mml:math>
<!-- eqn: 2 sup m - 1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>
is the number of bits in a color index stored in the frame buffer.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClearIndex</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_BITS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

94
Source/Bind/Specifications/Docs/glClearStencil.xml Normal file
View file

@ -0,0 +1,94 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearStencil">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClearStencil</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearStencil</refname>
<refpurpose>specify the clear value for the stencil buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearStencil</function></funcdef>
<paramdef>GLint <parameter>s</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>s</parameter></term>
<listitem>
<para>
Specifies the index used when the stencil buffer is cleared.
The initial value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClearStencil</function> specifies the index used by <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> to clear the stencil buffer.
<parameter>s</parameter> is masked with
<inlineequation><mml:math>
<!-- eqn: 2 sup m - 1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>
is the number of bits in the stencil buffer.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClearStencil</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_STENCIL_CLEAR_VALUE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_STENCIL_BITS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilFuncSeparate</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilMaskSeparate</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilOpSeparate</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

91
Source/Bind/Specifications/Docs/glClientActiveTexture.xml Normal file
View file

@ -0,0 +1,91 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClientActiveTexture">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClientActiveTexture</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClientActiveTexture</refname>
<refpurpose>select active texture unit</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClientActiveTexture</function></funcdef>
<paramdef>GLenum <parameter>texture</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>texture</parameter></term>
<listitem>
<para>
Specifies which texture unit to make active. The number
of texture units is implementation dependent, but must be at least
two. <parameter>texture</parameter> must be one of
<constant>GL_TEXTURE</constant><inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
where i ranges from 0 to the value of <constant>GL_MAX_TEXTURE_COORDS</constant> - 1, which is an
implementation-dependent value. The initial value is
<constant>GL_TEXTURE0</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glClientActiveTexture</function> selects the vertex array client state parameters to be modified by
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>, and enabled or disabled with
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>, respectively,
when called with a parameter of <constant>GL_TEXTURE_COORD_ARRAY</constant>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glClientActiveTexture</function> is supported only if the GL version is 1.3 or greater, or
<code>ARB_multitexture</code> is included in the string returned by
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry> when called with the argument <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>texture</parameter> is not one of
<constant>GL_TEXTURE</constant><inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
where
i ranges from 0 to the value of <constant>GL_MAX_TEXTURE_COORDS</constant> - 1.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CLIENT_ACTIVE_TEXTURE</constant> or <constant>GL_MAX_TEXTURE_COORDS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

134
Source/Bind/Specifications/Docs/glClipPlane.xml Normal file
View file

@ -0,0 +1,134 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClipPlane">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glClipPlane</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClipPlane</refname>
<refpurpose>specify a plane against which all geometry is clipped</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClipPlane</function></funcdef>
<paramdef>GLenum <parameter>plane</parameter></paramdef>
<paramdef>const GLdouble * <parameter>equation</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>plane</parameter></term>
<listitem>
<para>
Specifies which clipping plane is being positioned.
Symbolic names of the form <constant>GL_CLIP_PLANE</constant><emphasis>i</emphasis>,
where <emphasis>i</emphasis> is an integer between 0 and <constant>GL_MAX_CLIP_PLANES</constant>
<inlineequation><mml:math>
<!-- eqn: - 1:-->
<mml:mn>-1</mml:mn>
</mml:math></inlineequation>,
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>equation</parameter></term>
<listitem>
<para>
Specifies the address of an array of four double-precision floating-point values.
These values are interpreted as a plane equation.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Geometry is always clipped against the boundaries of a six-plane frustum
in <emphasis>x</emphasis>, <emphasis>y</emphasis>, and <emphasis>z</emphasis>.
<function>glClipPlane</function> allows the specification of additional planes,
not necessarily perpendicular to the <emphasis>x</emphasis>, <emphasis>y</emphasis>, or <emphasis>z</emphasis> axis,
against which all geometry is clipped.
To determine the maximum number of additional clipping planes, call
<citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> with argument <constant>GL_MAX_CLIP_PLANES</constant>. All
implementations support at least six such clipping planes.
Because the resulting clipping region is the intersection
of the defined half-spaces,
it is always convex.
</para>
<para>
<function>glClipPlane</function> specifies a half-space using a four-component plane equation.
When <function>glClipPlane</function> is called,
<parameter>equation</parameter> is transformed by the inverse of the modelview matrix
and stored in the resulting eye coordinates.
Subsequent changes to the modelview matrix have no effect on the
stored plane-equation components.
If the dot product of the eye coordinates of a vertex with the
stored plane equation components is positive or zero,
the vertex is <emphasis>in</emphasis> with respect to that clipping plane.
Otherwise, it is <emphasis>out</emphasis>.
</para>
<para>
To enable and disable clipping planes, call
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with the argument
<constant>GL_CLIP_PLANE</constant><emphasis>i</emphasis>,
where <emphasis>i</emphasis> is the plane number.
</para>
<para>
All clipping planes are initially defined as (0, 0, 0, 0) in eye coordinates
and are
disabled.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
It is always the case that <constant>GL_CLIP_PLANE</constant>
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
= <constant>GL_CLIP_PLANE0</constant> +
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>plane</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glClipPlane</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetClipPlane</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_CLIP_PLANE</constant><emphasis>i</emphasis>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

383
Source/Bind/Specifications/Docs/glColor.xml Normal file
View file

@ -0,0 +1,383 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColor">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColor</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColor</refname>
<refpurpose>set the current color</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3b</function></funcdef>
<paramdef>GLbyte <parameter>red</parameter></paramdef>
<paramdef>GLbyte <parameter>green</parameter></paramdef>
<paramdef>GLbyte <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3s</function></funcdef>
<paramdef>GLshort <parameter>red</parameter></paramdef>
<paramdef>GLshort <parameter>green</parameter></paramdef>
<paramdef>GLshort <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3i</function></funcdef>
<paramdef>GLint <parameter>red</parameter></paramdef>
<paramdef>GLint <parameter>green</parameter></paramdef>
<paramdef>GLint <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3f</function></funcdef>
<paramdef>GLfloat <parameter>red</parameter></paramdef>
<paramdef>GLfloat <parameter>green</parameter></paramdef>
<paramdef>GLfloat <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3d</function></funcdef>
<paramdef>GLdouble <parameter>red</parameter></paramdef>
<paramdef>GLdouble <parameter>green</parameter></paramdef>
<paramdef>GLdouble <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3ub</function></funcdef>
<paramdef>GLubyte <parameter>red</parameter></paramdef>
<paramdef>GLubyte <parameter>green</parameter></paramdef>
<paramdef>GLubyte <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3us</function></funcdef>
<paramdef>GLushort <parameter>red</parameter></paramdef>
<paramdef>GLushort <parameter>green</parameter></paramdef>
<paramdef>GLushort <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3ui</function></funcdef>
<paramdef>GLuint <parameter>red</parameter></paramdef>
<paramdef>GLuint <parameter>green</parameter></paramdef>
<paramdef>GLuint <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4b</function></funcdef>
<paramdef>GLbyte <parameter>red</parameter></paramdef>
<paramdef>GLbyte <parameter>green</parameter></paramdef>
<paramdef>GLbyte <parameter>blue</parameter></paramdef>
<paramdef>GLbyte <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4s</function></funcdef>
<paramdef>GLshort <parameter>red</parameter></paramdef>
<paramdef>GLshort <parameter>green</parameter></paramdef>
<paramdef>GLshort <parameter>blue</parameter></paramdef>
<paramdef>GLshort <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4i</function></funcdef>
<paramdef>GLint <parameter>red</parameter></paramdef>
<paramdef>GLint <parameter>green</parameter></paramdef>
<paramdef>GLint <parameter>blue</parameter></paramdef>
<paramdef>GLint <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4f</function></funcdef>
<paramdef>GLfloat <parameter>red</parameter></paramdef>
<paramdef>GLfloat <parameter>green</parameter></paramdef>
<paramdef>GLfloat <parameter>blue</parameter></paramdef>
<paramdef>GLfloat <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4d</function></funcdef>
<paramdef>GLdouble <parameter>red</parameter></paramdef>
<paramdef>GLdouble <parameter>green</parameter></paramdef>
<paramdef>GLdouble <parameter>blue</parameter></paramdef>
<paramdef>GLdouble <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4ub</function></funcdef>
<paramdef>GLubyte <parameter>red</parameter></paramdef>
<paramdef>GLubyte <parameter>green</parameter></paramdef>
<paramdef>GLubyte <parameter>blue</parameter></paramdef>
<paramdef>GLubyte <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4us</function></funcdef>
<paramdef>GLushort <parameter>red</parameter></paramdef>
<paramdef>GLushort <parameter>green</parameter></paramdef>
<paramdef>GLushort <parameter>blue</parameter></paramdef>
<paramdef>GLushort <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4ui</function></funcdef>
<paramdef>GLuint <parameter>red</parameter></paramdef>
<paramdef>GLuint <parameter>green</parameter></paramdef>
<paramdef>GLuint <parameter>blue</parameter></paramdef>
<paramdef>GLuint <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>red</parameter></term>
<term><parameter>green</parameter></term>
<term><parameter>blue</parameter></term>
<listitem>
<para>
Specify new red, green, and blue values for the current color.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>alpha</parameter></term>
<listitem>
<para>
Specifies a new alpha value for the current color.
Included only in the four-argument <function>glColor4</function> commands.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3bv</function></funcdef>
<paramdef>const GLbyte * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3sv</function></funcdef>
<paramdef>const GLshort * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3iv</function></funcdef>
<paramdef>const GLint * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3fv</function></funcdef>
<paramdef>const GLfloat * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3dv</function></funcdef>
<paramdef>const GLdouble * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3ubv</function></funcdef>
<paramdef>const GLubyte * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3usv</function></funcdef>
<paramdef>const GLushort * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor3uiv</function></funcdef>
<paramdef>const GLuint * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4bv</function></funcdef>
<paramdef>const GLbyte * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4sv</function></funcdef>
<paramdef>const GLshort * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4iv</function></funcdef>
<paramdef>const GLint * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4fv</function></funcdef>
<paramdef>const GLfloat * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4dv</function></funcdef>
<paramdef>const GLdouble * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4ubv</function></funcdef>
<paramdef>const GLubyte * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4usv</function></funcdef>
<paramdef>const GLushort * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColor4uiv</function></funcdef>
<paramdef>const GLuint * <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>v</parameter></term>
<listitem>
<para>
Specifies a pointer to an array that contains red, green, blue,
and (sometimes) alpha values.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The GL stores both a current single-valued color index
and a current four-valued RGBA color.
<function>glColor</function> sets a new four-valued RGBA color.
<function>glColor</function> has two major variants:
<function>glColor3</function> and <function>glColor4</function>.
<function>glColor3</function> variants specify new red,
green,
and blue values explicitly
and set the current alpha value to 1.0 (full intensity) implicitly.
<function>glColor4</function> variants specify all four color components explicitly.
</para>
<para>
<function>glColor3b</function>, <function>glColor4b</function>,
<function>glColor3s</function>, <function>glColor4s</function>, <function>glColor3i</function>, and <function>glColor4i</function> take
three or four signed byte, short, or long integers as arguments.
When <emphasis role="bold">v</emphasis> is appended to the name,
the color commands can take a pointer to an array of such values.
</para>
<para>
Current color values are stored in floating-point format,
with unspecified mantissa and exponent sizes.
Unsigned integer color components,
when specified,
are linearly mapped to floating-point values such that the largest
representable value maps to 1.0 (full intensity),
and 0 maps to 0.0 (zero intensity).
Signed integer color components,
when specified,
are linearly mapped to floating-point values such that the most positive
representable value maps to 1.0,
and the most negative representable value maps to
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>.
(Note that
this mapping does not convert 0 precisely to 0.0.)
Floating-point values are mapped directly.
</para>
<para>
Neither floating-point nor signed integer values are clamped
to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
before the current color is updated.
However,
color components are clamped to this range before they are interpolated
or written into a color buffer.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
The initial value for the current color is (1, 1, 1, 1).
</para>
<para>
The current color can be updated at any time.
In particular,
<function>glColor</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_COLOR</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_RGBA_MODE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<function>glColorPointer</function>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColor</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

99
Source/Bind/Specifications/Docs/glColorMask.xml Normal file
View file

@ -0,0 +1,99 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorMask">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorMask</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorMask</refname>
<refpurpose>enable and disable writing of frame buffer color components</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorMask</function></funcdef>
<paramdef>GLboolean <parameter>red</parameter></paramdef>
<paramdef>GLboolean <parameter>green</parameter></paramdef>
<paramdef>GLboolean <parameter>blue</parameter></paramdef>
<paramdef>GLboolean <parameter>alpha</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>red</parameter></term>
<term><parameter>green</parameter></term>
<term><parameter>blue</parameter></term>
<term><parameter>alpha</parameter></term>
<listitem>
<para>
Specify whether red, green, blue, and alpha can or cannot be written
into the frame buffer.
The initial values are all <constant>GL_TRUE</constant>,
indicating that the color components can be written.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorMask</function> specifies whether the individual color components in the frame buffer
can or cannot be written.
If <parameter>red</parameter> is <constant>GL_FALSE</constant>,
for example,
no change is made to the red component of any pixel in any of the
color buffers,
regardless of the drawing operation attempted.
</para>
<para>
Changes to individual bits of components cannot be controlled.
Rather,
changes are either enabled or disabled for entire color components.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorMask</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_WRITEMASK</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_RGBA_MODE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilMask</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

143
Source/Bind/Specifications/Docs/glColorMaterial.xml Normal file
View file

@ -0,0 +1,143 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorMaterial">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorMaterial</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorMaterial</refname>
<refpurpose>cause a material color to track the current color</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorMaterial</function></funcdef>
<paramdef>GLenum <parameter>face</parameter></paramdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>face</parameter></term>
<listitem>
<para>
Specifies whether front,
back,
or both front and back material parameters should track the current color.
Accepted values are
<constant>GL_FRONT</constant>,
<constant>GL_BACK</constant>,
and <constant>GL_FRONT_AND_BACK</constant>.
The initial value is <constant>GL_FRONT_AND_BACK</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies which of several material parameters track the current color.
Accepted values are
<constant>GL_EMISSION</constant>,
<constant>GL_AMBIENT</constant>,
<constant>GL_DIFFUSE</constant>,
<constant>GL_SPECULAR</constant>,
and <constant>GL_AMBIENT_AND_DIFFUSE</constant>.
The initial value is <constant>GL_AMBIENT_AND_DIFFUSE</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorMaterial</function> specifies which material parameters track the current color.
When <constant>GL_COLOR_MATERIAL</constant> is enabled,
the material parameter or parameters specified by <parameter>mode</parameter>,
of the material or materials specified by <parameter>face</parameter>,
track the current color at all times.
</para>
<para>
To enable and disable <constant>GL_COLOR_MATERIAL</constant>, call
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL</constant>.
<constant>GL_COLOR_MATERIAL</constant> is initially disabled.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glColorMaterial</function> makes it possible to change a subset of material parameters for each
vertex using only the <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry> command,
without calling <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>.
If only such a subset of parameters is to be specified for each
vertex, calling <function>glColorMaterial</function> is preferable to calling <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>.
</para>
<para>
Call <function>glColorMaterial</function> before enabling <constant>GL_COLOR_MATERIAL</constant>.
</para>
<para>
Calling <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>
may leave the current color indeterminate, if the color array is enabled.
If
<function>glColorMaterial</function> is enabled while the current color is indeterminate, the
lighting material state specified by <parameter>face</parameter> and <parameter>mode</parameter> is also indeterminate.
</para>
<para>
If the GL version is 1.1 or greater, and <constant>GL_COLOR_MATERIAL</constant> is
enabled, evaluated color values affect the results of the lighting
equation as if the current color were being modified, but no change is
made to the tracking lighting parameter of the current color.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>face</parameter> or <parameter>mode</parameter> is not an
accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorMaterial</function> is executed between
the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL_PARAMETER</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL_FACE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

208
Source/Bind/Specifications/Docs/glColorPointer.xml Normal file
View file

@ -0,0 +1,208 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorPointer">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorPointer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorPointer</refname>
<refpurpose>define an array of colors</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorPointer</function></funcdef>
<paramdef>GLint <parameter>size</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>GLsizei <parameter>stride</parameter></paramdef>
<paramdef>const GLvoid * <parameter>pointer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
Specifies the number of components per color. Must be 3 or 4.
The initial value is 4.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies the data type of each color component in the array.
Symbolic constants
<constant>GL_BYTE</constant>,
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_INT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_FLOAT</constant>,
and
<constant>GL_DOUBLE</constant>
are accepted.
The initial value is <constant>GL_FLOAT</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>stride</parameter></term>
<listitem>
<para>
Specifies the byte offset between consecutive colors.
If <parameter>stride</parameter> is 0, the colors are understood to be
tightly packed in the array. The initial value is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pointer</parameter></term>
<listitem>
<para>
Specifies a pointer to the first component of the first color element
in the array. The initial value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorPointer</function> specifies the location and data format of an array of color components
to use when rendering.
<parameter>size</parameter> specifies the number of components per color, and must be 3 or 4.
<parameter>type</parameter> specifies the data type of each color component, and <parameter>stride</parameter>
specifies the byte stride from one color to the next, allowing vertices and
attributes to be packed into a single array or stored in separate arrays.
(Single-array storage may be more efficient on some implementations;
see <citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>.)
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_ARRAY_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a color array is
specified, <parameter>pointer</parameter> is treated as a byte offset into the buffer object's data store.
Also, the buffer object binding (<constant>GL_ARRAY_BUFFER_BINDING</constant>) is saved as color vertex array
client-side state (<constant>GL_COLOR_ARRAY_BUFFER_BINDING</constant>).
</para>
<para>
When a color array is specified,
<parameter>size</parameter>, <parameter>type</parameter>, <parameter>stride</parameter>, and <parameter>pointer</parameter> are saved as client-side
state, in addition to the current vertex array buffer object binding.
</para>
<para>
To enable and disable the color array, call
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry> with the argument
<constant>GL_COLOR_ARRAY</constant>. If
enabled, the color array is used
when <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry> is called.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glColorPointer</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
The color array is initially disabled and isn't accessed when
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>
is called.
</para>
<para>
Execution of <function>glColorPointer</function> is not allowed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
but an error may or may not be generated. If no error is generated,
the operation is undefined.
</para>
<para>
<function>glColorPointer</function> is typically implemented on the client side.
</para>
<para>
Color array parameters are client-side state and are therefore not saved
or restored by <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>.
Use <citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry> instead.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is not 3 or 4.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>stride</parameter> is negative.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY_TYPE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY_STRIDE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry> with argument <constant>GL_COLOR_ARRAY_POINTER</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

227
Source/Bind/Specifications/Docs/glColorSubTable.xml Normal file
View file

@ -0,0 +1,227 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorSubTable">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorSubTable</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorSubTable</refname>
<refpurpose>respecify a portion of a color table</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorSubTable</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLsizei <parameter>start</parameter></paramdef>
<paramdef>GLsizei <parameter>count</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be one of
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, or
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
The starting index of the portion of the color table to be replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
The number of table entries to replace.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The format of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_RED</constant>,
<constant>GL_GREEN</constant>,
<constant>GL_BLUE</constant>,
<constant>GL_ALPHA</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_RGB</constant>,
<constant>GL_BGR</constant>,
<constant>GL_RGBA</constant>, and
<constant>GL_BGRA</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
The type of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_BYTE</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Pointer to a one-dimensional array of pixel data that is processed to
replace the specified region of the color table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorSubTable</function> is used to respecify a contiguous portion of a color table previously
defined using <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>. The pixels referenced by <parameter>data</parameter> replace the
portion of the existing table from indices <parameter>start</parameter> to
<inlineequation><mml:math>
<!-- eqn: start + count - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">count</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive. This region may not include any
entries outside the range of the color table as it was originally specified.
It is not an error to specify a subtexture with width of 0, but such a
specification has no effect.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a portion of a color table is
respecified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glColorSubTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
<para>
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: start + count > width:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">count</mml:mi>
</mml:mrow>
<mml:mo>&gt;</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:math></inlineequation>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorSubTable</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyColorSubTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

778
Source/Bind/Specifications/Docs/glColorTable.xml Normal file
View file

@ -0,0 +1,778 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorTable">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorTable</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorTable</refname>
<refpurpose>define a color lookup table</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorTable</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be one of
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>,
<constant>GL_PROXY_COLOR_TABLE</constant>,
<constant>GL_PROXY_POST_CONVOLUTION_COLOR_TABLE</constant>,
or
<constant>GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal format of the color table.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, and
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The number of entries in the color lookup table specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The format of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_RED</constant>,
<constant>GL_GREEN</constant>,
<constant>GL_BLUE</constant>,
<constant>GL_ALPHA</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_RGB</constant>,
<constant>GL_BGR</constant>,
<constant>GL_RGBA</constant>, and
<constant>GL_BGRA</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
The type of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_BYTE</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Pointer to a one-dimensional array of pixel data that is processed to
build the color table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorTable</function> may be used in two ways:
to test the actual size and color resolution of a lookup table
given a particular set of parameters,
or to load the contents of a color lookup
table.
Use the targets <constant>GL_PROXY_*</constant> for the first case
and the other targets for the second case.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a color table is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
<para>
If <parameter>target</parameter> is <constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
or
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>,
<function>glColorTable</function> builds a color lookup table from an array of pixels.
The pixel array specified by <parameter>width</parameter>, <parameter>format</parameter>, <parameter>type</parameter>, and <parameter>data</parameter>
is extracted from memory and
processed just as if <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> were called, but processing
stops after the final expansion to RGBA is completed.
</para>
<para>
The four scale parameters and the four bias parameters that are defined
for the table are then used to scale and bias the R, G, B, and A components
of each pixel.
(Use <function>glColorTableParameter</function> to set these scale and bias
parameters.)
</para>
<para>
Next, the R, G, B, and A values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*" />
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.5*" align="center"/>
<colspec colwidth="1.5*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Finally, the red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in the color table.
They form a one-dimensional table with indices in the range
<inlineequation><mml:math>
<!-- eqn: [0, width-1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
<para>
If <parameter>target</parameter> is <constant>GL_PROXY_*</constant>,
<function>glColorTable</function> recomputes and stores the values of the proxy color table's state
variables
<constant>GL_COLOR_TABLE_FORMAT</constant>,
<constant>GL_COLOR_TABLE_WIDTH</constant>,
<constant>GL_COLOR_TABLE_RED_SIZE</constant>,
<constant>GL_COLOR_TABLE_GREEN_SIZE</constant>,
<constant>GL_COLOR_TABLE_BLUE_SIZE</constant>,
<constant>GL_COLOR_TABLE_ALPHA_SIZE</constant>,
<constant>GL_COLOR_TABLE_LUMINANCE_SIZE</constant>, and
<constant>GL_COLOR_TABLE_INTENSITY_SIZE</constant>.
There is no effect on the image or state of any actual color table.
If the specified color table is too large to be supported, then all the
proxy state variables listed above are set to zero.
Otherwise, the color table could be supported by <function>glColorTable</function>
using the corresponding non-proxy target,
and the proxy state variables are set as if that target were being defined.
</para>
<para>
The proxy state variables can be retrieved by calling
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry> with a target of
<constant>GL_PROXY_*</constant>.
This allows the application to decide if a particular <function>glColorTable</function>
command would succeed, and to determine what the resulting color table
attributes would be.
</para>
<para>
If a color table is enabled, and its width is non-zero, then its
contents are used to replace a subset of the components of each RGBA
pixel group, based on the internal format of the table.
</para>
<para>
Each pixel group has color components (R, G, B, A)
that are in the range
<inlineequation><mml:math>
<!-- eqn: [0.0, 1.0]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0.0</mml:mn>
<mml:mn>1.0</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
The color components are rescaled to
the size of the color lookup table to form an index.
Then a subset of the components based on the internal format of the table are
replaced by the table entry selected by that index.
If the color components and contents of the table are represented as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="2" align="left">
<colspec align="center"/>
<colspec align="center"/>
<thead>
<row>
<entry rowsep="1" align="center"><emphasis role="bold">
Representation
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Meaning
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="center">
<code>r</code>
</entry>
<entry align="left">
Table index computed from <code>R</code>
</entry>
</row>
<row>
<entry align="center">
<code>g</code>
</entry>
<entry align="left">
Table index computed from <code>G</code>
</entry>
</row>
<row>
<entry align="center">
<code>b</code>
</entry>
<entry align="left">
Table index computed from <code>B</code>
</entry>
</row>
<row>
<entry align="center">
<code>a</code>
</entry>
<entry align="left">
Table index computed from <code>A</code>
</entry>
</row>
<row>
<entry align="center">
<code>L[i]</code>
</entry>
<entry align="left">
Luminance value at table index <code>i</code>
</entry>
</row>
<row>
<entry align="center">
<code>I[i]</code>
</entry>
<entry align="left">
Intensity value at table index <code>i</code>
</entry>
</row>
<row>
<entry align="center">
<code>R[i]</code>
</entry>
<entry align="left">
Red value at table index <code>i</code>
</entry>
</row>
<row>
<entry align="center">
<code>G[i]</code>
</entry>
<entry align="left">
Green value at table index <code>i</code>
</entry>
</row>
<row>
<entry align="center">
<code>B[i]</code>
</entry>
<entry align="left">
Blue value at table index <code>i</code>
</entry>
</row>
<row>
<entry align="center">
<code>A[i]</code>
</entry>
<entry align="left">
Alpha value at table index <code>i</code>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
then the result of color table lookup is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="5" align="left">
<colspec colwidth="2*" />
<colspec colwidth="1*" colname="r"/>
<colspec colwidth="1*" colname="g"/>
<colspec colwidth="1*" colname="b"/>
<colspec colwidth="1*" colname="a"/>
<thead>
<row>
<entry align="left"><emphasis role="bold">
</emphasis></entry>
<entry namest="r" nameend="a" align="center"><emphasis role="bold">
Resulting Texture Components
</emphasis></entry>
</row>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Table Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
R
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
G
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
B
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
A
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
<code>R</code>
</entry>
<entry align="center">
<code>G</code>
</entry>
<entry align="center">
<code>B</code>
</entry>
<entry align="center">
<code>A[a]</code>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
<code>L[r]</code>
</entry>
<entry align="center">
<code>L[g]</code>
</entry>
<entry align="center">
<code>L[b]</code>
</entry>
<entry align="center">
<code>At</code>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
<code>L[r]</code>
</entry>
<entry align="center">
<code>L[g]</code>
</entry>
<entry align="center">
<code>L[b]</code>
</entry>
<entry align="center">
<code>A[a]</code>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
<code>I[r]</code>
</entry>
<entry align="center">
<code>I[g]</code>
</entry>
<entry align="center">
<code>I[b]</code>
</entry>
<entry align="center">
<code>I[a]</code>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
<code>R[r]</code>
</entry>
<entry align="center">
<code>G[g]</code>
</entry>
<entry align="center">
<code>B[b]</code>
</entry>
<entry align="center">
<code>A</code>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
<code>R[r]</code>
</entry>
<entry align="center">
<code>G[g]</code>
</entry>
<entry align="center">
<code>B[b]</code>
</entry>
<entry align="center">
<code>A[a]</code>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
When <constant>GL_COLOR_TABLE</constant> is enabled, the colors resulting from
the pixel map operation (if it is enabled) are mapped
by the color lookup table before being passed to the convolution
operation. The colors resulting from the convolution operation
are modified by the post convolution color lookup table when
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>
is enabled. These modified colors are then sent to the color matrix operation.
Finally, if <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>
is enabled, the colors resulting from the color matrix operation
are mapped by the post color matrix color lookup table before being
used by the histogram operation.
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glColorTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
<para>
If <parameter>target</parameter> is set to <constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
or <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>,
then <parameter>width</parameter> must be a power of two or a <constant>GL_INVALID_VALUE</constant>
error is generated.
</para>
<para>
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero.
</para>
<para>
<constant>GL_TABLE_TOO_LARGE</constant> is generated if the requested color table
is too large to be supported by the implementation, and <parameter>target</parameter> is
not a <constant>GL_PROXY_*</constant> target.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorTable</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorSubTable</refentrytitle></citerefentry>,
<function>glColorTableParameter</function>,
<citerefentry><refentrytitle>glCopyColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyColorSubTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

136
Source/Bind/Specifications/Docs/glColorTableParameter.xml Normal file
View file

@ -0,0 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glColorTableParameter">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glColorTableParameter</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glColorTableParameter</refname>
<refpurpose>set color lookup table parameters</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorTableParameterfv</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLfloat * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glColorTableParameteriv</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLint * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
The target color table.
Must be
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, or
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
The symbolic name of a texture color lookup table parameter.
Must be one of
<constant>GL_COLOR_TABLE_SCALE</constant> or
<constant>GL_COLOR_TABLE_BIAS</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
A pointer to an array where the values of the parameters are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glColorTableParameter</function> is used to specify the scale factors and bias terms applied to
color components when they are loaded into a color table. <parameter>target</parameter>
indicates which color table the scale and bias terms apply to; it
must be set to
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, or
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
<para>
<parameter>pname</parameter> must be <constant>GL_COLOR_TABLE_SCALE</constant> to set the
scale factors.
In this case, <parameter>params</parameter> points to an array of four values, which are
the scale factors for red, green, blue, and alpha, in that order.
</para>
<para>
<parameter>pname</parameter> must be <constant>GL_COLOR_TABLE_BIAS</constant> to set the
bias terms. In this case,
<parameter>params</parameter> points to an array of four values, which are the bias
terms for red, green, blue, and alpha, in that order.
</para>
<para>
The color tables themselves are specified by
calling <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glColorTableParameter</function> is available only if <code>ARB_imaging</code> is returned from calling
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry> with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> or <parameter>pname</parameter> is not
an acceptable value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorTableParameter</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

94
Source/Bind/Specifications/Docs/glCompileShader.xml Normal file
View file

@ -0,0 +1,94 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompileShader">
<refmeta>
<refentrytitle>glCompileShader</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompileShader</refname>
<refpurpose>Compiles a shader object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompileShader</function></funcdef>
<paramdef>GLuint <parameter>shader</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>shader</parameter></term>
<listitem>
<para>Specifies the shader object to be
compiled.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glCompileShader</function> compiles the source
code strings that have been stored in the shader object
specified by <parameter>shader</parameter>.</para>
<para>The compilation status will be stored as part of the
shader object's state. This value will be set to
<constant>GL_TRUE</constant> if the shader was compiled without
errors and is ready for use, and <constant>GL_FALSE</constant>
otherwise. It can be queried by calling
<citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with arguments <parameter>shader</parameter> and
<constant>GL_COMPILE_STATUS</constant>.</para>
<para>Compilation of a shader can fail for a number of reasons
as specified by the OpenGL Shading Language Specification.
Whether or not the compilation was successful, information about
the compilation can be obtained from the shader object's
information log by calling
<citerefentry><refentrytitle>glGetShaderInfoLog</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glCompileShader</function>
is available only if the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>shader</parameter> is not a value generated by
OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>shader</parameter> is not a shader object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glCompileShader</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetShaderInfoLog</refentrytitle></citerefentry>
with argument <parameter>shader</parameter></para>
<para><citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with arguments <parameter>shader</parameter> and
<constant>GL_COMPILE_STATUS</constant></para>
<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glShaderSource</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

239
Source/Bind/Specifications/Docs/glCompressedTexImage1D.xml Normal file
View file

@ -0,0 +1,239 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexImage1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexImage1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexImage1D</refname>
<refpurpose>specify a one-dimensional texture image in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexImage1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLint <parameter>border</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_1D</constant> or <constant>GL_PROXY_TEXTURE_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All implementations support texture images that are at least 64 texels wide. The height of the 1D texture image is 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>border</parameter></term>
<listitem>
<para>
Specifies the width of the border. Must be either 0 or 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable one-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>.
</para>
<para>
<function>glCompressedTexImage1D</function> loads a previously defined, and retrieved, compressed one-dimensional texture image if <parameter>target</parameter> is <constant>GL_TEXTURE_1D</constant> (see <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>).
</para>
<para>
If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_1D</constant>, no data is read from <parameter>data</parameter>, but
all of the texture image state is recalculated, checked for consistency, and checked against the implementation's capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see <citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level greater than or equal to 1.
</para>
<para>
<parameter>internalformat</parameter> must be extension-specified compressed-texture format. When a texture is loaded with <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> using a generic compressed texture format (e.g., <constant>GL_COMPRESSED_RGB</constant>) the GL selects from one of
its extensions supporting compressed textures. In order to load the
compressed texture image using <function>glCompressedTexImage1D</function>, query the compressed texture image's size and format using <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexImage1D</function> is available only if the GL version is 1.3 or greater.
</para>
<para>
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the <constant>GL_ARB_texture_non_power_of_two</constant> extension.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is one of the generic compressed internal formats: <constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>, <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>, <constant>GL_COMPRESSED_RGB</constant>, or
<constant>GL_COMPRESSED_RGBA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image
data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexImage1D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if
<parameter>data</parameter> is not encoded in a manner consistent with the extension
specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

295
Source/Bind/Specifications/Docs/glCompressedTexImage2D.xml Normal file
View file

@ -0,0 +1,295 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexImage2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexImage2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexImage2D</refname>
<refpurpose>specify a two-dimensional texture image in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexImage2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLint <parameter>border</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_2D</constant>, <constant>GL_PROXY_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
<constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All
implementations support 2D texture images that are at least 64 texels
wide and cube-mapped texture images that are at least 16 texels wide.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
Must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All
implementations support 2D texture images that are at least 64 texels
high and cube-mapped texture images that are at least 16 texels high.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>border</parameter></term>
<listitem>
<para>
Specifies the width of the border.
Must be either 0 or 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the
address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical
primitive for which texturing is enabled. To enable and disable
two-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D</constant>. To enable and disable texturing using
cube-mapped textures, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_CUBE_MAP</constant>.
</para>
<para>
<function>glCompressedTexImage2D</function> loads a previously defined, and retrieved, compressed two-dimensional
texture image if <parameter>target</parameter> is <constant>GL_TEXTURE_2D</constant> (see <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>).
</para>
<para>
If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_2D</constant>, no data is read from <parameter>data</parameter>, but
all of the texture image state is recalculated, checked for consistency,
and checked against the implementation's capabilities. If the
implementation cannot handle a texture of the requested texture size, it
sets all of the image state to 0, but does not generate an error (see
<citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level
greater than or equal to 1.
</para>
<para>
<parameter>internalformat</parameter> must be an extension-specified compressed-texture format.
When a texture is loaded with <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> using a generic compressed
texture format (e.g., <constant>GL_COMPRESSED_RGB</constant>), the GL selects from one of
its extensions supporting compressed textures. In order to load the
compressed texture image using <function>glCompressedTexImage2D</function>, query the compressed texture image's
size and format using <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexImage2D</function> is available only if the GL version is 1.3 or greater.
</para>
<para>
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the <constant>GL_ARB_texture_non_power_of_two</constant> extension.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is one of the generic compressed internal formats: <constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>, <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>, <constant>GL_COMPRESSED_RGB</constant>, or
<constant>GL_COMPRESSED_RGBA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image
data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexImage2D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if
<parameter>data</parameter> is not encoded in a manner consistent with the extension
specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

311
Source/Bind/Specifications/Docs/glCompressedTexImage3D.xml Normal file
View file

@ -0,0 +1,311 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexImage3D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexImage3D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexImage3D</refname>
<refpurpose>specify a three-dimensional texture image in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexImage3D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLsizei <parameter>depth</parameter></paramdef>
<paramdef>GLint <parameter>border</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_3D</constant> or <constant>GL_PROXY_TEXTURE_3D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All
implementations support 3D texture images that are at least 16 texels
wide.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All
implementations support 3D texture images that are at least 16 texels
high.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>depth</parameter></term>
<listitem>
<para>
Specifies the depth of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
All
implementations support 3D texture images that are at least 16 texels
deep.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>border</parameter></term>
<listitem>
<para>
Specifies the width of the border.
Must be either 0 or 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the
address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical
primitive for which texturing is enabled. To enable and disable
three-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D</constant>.
</para>
<para>
<function>glCompressedTexImage3D</function> loads a previously defined, and retrieved, compressed three-dimensional
texture image if <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant> (see <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>).
</para>
<para>
If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_3D</constant>, no data is read from <parameter>data</parameter>, but
all of the texture image state is recalculated, checked for consistency,
and checked against the implementation's capabilities. If the
implementation cannot handle a texture of the requested texture size, it
sets all of the image state to 0, but does not generate an error (see
<citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level
greater than or equal to 1.
</para>
<para>
<parameter>internalformat</parameter> must be an extension-specified compressed-texture format.
When a texture is loaded with <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> using a generic compressed
texture format (e.g., <constant>GL_COMPRESSED_RGB</constant>), the GL selects from one of
its extensions supporting compressed textures. In order to load the
compressed texture image using <function>glCompressedTexImage3D</function>, query the compressed texture image's
size and format using <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexImage3D</function> is available only if the GL version is 1.3 or greater.
</para>
<para>
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the <constant>GL_ARB_texture_non_power_of_two</constant> extension.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is one of the generic compressed internal formats: <constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>, <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>, <constant>GL_COMPRESSED_RGB</constant>, or
<constant>GL_COMPRESSED_RGBA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexImage3D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if <parameter>data</parameter> is not encoded in a manner consistent with the extension specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

243
Source/Bind/Specifications/Docs/glCompressedTexSubImage1D.xml Normal file
View file

@ -0,0 +1,243 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexSubImage1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexSubImage1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexSubImage1D</refname>
<refpurpose>specify a one-dimensional texture subimage in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexSubImage1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the x direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the
address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical
primitive for which texturing is enabled. To enable and disable
one-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_1D</constant>.
</para>
<para>
<function>glCompressedTexSubImage1D</function> redefines a contiguous subregion of an existing one-dimensional
texture image. The texels referenced by <parameter>data</parameter> replace the portion of the
existing texture array with x indices <parameter>xoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive. This region may not include any texels
outside the range of the texture array as it was originally specified. It
is not an error to specify a subtexture with width of 0, but such a
specification has no effect.
</para>
<para>
<parameter>format</parameter> must be an extension-specified
compressed-texture format. The <parameter>format</parameter> of the compressed texture
image is selected by the GL implementation that compressed it (see
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>), and should be queried at the time the texture was
compressed with <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexSubImage1D</function> is available only if the GL version is 1.3 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is one of these generic compressed internal formats:
<constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>,
<constant>GL_COMPRESSED_RGB</constant>,
<constant>GL_COMPRESSED_RGBA</constant>,
<constant>GL_COMPRESSED_SLUMINANCE</constant>,
<constant>GL_COMPRESSED_SLUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_SRGB</constant>,
<constant>GL_COMPRESSED_SRGBA</constant>, or
<constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image
data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexSubImage1D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if
<parameter>data</parameter> is not encoded in a manner consistent with the extension
specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

291
Source/Bind/Specifications/Docs/glCompressedTexSubImage2D.xml Normal file
View file

@ -0,0 +1,291 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexSubImage2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexSubImage2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexSubImage2D</refname>
<refpurpose>specify a two-dimensional texture subimage in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexSubImage2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>yoffset</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the x direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>yoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the y direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the
address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical
primitive for which texturing is enabled. To enable and disable
two-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D</constant>. To enable and disable texturing using
cube-mapped texture, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_CUBE_MAP</constant>.
</para>
<para>
<function>glCompressedTexSubImage2D</function> redefines a contiguous subregion of an existing two-dimensional
texture image. The texels referenced by <parameter>data</parameter> replace the portion of the
existing texture array with x indices <parameter>xoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and the y indices <parameter>yoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: yoffset + height - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive.
This region may not include any texels
outside the range of the texture array as it was originally specified. It
is not an error to specify a subtexture with width of 0, but such a
specification has no effect.
</para>
<para>
<parameter>format</parameter> must be an extension-specified
compressed-texture format. The <parameter>format</parameter> of the compressed texture
image is selected by the GL implementation that compressed it (see
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>) and should be queried at the time the texture was
compressed with <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexSubImage2D</function> is available only if the GL version is 1.3 or greater.
</para>
<para>
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
<constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is one of these generic compressed internal formats:
<constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>,
<constant>GL_COMPRESSED_RGB</constant>,
<constant>GL_COMPRESSED_RGBA</constant>,
<constant>GL_COMPRESSED_SLUMINANCE</constant>,
<constant>GL_COMPRESSED_SLUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_SRGB</constant>,
<constant>GL_COMPRESSED_SRGBA</constant>, or
<constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image
data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexSubImage2D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if
<parameter>data</parameter> is not encoded in a manner consistent with the extension
specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

293
Source/Bind/Specifications/Docs/glCompressedTexSubImage3D.xml Normal file
View file

@ -0,0 +1,293 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCompressedTexSubImage3D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCompressedTexSubImage3D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCompressedTexSubImage3D</refname>
<refpurpose>specify a three-dimensional texture subimage in a compressed format</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCompressedTexSubImage3D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>yoffset</parameter></paramdef>
<paramdef>GLint <parameter>zoffset</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLsizei <parameter>depth</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_3D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the x direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>yoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the y direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>depth</parameter></term>
<listitem>
<para>
Specifies the depth of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>imageSize</parameter></term>
<listitem>
<para>
Specifies the number of unsigned bytes of image data starting at the
address specified by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the compressed image data in memory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Texturing maps a portion of a specified texture image onto each graphical
primitive for which texturing is enabled. To enable and disable
three-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D</constant>.
</para>
<para>
<function>glCompressedTexSubImage3D</function> redefines a contiguous subregion of an existing three-dimensional
texture image. The texels referenced by <parameter>data</parameter> replace the portion of the
existing texture array with x indices <parameter>xoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and the y indices <parameter>yoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: yoffset + height - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and the z indices <parameter>zoffset</parameter> and
<inlineequation><mml:math>
<!-- eqn: zoffset + depth - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">zoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">depth</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive. This region may not include
any texels outside the range of the texture array as it was originally
specified. It is not an error to specify a subtexture with width of 0,
but such a specification has no effect.
</para>
<para>
<parameter>format</parameter> must be an extension-specified
compressed-texture format. The <parameter>format</parameter> of the compressed texture
image is selected by the GL implementation that compressed it (see
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>) and should be queried at the time the texture was
compressed with <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCompressedTexSubImage3D</function> is available only if the GL version is 1.3 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is one of these generic compressed internal formats:
<constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>,
<constant>GL_COMPRESSED_RGB</constant>,
<constant>GL_COMPRESSED_RGBA</constant>,
<constant>GL_COMPRESSED_SLUMINANCE</constant>,
<constant>GL_COMPRESSED_SLUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_SRGB</constant>,
<constant>GL_COMPRESSED_SRGBA</constant>, or
<constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
the format, dimensions, and contents of the specified compressed image
data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
supported by the specific compressed internal format as specified in the
specific texture compression extension.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexSubImage3D</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
Undefined results, including abnormal program termination, are generated if
<parameter>data</parameter> is not encoded in a manner consistent with the extension
specification defining the internal compression format.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

459
Source/Bind/Specifications/Docs/glConvolutionFilter1D.xml Normal file
View file

@ -0,0 +1,459 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glConvolutionFilter1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glConvolutionFilter1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glConvolutionFilter1D</refname>
<refpurpose>define a one-dimensional convolution filter</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionFilter1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be <constant>GL_CONVOLUTION_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal format of the convolution filter kernel.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, or
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the pixel array referenced by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The format of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_RGB</constant>, and
<constant>GL_RGBA</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
The type of the pixel data in <parameter>data</parameter>.
Symbolic constants
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_BYTE</constant>,
<constant>GL_BITMAP</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Pointer to a one-dimensional array of pixel data that is processed to
build the convolution filter kernel.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glConvolutionFilter1D</function> builds a one-dimensional convolution filter kernel from an array of
pixels.
</para>
<para>
The pixel array specified by <parameter>width</parameter>, <parameter>format</parameter>, <parameter>type</parameter>, and <parameter>data</parameter>
is extracted from memory and
processed just as if <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> were called, but processing
stops after the final expansion to RGBA is completed.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a convolution filter is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
<para>
The R, G, B, and A components of each pixel are next scaled by the four
1D <constant>GL_CONVOLUTION_FILTER_SCALE</constant> parameters and biased by the
four 1D <constant>GL_CONVOLUTION_FILTER_BIAS</constant> parameters.
(The scale and bias parameters are set by <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>
using the <constant>GL_CONVOLUTION_1D</constant> target and the names
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
The parameters themselves are vectors of four values that are applied to red,
green, blue, and alpha, in that order.)
The R, G, B, and A values are not clamped to [0,1] at any time during this
process.
</para>
<para>
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*" />
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in floating-point rather than integer
format.
They form a one-dimensional filter kernel image indexed with coordinate
<emphasis>i</emphasis> such that <emphasis>i</emphasis> starts at 0 and increases from left to right.
Kernel location <emphasis>i</emphasis> is derived from the <emphasis>i</emphasis>th pixel, counting from 0.
</para>
<para>
Note that after a convolution is performed, the resulting color
components are also scaled by their corresponding
<constant>GL_POST_CONVOLUTION_c_SCALE</constant> parameters and biased by their
corresponding <constant>GL_POST_CONVOLUTION_c_BIAS</constant> parameters (where
<emphasis>c</emphasis> takes on the values <emphasis role="bold">RED</emphasis>, <emphasis role="bold">GREEN</emphasis>, <emphasis role="bold">BLUE</emphasis>, and
<emphasis role="bold">ALPHA</emphasis>).
These parameters are set by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glConvolutionFilter1D</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_CONVOLUTION_1D</constant>.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_1D</constant> and name
<constant>GL_MAX_CONVOLUTION_WIDTH</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is one of
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
and <parameter>type</parameter> is not <constant>GL_RGB</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is one of
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
and <parameter>type</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glConvolutionFilter1D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

478
Source/Bind/Specifications/Docs/glConvolutionFilter2D.xml Normal file
View file

@ -0,0 +1,478 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glConvolutionFilter2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glConvolutionFilter2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glConvolutionFilter2D</refname>
<refpurpose>define a two-dimensional convolution filter</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionFilter2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be <constant>GL_CONVOLUTION_2D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal format of the convolution filter kernel.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, or
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the pixel array referenced by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
The height of the pixel array referenced by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The format of the pixel data in <parameter>data</parameter>.
The allowable values are
<constant>GL_RED</constant>,
<constant>GL_GREEN</constant>,
<constant>GL_BLUE</constant>,
<constant>GL_ALPHA</constant>,
<constant>GL_RGB</constant>,
<constant>GL_BGR</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_BGRA</constant>,
<constant>GL_LUMINANCE</constant>, and
<constant>GL_LUMINANCE_ALPHA</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
The type of the pixel data in <parameter>data</parameter>.
Symbolic constants
<constant>GL_UNSIGNED_BYTE</constant>,
<constant>GL_BYTE</constant>,
<constant>GL_BITMAP</constant>,
<constant>GL_UNSIGNED_SHORT</constant>,
<constant>GL_SHORT</constant>,
<constant>GL_UNSIGNED_INT</constant>,
<constant>GL_INT</constant>,
<constant>GL_FLOAT</constant>,
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Pointer to a two-dimensional array of pixel data that is processed to
build the convolution filter kernel.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glConvolutionFilter2D</function> builds a two-dimensional convolution filter kernel from an array of
pixels.
</para>
<para>
The pixel array specified by <parameter>width</parameter>, <parameter>height</parameter>, <parameter>format</parameter>, <parameter>type</parameter>, and
<parameter>data</parameter> is extracted from memory and processed just as if
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> were called, but processing stops after the final
expansion to RGBA is completed.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a convolution filter is
specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
</para>
<para>
The R, G, B, and A components of each pixel are next scaled by the four
2D <constant>GL_CONVOLUTION_FILTER_SCALE</constant> parameters and biased by the
four 2D <constant>GL_CONVOLUTION_FILTER_BIAS</constant> parameters.
(The scale and bias parameters are set by <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>
using the <constant>GL_CONVOLUTION_2D</constant> target and the names
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
The parameters themselves are vectors of four values that are applied to red,
green, blue, and alpha, in that order.)
The R, G, B, and A values are not clamped to [0,1] at any time during this
process.
</para>
<para>
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in floating-point rather than integer
format.
They form a two-dimensional filter kernel image indexed with coordinates
<emphasis>i</emphasis> and <emphasis>j</emphasis> such that <emphasis>i</emphasis> starts at zero and increases from left
to right, and <emphasis>j</emphasis> starts at zero and increases from bottom to top.
Kernel location <emphasis>i,j</emphasis> is derived from the <emphasis>N</emphasis>th pixel,
where <emphasis>N</emphasis> is <emphasis>i</emphasis>+<emphasis>j</emphasis>*<parameter>width</parameter>.
</para>
<para>
Note that after a convolution is performed, the resulting color
components are also scaled by their corresponding
<constant>GL_POST_CONVOLUTION_c_SCALE</constant> parameters and biased by their
corresponding <constant>GL_POST_CONVOLUTION_c_BIAS</constant> parameters (where
<emphasis>c</emphasis> takes on the values <emphasis role="bold">RED</emphasis>, <emphasis role="bold">GREEN</emphasis>, <emphasis role="bold">BLUE</emphasis>, and
<emphasis role="bold">ALPHA</emphasis>).
These parameters are set by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glConvolutionFilter2D</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_CONVOLUTION_2D</constant>.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_2D</constant> and name
<constant>GL_MAX_CONVOLUTION_WIDTH</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>height</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_2D</constant> and name
<constant>GL_MAX_CONVOLUTION_HEIGHT</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>height</parameter> is one of
<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>height</parameter> is one of
<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glConvolutionFilter2D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

311
Source/Bind/Specifications/Docs/glConvolutionParameter.xml Normal file
View file

@ -0,0 +1,311 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glConvolutionParameter">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glConvolutionParameter</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glConvolutionParameter</refname>
<refpurpose>set convolution parameters</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionParameterf</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLfloat <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionParameteri</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLint <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<para>
</para>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
The target for the convolution parameter.
Must be one of
<constant>GL_CONVOLUTION_1D</constant>,
<constant>GL_CONVOLUTION_2D</constant>, or
<constant>GL_SEPARABLE_2D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
The parameter to be set.
Must be
<constant>GL_CONVOLUTION_BORDER_MODE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
The parameter value.
Must be one of
<constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, <constant>GL_REPLICATE_BORDER</constant>.
</para>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionParameterfv</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLfloat * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glConvolutionParameteriv</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLint * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<para>
</para>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
The target for the convolution parameter.
Must be one of
<constant>GL_CONVOLUTION_1D</constant>,
<constant>GL_CONVOLUTION_2D</constant>, or
<constant>GL_SEPARABLE_2D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
The parameter to be set.
Must be one of
<constant>GL_CONVOLUTION_BORDER_MODE</constant>,
<constant>GL_CONVOLUTION_BORDER_COLOR</constant>,
<constant>GL_CONVOLUTION_FILTER_SCALE</constant>, or
<constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
The parameter value.
If <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_BORDER_MODE</constant>, <parameter>params</parameter>v must be one of
<constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, or <constant>GL_REPLICATE_BORDER</constant>.
Otherwise, must be a vector of four values (for red, green, blue, and alpha,
respectively) to be used for
scaling (when <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_FILTER_SCALE</constant>), or
biasing (when <parameter>pname</parameter>v is <constant>GL_CONVOLUTION_FILTER_BIAS</constant>) a convolution
filter kernel or setting the constant border color (when <parameter>pname</parameter>v is
<constant>GL_CONVOLUTION_BORDER_COLOR</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glConvolutionParameter</function> sets the value of a convolution parameter.
</para>
<para>
<parameter>target</parameter> selects the convolution filter to be affected:
<constant>GL_CONVOLUTION_1D</constant>,
<constant>GL_CONVOLUTION_2D</constant>, or
<constant>GL_SEPARABLE_2D</constant>
for the 1D, 2D, or separable 2D filter, respectively.
</para>
<para>
<parameter>pname</parameter> selects the parameter to be changed.
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>
affect the definition of the convolution filter kernel; see
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry> for details.
In these cases, <parameter>params</parameter>v is an array of four values to be applied to
red, green, blue, and alpha values, respectively. The initial value for
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> is (1, 1, 1, 1), and the initial value
for <constant>GL_CONVOLUTION_FILTER_BIAS</constant> is (0, 0, 0, 0).
</para>
<para>
A <parameter>pname</parameter> value of <constant>GL_CONVOLUTION_BORDER_MODE</constant> controls the
convolution border mode. The accepted modes are:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_REDUCE</constant></term>
<listitem>
<para>
The image resulting from convolution is
smaller than the source image.
If the filter width is
<inlineequation><mml:math><mml:mi mathvariant="italic">Wf</mml:mi></mml:math></inlineequation>
and height is
<inlineequation><mml:math><mml:mi mathvariant="italic">Hf</mml:mi></mml:math></inlineequation>,
and the source image width is
<inlineequation><mml:math><mml:mi mathvariant="italic">Ws</mml:mi></mml:math></inlineequation>
and height is
<inlineequation><mml:math><mml:mi mathvariant="italic">Hs</mml:mi></mml:math></inlineequation>,
then the convolved image width will be
<inlineequation><mml:math>
<!-- eqn: Ws - Wf + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">Ws</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">Wf</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
and height
will be
<inlineequation><mml:math>
<!-- eqn: Hs - Hf + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">Hs</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">Hf</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>.
(If this reduction would generate an image with zero or negative width
and/or height, the output is simply null, with no error generated.)
The coordinates of the image resulting from convolution are zero
through
<inlineequation><mml:math>
<!-- eqn: Ws - Wf:-->
<mml:mrow>
<mml:mi mathvariant="italic">Ws</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">Wf</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
in width and zero through
<inlineequation><mml:math>
<!-- eqn: Hs - Hf:-->
<mml:mrow>
<mml:mi mathvariant="italic">Hs</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">Hf</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
in
height.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_CONSTANT_BORDER</constant></term>
<listitem>
<para>
The image resulting from convolution is the same size as the source image, and
processed as if the source image were surrounded by pixels with their color
specified by the <constant>GL_CONVOLUTION_BORDER_COLOR</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_REPLICATE_BORDER</constant></term>
<listitem>
<para>
The image resulting from convolution is the same size as the source image, and
processed as if the outermost pixel on the border of the source image were
replicated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glConvolutionParameter</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
<para>
In cases where errors can result from the specification of invalid
image dimensions, it is the dimensions after convolution that are
tested, not the dimensions of the source image.
For example, <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> requires power-of-two image size.
When <constant>GL_REDUCE</constant> border mode is in effect,
the source image must be larger than the final power-of-two size
by one less than the size of the 1D filter kernel.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is
<constant>GL_CONVOLUTION_BORDER_MODE</constant> and <parameter>params</parameter> is not one of
<constant>GL_REDUCE</constant>, <constant>GL_CONSTANT_BORDER</constant>, or <constant>GL_REPLICATE_BORDER</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glConvolutionParameter</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

152
Source/Bind/Specifications/Docs/glCopyColorSubTable.xml Normal file
View file

@ -0,0 +1,152 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyColorSubTable">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyColorSubTable</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyColorSubTable</refname>
<refpurpose>respecify a portion of a color table</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyColorSubTable</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLsizei <parameter>start</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be one of
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, or
<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
The starting index of the portion of the color table to be replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
The window coordinates of the left corner of the row of pixels to be
copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The number of table entries to replace.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyColorSubTable</function> is used to respecify a contiguous portion of a color table previously
defined using <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>. The pixels copied from the framebuffer
replace the portion of the existing table from indices <parameter>start</parameter> to
<inlineequation><mml:math>
<!-- eqn: start + x - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">x</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive. This region may not include any
entries outside the range of the color table, as was originally specified.
It is not an error to specify a subtexture with width of 0, but such a
specification has no effect.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyColorSubTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>target</parameter> is not a previously defined
color table.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>target</parameter> is not one of the allowable
values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: start + x > width:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">x</mml:mi>
</mml:mrow>
<mml:mo>&gt;</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:math></inlineequation>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyColorSubTable</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorSubTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyColorTable</refentrytitle></citerefentry>,
<function>glCopyColorSubTable</function>,
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

385
Source/Bind/Specifications/Docs/glCopyColorTable.xml Normal file
View file

@ -0,0 +1,385 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyColorTable">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyColorTable</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyColorTable</refname>
<refpurpose>copy pixels into a color table</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyColorTable</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
The color table target. Must be
<constant>GL_COLOR_TABLE</constant>,
<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
or <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal storage format of the texture image.
Must be one of the following symbolic constants:
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, or
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<listitem>
<para>
The x coordinate of the lower-left corner of the pixel rectangle
to be transferred to the color table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>y</parameter></term>
<listitem>
<para>
The y coordinate of the lower-left corner of the pixel rectangle
to be transferred to the color table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the pixel rectangle.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyColorTable</function> loads a color table with pixels from the current
<constant>GL_READ_BUFFER</constant> (rather than from main memory, as is the case for
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel rectangle with lower-left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>)
having width <parameter>width</parameter> and height 1
is loaded into the color table. If any pixels within
this region are outside the window that is associated with the GL
context, the values obtained for those pixels are undefined.
</para>
<para>
The pixels in the rectangle are processed just as if
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> were called, with <parameter>internalformat</parameter> set to RGBA,
but processing stops after the final conversion to RGBA.
</para>
<para>
The four scale parameters and the four bias parameters that are defined
for the table are then used to scale and bias the R, G, B, and A components
of each pixel. The scale and bias parameters are set by calling
<citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>.
</para>
<para>
Next, the R, G, B, and A values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>. This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*" />
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.5*" align="center"/>
<colspec colwidth="1.5*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Finally, the red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in the color table.
They form a one-dimensional table with indices in the range
<inlineequation><mml:math>
<!-- eqn: [0, width-1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mrow>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>.
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyColorTable</function> is available only if <code>ARB_imaging</code> is returned from calling
<citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry> with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated when <parameter>target</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_TABLE_TOO_LARGE</constant> is generated if the requested color table
is too large to be supported by the implementation.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyColorTable</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

369
Source/Bind/Specifications/Docs/glCopyConvolutionFilter1D.xml Normal file
View file

@ -0,0 +1,369 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyConvolutionFilter1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyConvolutionFilter1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyConvolutionFilter1D</refname>
<refpurpose>copy pixels into a one-dimensional convolution filter</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyConvolutionFilter1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be <constant>GL_CONVOLUTION_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal format of the convolution filter kernel.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, or
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
The window space coordinates of the lower-left coordinate of the
pixel array to copy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the pixel array to copy.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyConvolutionFilter1D</function> defines a one-dimensional convolution filter kernel with pixels
from the current <constant>GL_READ_BUFFER</constant> (rather than from main memory,
as is the case for <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel rectangle with lower-left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>),
width <parameter>width</parameter> and height 1 is used to define
the convolution filter. If any pixels within this region are
outside the window that is associated with the GL context, the
values obtained for those pixels are undefined.
</para>
<para>
The pixels in the rectangle are processed exactly as if <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>
had been called with <emphasis>format</emphasis>
set to RGBA, but the process stops just before final conversion.
The R, G, B, and A components of each pixel are next scaled by the four
1D <constant>GL_CONVOLUTION_FILTER_SCALE</constant> parameters and biased by the
four 1D <constant>GL_CONVOLUTION_FILTER_BIAS</constant> parameters.
(The scale and bias parameters are set by <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>
using the <constant>GL_CONVOLUTION_1D</constant> target and the names
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
The parameters themselves are vectors of four values that are applied to red,
green, blue, and alpha, in that order.)
The R, G, B, and A values are not clamped to [0,1] at any time during this
process.
</para>
<para>
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*" />
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in floating-point rather than integer
format.
</para>
<para>
Pixel ordering is such that lower x screen coordinates correspond to
lower <emphasis>i</emphasis> filter image coordinates.
</para>
<para>
Note that after a convolution is performed, the resulting color
components are also scaled by their corresponding
<constant>GL_POST_CONVOLUTION_c_SCALE</constant> parameters and biased by their
corresponding <constant>GL_POST_CONVOLUTION_c_BIAS</constant> parameters (where
<emphasis>c</emphasis> takes on the values <emphasis role="bold">RED</emphasis>, <emphasis role="bold">GREEN</emphasis>, <emphasis role="bold">BLUE</emphasis>, and
<emphasis role="bold">ALPHA</emphasis>).
These parameters are set by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyConvolutionFilter1D</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_CONVOLUTION_1D</constant>.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_1D</constant> and name
<constant>GL_MAX_CONVOLUTION_WIDTH</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyConvolutionFilter1D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

387
Source/Bind/Specifications/Docs/glCopyConvolutionFilter2D.xml Normal file
View file

@ -0,0 +1,387 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyConvolutionFilter2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyConvolutionFilter2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyConvolutionFilter2D</refname>
<refpurpose>copy pixels into a two-dimensional convolution filter</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyConvolutionFilter2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Must be <constant>GL_CONVOLUTION_2D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
The internal format of the convolution filter kernel.
The allowable values are
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>, or
<constant>GL_RGBA16</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
The window space coordinates of the lower-left coordinate of the
pixel array to copy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the pixel array to copy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
The height of the pixel array to copy.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyConvolutionFilter2D</function> defines a two-dimensional convolution filter kernel with pixels
from the current <constant>GL_READ_BUFFER</constant> (rather than from main memory,
as is the case for <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel rectangle with lower-left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>),
width <parameter>width</parameter> and height <parameter>height</parameter>
is used to define the convolution filter. If any pixels within this
region are
outside the window that is associated with the GL context, the
values obtained for those pixels are undefined.
</para>
<para>
The pixels in the rectangle are processed
exactly as if <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> had been called with <emphasis>format</emphasis>
set to RGBA, but the process stops just before final conversion.
The R, G, B, and A components of each pixel are next scaled by the four
2D <constant>GL_CONVOLUTION_FILTER_SCALE</constant> parameters and biased by the
four 2D <constant>GL_CONVOLUTION_FILTER_BIAS</constant> parameters.
(The scale and bias parameters are set by <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>
using the <constant>GL_CONVOLUTION_2D</constant> target and the names
<constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
The parameters themselves are vectors of four values that are applied to red,
green, blue, and alpha, in that order.)
The R, G, B, and A values are not clamped to [0,1] at any time during this
process.
</para>
<para>
Each pixel is then converted to the internal format specified by
<parameter>internalformat</parameter>.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="7" align="left">
<colspec colwidth="3*"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<colspec colwidth="1.7*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Internal Format
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Red
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Green
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Blue
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Alpha
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Luminance
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Intensity
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_LUMINANCE_ALPHA</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
A
</entry>
<entry align="center">
R
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_INTENSITY</constant>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
R
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGB</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
<row>
<entry align="left">
<constant>GL_RGBA</constant>
</entry>
<entry align="center">
R
</entry>
<entry align="center">
G
</entry>
<entry align="center">
B
</entry>
<entry align="center">
A
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in floating-point rather than integer
format.
</para>
<para>
Pixel ordering is such that lower x screen coordinates correspond to
lower <emphasis>i</emphasis> filter image coordinates, and lower y screen coordinates
correspond to lower <emphasis>j</emphasis> filter image coordinates.
</para>
<para>
Note that after a convolution is performed, the resulting color
components are also scaled by their corresponding
<constant>GL_POST_CONVOLUTION_c_SCALE</constant> parameters and biased by their
corresponding <constant>GL_POST_CONVOLUTION_c_BIAS</constant> parameters (where
<emphasis>c</emphasis> takes on the values <emphasis role="bold">RED</emphasis>, <emphasis role="bold">GREEN</emphasis>, <emphasis role="bold">BLUE</emphasis>, and
<emphasis role="bold">ALPHA</emphasis>).
These parameters are set by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyConvolutionFilter2D</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
is called with an argument of <constant>GL_EXTENSIONS</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
<constant>GL_CONVOLUTION_2D</constant>.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
allowable values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_2D</constant> and name
<constant>GL_MAX_CONVOLUTION_WIDTH</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>height</parameter> is less than zero or greater
than the maximum supported value.
This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
using target <constant>GL_CONVOLUTION_2D</constant> and name
<constant>GL_MAX_CONVOLUTION_HEIGHT</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyConvolutionFilter2D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

609
Source/Bind/Specifications/Docs/glCopyPixels.xml Normal file
View file

@ -0,0 +1,609 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyPixels">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyPixels</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyPixels</refname>
<refpurpose>copy pixels in the frame buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyPixels</function></funcdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specify the dimensions of the rectangular region of pixels to be copied.
Both must be nonnegative.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies whether color values,
depth values,
or stencil values are to be copied.
Symbolic constants
<constant>GL_COLOR</constant>,
<constant>GL_DEPTH</constant>,
and <constant>GL_STENCIL</constant> are accepted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyPixels</function> copies a screen-aligned rectangle of pixels
from the specified frame buffer location to a region relative to the
current raster position.
Its operation is well defined only if the entire pixel source region
is within the exposed portion of the window.
Results of copies from outside the window,
or from regions of the window that are not exposed,
are hardware dependent and undefined.
</para>
<para>
<parameter>x</parameter> and <parameter>y</parameter> specify the window coordinates of
the lower left corner of the rectangular region to be copied.
<parameter>width</parameter> and <parameter>height</parameter> specify the dimensions of the
rectangular region to be copied.
Both <parameter>width</parameter> and <parameter>height</parameter> must not be negative.
</para>
<para>
Several parameters control the processing of the pixel data
while it is being copied.
These parameters are set with three commands:
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>.
This reference page describes the effects on <function>glCopyPixels</function> of most,
but not all, of the parameters specified by these three commands.
</para>
<para>
<function>glCopyPixels</function> copies values from each pixel with the lower left-hand corner at
<inlineequation><mml:math>
<!-- eqn: (x + i, y + j):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">x</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">y</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>
for
<inlineequation><mml:math>
<!-- eqn: 0 <= i < width:-->
<mml:mrow>
<mml:mn>0</mml:mn>
<mml:mo>&lt;=</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: 0 <= j < height:-->
<mml:mrow>
<mml:mn>0</mml:mn>
<mml:mo>&lt;=</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
</mml:mrow>
</mml:math></inlineequation>.
This pixel is said to be the
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
pixel in the
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
row.
Pixels are copied in row order from the lowest to the highest row,
left to right in each row.
</para>
<para>
<parameter>type</parameter> specifies whether color, depth, or stencil data is to be copied.
The details of the transfer for each data type are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_COLOR</constant></term>
<listitem>
<para>
Indices or RGBA colors are read from the buffer currently specified as the
read source buffer (see <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>).
If the GL is in color index mode,
each index that is read from this buffer is converted
to a fixed-point format with an unspecified
number of bits to the right of the binary point.
Each index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits,
and added to <constant>GL_INDEX_OFFSET</constant>.
If <constant>GL_INDEX_SHIFT</constant> is negative,
the shift is to the right.
In either case, zero bits fill otherwise unspecified bit locations in the
result.
If <constant>GL_MAP_COLOR</constant> is true,
the index is replaced with the value that it references in lookup table
<constant>GL_PIXEL_MAP_I_TO_I</constant>.
Whether the lookup replacement of the index is done or not,
the integer part of the index is then ANDed with
<inlineequation><mml:math>
<!-- eqn: 2 sup b -1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
is the number of bits in a color index buffer.
</para>
<para>
If the GL is in RGBA mode,
the red, green, blue, and alpha components of each pixel that is read
are converted to an internal floating-point format with unspecified
precision.
The conversion maps the largest representable component value to 1.0,
and component value 0 to 0.0.
The resulting floating-point color values are then multiplied
by <constant>GL_c_SCALE</constant> and added to <constant>GL_c_BIAS</constant>,
where <emphasis>c</emphasis> is RED, GREEN, BLUE, and ALPHA
for the respective color components.
The results are clamped to the range [0,1].
If <constant>GL_MAP_COLOR</constant> is true,
each color component is scaled by the size of lookup table
<constant>GL_PIXEL_MAP_c_TO_c</constant>,
then replaced by the value that it references in that table.
<emphasis>c</emphasis> is R, G, B, or A.
</para>
<para>
If the <code>ARB_imaging</code> extension is supported, the color values may
be
additionally processed by color-table lookups, color-matrix
transformations, and convolution filters.
</para>
<para>
The GL then converts the resulting indices or RGBA colors to fragments
by attaching the current raster position <emphasis>z</emphasis> coordinate and
texture coordinates to each pixel,
then assigning window coordinates
<inlineequation><mml:math>
<!-- eqn: (x sub r + i , y sub r + j):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>,
where
<inlineequation><mml:math>
<!-- eqn: (x sub r , y sub r):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the current raster position,
and the pixel was the
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
pixel in the
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
row.
These pixel fragments are then treated just like the fragments generated by
rasterizing points, lines, or polygons.
Texture mapping,
fog,
and all the fragment operations are applied before the fragments are written
to the frame buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_DEPTH</constant></term>
<listitem>
<para>
Depth values are read from the depth buffer and
converted directly to an internal floating-point format
with unspecified precision.
The resulting floating-point depth value is then multiplied
by <constant>GL_DEPTH_SCALE</constant> and added to <constant>GL_DEPTH_BIAS</constant>.
The result is clamped to the range [0,1].
</para>
<para>
The GL then converts the resulting depth components to fragments
by attaching the current raster position color or color index and
texture coordinates to each pixel,
then assigning window coordinates
<inlineequation><mml:math>
<!-- eqn: (x sub r + i , y sub r + j):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>,
where
<inlineequation><mml:math>
<!-- eqn: (x sub r , y sub r):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the current raster position,
and the pixel was the
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
pixel in the
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
row.
These pixel fragments are then treated just like the fragments generated by
rasterizing points, lines, or polygons.
Texture mapping,
fog,
and all the fragment operations are applied before the fragments are written
to the frame buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_STENCIL</constant></term>
<listitem>
<para>
Stencil indices are read from the stencil buffer and
converted to an internal fixed-point format
with an unspecified number of bits to the right of the binary point.
Each fixed-point index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits,
and added to <constant>GL_INDEX_OFFSET</constant>.
If <constant>GL_INDEX_SHIFT</constant> is negative,
the shift is to the right.
In either case, zero bits fill otherwise unspecified bit locations in the
result.
If <constant>GL_MAP_STENCIL</constant> is true,
the index is replaced with the value that it references in lookup table
<constant>GL_PIXEL_MAP_S_TO_S</constant>.
Whether the lookup replacement of the index is done or not,
the integer part of the index is then ANDed with
<inlineequation><mml:math>
<!-- eqn: 2 sup b -1:-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:msup>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
is the number of bits in the stencil buffer.
The resulting stencil indices are then written to the stencil buffer
such that the index read from the
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
location of the
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
row
is written to location
<inlineequation><mml:math>
<!-- eqn: (x sub r + i , y sub r + j):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>,
where
<inlineequation><mml:math>
<!-- eqn: (x sub r , y sub r):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the current raster position.
Only the pixel ownership test,
the scissor test,
and the stencil writemask affect these write operations.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The rasterization described thus far assumes pixel zoom factors of 1.0.
If
<citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry> is used to change the
<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
pixel zoom factors,
pixels are converted to fragments as follows.
If
<inlineequation><mml:math>
<!-- eqn: (x sub r, y sub r):-->
<mml:mfenced open="(" close=")">
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math></inlineequation>
is the current raster position,
and a given pixel is in the
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
location in the
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
row of the source
pixel rectangle,
then fragments are generated for pixels whose centers are in the rectangle
with corners at
</para>
<para>
<inlineequation><mml:math>
<!-- eqn: (x sub r + {zoom sub x} i, y sub r + {zoom sub y} j):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">x</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">i</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">y</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>
</para>
<para>
and
</para>
<para>
<inlineequation><mml:math>
<!-- eqn: (x sub r + {zoom sub x} (i + 1), y sub r + {zoom sub y} ( j + 1 )):-->
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">x</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">y</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>
</para>
<para>
where
<inlineequation><mml:math>
<!-- eqn: zoom sub x:-->
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">x</mml:mi>
</mml:msub>
</mml:math></inlineequation>
is the value of <constant>GL_ZOOM_X</constant> and
<inlineequation><mml:math>
<!-- eqn: zoom sub y:-->
<mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
<mml:mi mathvariant="italic">y</mml:mi>
</mml:msub>
</mml:math></inlineequation>
is the value of <constant>GL_ZOOM_Y</constant>.
</para>
</refsect1>
<refsect1 id="examples"><title>Examples</title>
<para>
To copy the color pixel in the lower left corner of the window to the current raster position,
use
</para>
<para>
<programlisting>
glCopyPixels(0, 0, 1, 1, <constant>GL_COLOR</constant>);
</programlisting>
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Modes specified by <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> have no effect on the operation
of <function>glCopyPixels</function>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is <constant>GL_DEPTH</constant>
and there is no depth buffer.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is <constant>GL_STENCIL</constant>
and there is no stencil buffer.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyPixels</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

370
Source/Bind/Specifications/Docs/glCopyTexImage1D.xml Normal file
View file

@ -0,0 +1,370 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexImage1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyTexImage1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyTexImage1D</refname>
<refpurpose>copy pixels into a 1D texture image</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyTexImage1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLint <parameter>border</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
Specifies the internal format of the texture.
Must be one of the following symbolic constants:
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>,
<constant>GL_COMPRESSED_RGB</constant>,
<constant>GL_COMPRESSED_RGBA</constant>,
<constant>GL_DEPTH_COMPONENT</constant>,
<constant>GL_DEPTH_COMPONENT16</constant>,
<constant>GL_DEPTH_COMPONENT24</constant>,
<constant>GL_DEPTH_COMPONENT32</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_RGB</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>,
<constant>GL_RGBA16</constant>,
<constant>GL_SLUMINANCE</constant>,
<constant>GL_SLUMINANCE8</constant>,
<constant>GL_SLUMINANCE_ALPHA</constant>,
<constant>GL_SLUMINANCE8_ALPHA8</constant>,
<constant>GL_SRGB</constant>,
<constant>GL_SRGB8</constant>,
<constant>GL_SRGB_ALPHA</constant>, or
<constant>GL_SRGB8_ALPHA8</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the left corner
of the row of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture image.
Must be 0 or
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
The height of the texture image is 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>border</parameter></term>
<listitem>
<para>
Specifies the width of the border.
Must be either 0 or 1.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyTexImage1D</function> defines a one-dimensional texture image with pixels from the current
<constant>GL_READ_BUFFER</constant>.
</para>
<para>
The screen-aligned pixel row with left corner at
<inlineequation><mml:math>
<!-- eqn: (x, y):-->
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">y</mml:mi>
</mml:mfenced>
</mml:math></inlineequation>
and with a length of
<inlineequation><mml:math>
<!-- eqn: width + 2 ( border ):-->
<mml:mrow>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
defines the texture array
at the mipmap level specified by <parameter>level</parameter>.
<parameter>internalformat</parameter> specifies the internal format of the texture array.
</para>
<para>
The pixels in the row are processed exactly as if
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
final conversion.
At this point all pixel component values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
and then converted to the texture's internal format for storage in the texel
array.
</para>
<para>
Pixel ordering is such that lower
<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
screen coordinates correspond to
lower texture coordinates.
</para>
<para>
If any of the pixels within the specified row of the current
<constant>GL_READ_BUFFER</constant> are outside the window associated with the current
rendering context, then the values obtained for those pixels are undefined.
</para>
<para>
<function>glCopyTexImage1D</function> defines a one-dimensional texture image with pixels from the current
<constant>GL_READ_BUFFER</constant>.
</para>
<para>
When <parameter>internalformat</parameter> is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. In this case, the <function>glPixelMap</function> function can be used to accomplish the conversion.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyTexImage1D</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
Texturing has no effect in color index mode.
</para>
<para>
1, 2, 3, and 4 are not accepted values for <parameter>internalformat</parameter>.
</para>
<para>
An image with 0 width indicates a NULL texture.
</para>
<para>
When the <code>ARB_imaging</code> extension is supported, the RGBA components copied from the framebuffer may be processed by the imaging pipeline. See <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
</para>
<para>
<constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
<constant>GL_DEPTH_COMPONENT24</constant>, and <constant>GL_DEPTH_COMPONENT32</constant> are available only
if the GL version is 1.4 or greater.
</para>
<para>
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the <constant>GL_ARB_texture_non_power_of_two</constant> extension.
</para>
<para>
The
<constant>GL_SRGB</constant>,
<constant>GL_SRGB8</constant>,
<constant>GL_SRGB_ALPHA</constant>,
<constant>GL_SRGB8_ALPHA8</constant>,
<constant>GL_SLUMINANCE</constant>,
<constant>GL_SLUMINANCE8</constant>,
<constant>GL_SLUMINANCE_ALPHA</constant>, and
<constant>GL_SLUMINANCE8_ALPHA8</constant>
internal formats are only available if the GL version is 2.1 or greater. See <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details about sRGB conversion.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable values.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
than
<inlineequation><mml:math>
<!-- eqn: log sub 2 max:-->
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">max</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalformat</parameter> is not an allowable value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0 or greater than
2 + <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if non-power-of-two textures are not supported and the <parameter>width</parameter> cannot be represented as
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer value of <emphasis>n</emphasis>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexImage1D</function> is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>internalformat</parameter> is
<constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
<constant>GL_DEPTH_COMPONENT24</constant>, or <constant>GL_DEPTH_COMPONENT32</constant> and there is no depth
buffer.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

432
Source/Bind/Specifications/Docs/glCopyTexImage2D.xml Normal file
View file

@ -0,0 +1,432 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexImage2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyTexImage2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyTexImage2D</refname>
<refpurpose>copy pixels into a 2D texture image</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyTexImage2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLint <parameter>border</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>internalformat</parameter></term>
<listitem>
<para>
Specifies the internal format of the texture.
Must be one of the following symbolic constants:
<constant>GL_ALPHA</constant>,
<constant>GL_ALPHA4</constant>,
<constant>GL_ALPHA8</constant>,
<constant>GL_ALPHA12</constant>,
<constant>GL_ALPHA16</constant>,
<constant>GL_COMPRESSED_ALPHA</constant>,
<constant>GL_COMPRESSED_LUMINANCE</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
<constant>GL_COMPRESSED_INTENSITY</constant>,
<constant>GL_COMPRESSED_RGB</constant>,
<constant>GL_COMPRESSED_RGBA</constant>,
<constant>GL_DEPTH_COMPONENT</constant>,
<constant>GL_DEPTH_COMPONENT16</constant>,
<constant>GL_DEPTH_COMPONENT24</constant>,
<constant>GL_DEPTH_COMPONENT32</constant>,
<constant>GL_LUMINANCE</constant>,
<constant>GL_LUMINANCE4</constant>,
<constant>GL_LUMINANCE8</constant>,
<constant>GL_LUMINANCE12</constant>,
<constant>GL_LUMINANCE16</constant>,
<constant>GL_LUMINANCE_ALPHA</constant>,
<constant>GL_LUMINANCE4_ALPHA4</constant>,
<constant>GL_LUMINANCE6_ALPHA2</constant>,
<constant>GL_LUMINANCE8_ALPHA8</constant>,
<constant>GL_LUMINANCE12_ALPHA4</constant>,
<constant>GL_LUMINANCE12_ALPHA12</constant>,
<constant>GL_LUMINANCE16_ALPHA16</constant>,
<constant>GL_INTENSITY</constant>,
<constant>GL_INTENSITY4</constant>,
<constant>GL_INTENSITY8</constant>,
<constant>GL_INTENSITY12</constant>,
<constant>GL_INTENSITY16</constant>,
<constant>GL_RGB</constant>,
<constant>GL_R3_G3_B2</constant>,
<constant>GL_RGB4</constant>,
<constant>GL_RGB5</constant>,
<constant>GL_RGB8</constant>,
<constant>GL_RGB10</constant>,
<constant>GL_RGB12</constant>,
<constant>GL_RGB16</constant>,
<constant>GL_RGBA</constant>,
<constant>GL_RGBA2</constant>,
<constant>GL_RGBA4</constant>,
<constant>GL_RGB5_A1</constant>,
<constant>GL_RGBA8</constant>,
<constant>GL_RGB10_A2</constant>,
<constant>GL_RGBA12</constant>,
<constant>GL_RGBA16</constant>,
<constant>GL_SLUMINANCE</constant>,
<constant>GL_SLUMINANCE8</constant>,
<constant>GL_SLUMINANCE_ALPHA</constant>,
<constant>GL_SLUMINANCE8_ALPHA8</constant>,
<constant>GL_SRGB</constant>,
<constant>GL_SRGB8</constant>,
<constant>GL_SRGB_ALPHA</constant>, or
<constant>GL_SRGB8_ALPHA8</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture image.
Must be 0 or
<inlineequation><mml:math>
<!-- eqn: 2 sup n + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture image.
Must be 0 or
<inlineequation><mml:math>
<!-- eqn: 2 sup m + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>border</parameter></term>
<listitem>
<para>
Specifies the width of the border.
Must be either 0 or 1.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyTexImage2D</function> defines a two-dimensional texture image, or cube-map texture image
with pixels from the current
<constant>GL_READ_BUFFER</constant>.
</para>
<para>
The screen-aligned pixel rectangle with lower left corner at (<parameter>x</parameter>,
<parameter>y</parameter>) and with a width of
<inlineequation><mml:math>
<!-- eqn: width + 2 ( border ):-->
<mml:mrow>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
and a height of
<inlineequation><mml:math>
<!-- eqn: height + 2 ( border ):-->
<mml:mrow>
<mml:mi mathvariant="italic">height</mml:mi>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
defines the texture array
at the mipmap level specified by <parameter>level</parameter>.
<parameter>internalformat</parameter> specifies the internal format of the texture array.
</para>
<para>
The pixels in the rectangle are processed exactly as if
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
final conversion.
At this point all pixel component values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
and then converted to the texture's internal format for storage in the texel
array.
</para>
<para>
Pixel ordering is such that lower
<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
screen coordinates correspond to
lower
<inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">t</mml:mi></mml:math></inlineequation>
texture coordinates.
</para>
<para>
If any of the pixels within the specified rectangle of the current
<constant>GL_READ_BUFFER</constant> are outside the window associated with the current
rendering context, then the values obtained for those pixels are undefined.
</para>
<para>
When <parameter>internalformat</parameter> is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. In this case, the <function>glPixelMap</function> function can be used to accomplish the conversion.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyTexImage2D</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
Texturing has no effect in color index mode.
</para>
<para>
1, 2, 3, and 4 are not accepted values for <parameter>internalformat</parameter>.
</para>
<para>
An image with height or width of 0 indicates a NULL texture.
</para>
<para>
When the <code>ARB_imaging</code> extension is supported, the RGBA components read from the framebuffer may be processed by the imaging pipeline. See <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
</para>
<para>
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
<constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
or greater.
</para>
<para>
<constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>, <constant>GL_DEPTH_COMPONENT24</constant>,
and <constant>GL_DEPTH_COMPONENT32</constant> are available only if the GL version is 1.4
or greater.
</para>
<para>
The
<constant>GL_SRGB</constant>,
<constant>GL_SRGB8</constant>,
<constant>GL_SRGB_ALPHA</constant>,
<constant>GL_SRGB8_ALPHA8</constant>,
<constant>GL_SLUMINANCE</constant>,
<constant>GL_SLUMINANCE8</constant>,
<constant>GL_SLUMINANCE_ALPHA</constant>, and
<constant>GL_SLUMINANCE8_ALPHA8</constant>
internal formats are only available if the GL version is 2.1 or greater. See <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> for specific details about sRGB conversion.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
than
<inlineequation><mml:math>
<!-- eqn: log sub 2 max:-->
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">max</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0
or greater than
2 + <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if non-power-of-two textures are not supported and the <parameter>width</parameter> or <parameter>depth</parameter> cannot be represented as
<inlineequation><mml:math>
<!-- eqn: 2 sup k + 2 ( border ):-->
<mml:mrow>
<mml:msup><mml:mn>2</mml:mn>
<mml:mi mathvariant="italic">k</mml:mi>
</mml:msup>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">border</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
for some integer
<inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalformat</parameter> is not an
accepted format.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexImage2D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>internalformat</parameter> is
<constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
<constant>GL_DEPTH_COMPONENT24</constant>, or <constant>GL_DEPTH_COMPONENT32</constant> and there is no depth
buffer.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

268
Source/Bind/Specifications/Docs/glCopyTexSubImage1D.xml Normal file
View file

@ -0,0 +1,268 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexSubImage1D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyTexSubImage1D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyTexSubImage1D</refname>
<refpurpose>copy a one-dimensional texture subimage</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyTexSubImage1D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<para>
</para>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_1D</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies the texel offset within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the left corner
of the row of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyTexSubImage1D</function> replaces a portion of a one-dimensional
texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel row with left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>), and with
length <parameter>width</parameter> replaces the portion of the
texture array with x indices <parameter>xoffset</parameter> through
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive. The destination in the texture array may not
include any texels outside the texture array as it was
originally specified.
</para>
<para>
The pixels in the row are processed exactly as if
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
final conversion.
At this point, all pixel component values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
and then converted to the texture's internal format for storage in the texel
array.
</para>
<para>
It is not an error to specify a subtexture with zero width, but
such a specification has no effect.
If any of the pixels within the specified row of the current
<constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
rendering context, then the values obtained for those pixels are undefined.
</para>
<para>
No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
or <emphasis>border</emphasis> parameters of the specified texture
array or to texel values outside the specified subregion.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyTexSubImage1D</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
Texturing has no effect in color index mode.
</para>
<para>
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
</para>
<para>
When the <code>ARB_imaging</code> extension is supported, the RGBA components
copied from the framebuffer may be processed by the imaging pipeline. See
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_1D</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry> operation.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if
<inlineequation><mml:math>
<!-- eqn: level > log sub 2(max):-->
<mml:mrow>
<mml:mi mathvariant="italic">level</mml:mi>
<mml:mo>&gt;</mml:mo>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">max</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: xoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
or
<inlineequation><mml:math>
<!-- eqn: (xoffset + width) > (w-b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">w</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_WIDTH</constant> and
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_BORDER</constant>
of the texture image being modified.
Note that
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
includes twice the border width.
</para>
<para>
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

370
Source/Bind/Specifications/Docs/glCopyTexSubImage2D.xml Normal file
View file

@ -0,0 +1,370 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexSubImage2D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyTexSubImage2D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyTexSubImage2D</refname>
<refpurpose>copy a two-dimensional texture subimage</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyTexSubImage2D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>yoffset</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<para>
</para>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the x direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>yoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the y direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture subimage.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyTexSubImage2D</function> replaces a rectangular portion of a two-dimensional texture image or
cube-map texture image with pixels from the current <constant>GL_READ_BUFFER</constant>
(rather than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel rectangle with lower left corner at
<inlineequation><mml:math>
<!-- eqn: (x, y):-->
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">x</mml:mi>
<mml:mi mathvariant="italic">y</mml:mi>
</mml:mfenced>
</mml:math></inlineequation>
and with
width <parameter>width</parameter> and height <parameter>height</parameter> replaces the portion of the
texture array with x indices <parameter>xoffset</parameter> through
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive, and y indices <parameter>yoffset</parameter> through
<inlineequation><mml:math>
<!-- eqn: yoffset + height - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive, at the mipmap level specified by <parameter>level</parameter>.
</para>
<para>
The pixels in the rectangle are processed exactly as if
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
final conversion.
At this point, all pixel component values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
and then converted to the texture's internal format for storage in the texel
array.
</para>
<para>
The destination rectangle in the texture array may not include any texels
outside the texture array as it was originally specified.
It is not an error to specify a subtexture with zero width or height, but
such a specification has no effect.
</para>
<para>
If any of the pixels within the specified rectangle of the current
<constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
rendering context, then the values obtained for those pixels are undefined.
</para>
<para>
No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
<emphasis>height</emphasis>, or <emphasis>border</emphasis> parameters of the specified texture
array or to texel values outside the specified subregion.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyTexSubImage2D</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
<constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
or greater.
</para>
<para>
Texturing has no effect in color index mode.
</para>
<para>
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
</para>
<para>
When the <code>ARB_imaging</code> extension is supported, the RGBA components
read from the framebuffer may be processed by the imaging pipeline. See
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
<constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not been
defined by a previous <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry> operation.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if
<inlineequation><mml:math>
<!-- eqn: level > log sub 2(max):-->
<mml:mrow>
<mml:mi mathvariant="italic">level</mml:mi>
<mml:mo>&gt;</mml:mo>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">max</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: xoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: (xoffset + width) > (w - b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">w</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: yoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
or
<inlineequation><mml:math>
<!-- eqn: (yoffset + height) > (h - b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">h</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_WIDTH</constant>,
<inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_HEIGHT</constant>,
and
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_BORDER</constant>
of the texture image being modified.
Note that
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
include twice the border width.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexSubImage2D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

385
Source/Bind/Specifications/Docs/glCopyTexSubImage3D.xml Normal file
View file

@ -0,0 +1,385 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexSubImage3D">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCopyTexSubImage3D</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCopyTexSubImage3D</refname>
<refpurpose>copy a three-dimensional texture subimage</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCopyTexSubImage3D</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>yoffset</parameter></paramdef>
<paramdef>GLint <parameter>zoffset</parameter></paramdef>
<paramdef>GLint <parameter>x</parameter></paramdef>
<paramdef>GLint <parameter>y</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<para>
</para>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target texture.
Must be <constant>GL_TEXTURE_3D</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the x direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>yoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the y direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>zoffset</parameter></term>
<listitem>
<para>
Specifies a texel offset in the z direction within the texture array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>x</parameter></term>
<term><parameter>y</parameter></term>
<listitem>
<para>
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
Specifies the width of the texture subimage.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
Specifies the height of the texture subimage.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCopyTexSubImage3D</function> replaces a rectangular portion of a three-dimensional
texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>).
</para>
<para>
The screen-aligned pixel rectangle with lower left corner at
(<parameter>x</parameter>,\ <parameter>y</parameter>) and with
width <parameter>width</parameter> and height <parameter>height</parameter> replaces the portion of the
texture array with x indices <parameter>xoffset</parameter> through
<inlineequation><mml:math>
<!-- eqn: xoffset + width - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive, and y indices <parameter>yoffset</parameter> through
<inlineequation><mml:math>
<!-- eqn: yoffset + height - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
inclusive, at z index <parameter>zoffset</parameter> and at the mipmap level specified by <parameter>level</parameter>.
</para>
<para>
The pixels in the rectangle are processed exactly as if
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
final conversion.
At this point, all pixel component values are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
and then converted to the texture's internal format for storage in the texel
array.
</para>
<para>
The destination rectangle in the texture array may not include any texels
outside the texture array as it was originally specified.
It is not an error to specify a subtexture with zero width or height, but
such a specification has no effect.
</para>
<para>
If any of the pixels within the specified rectangle of the current
<constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
rendering context, then the values obtained for those pixels are undefined.
</para>
<para>
No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
<emphasis>height</emphasis>, <emphasis>depth</emphasis>, or <emphasis>border</emphasis> parameters of the specified texture
array or to texel values outside the specified subregion.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glCopyTexSubImage3D</function> is available only if the GL version is 1.2 or greater.
</para>
<para>
Texturing has no effect in color index mode.
</para>
<para>
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
</para>
<para>
When the <code>ARB_imaging</code> extension is supported, the RGBA components
copied from the framebuffer may be processed by the imaging pipeline, as
if they were a two-dimensional texture. See <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> for
specific details.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_3D</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
been defined by a previous <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> operation.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> may be generated if
<inlineequation><mml:math>
<!-- eqn: level > log sub 2(max):-->
<mml:mrow>
<mml:mi mathvariant="italic">level</mml:mi>
<mml:mo>&gt;</mml:mo>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">max</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
is the returned value of <constant>GL_MAX_3D_TEXTURE_SIZE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: xoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: (xoffset + width) > (w - b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">xoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">width</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">w</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: yoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: (yoffset + height) > (h - b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">yoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">height</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">h</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: zoffset < -b:-->
<mml:mrow>
<mml:mi mathvariant="italic">zoffset</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>,
or
<inlineequation><mml:math>
<!-- eqn: (zoffset + 1) > (d - b):-->
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">zoffset</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo>&gt;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">d</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">b</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>,
where
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_WIDTH</constant>,
<inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_HEIGHT</constant>,
<inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_DEPTH</constant>,
and
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
is the <constant>GL_TEXTURE_BORDER</constant>
of the texture image being modified.
Note that
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>,
and
<inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
include twice the border width.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexSubImage3D</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

127
Source/Bind/Specifications/Docs/glCreateProgram.xml Normal file
View file

@ -0,0 +1,127 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCreateProgram">
<refmeta>
<refentrytitle>glCreateProgram</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCreateProgram</refname>
<refpurpose>Creates a program object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>GLuint <function>glCreateProgram</function></funcdef>
<paramdef><parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="description"><title>Description</title>
<para><function>glCreateProgram</function> creates an empty
program object and returns a non-zero value by which it can be
referenced. A program object is an object to which shader
objects can be attached. This provides a mechanism to specify
the shader objects that will be linked to create a program. It
also provides a means for checking the compatibility of the
shaders that will be used to create a program (for instance,
checking the compatibility between a vertex shader and a
fragment shader). When no longer needed as part of a program
object, shader objects can be detached.</para>
<para>One or more executables are created in a program object by
successfully attaching shader objects to it with
<citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
successfully compiling the shader objects with
<citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
and successfully linking the program object with
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>.
These executables are made part of current state when
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>
is called. Program objects can be deleted by calling
<citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>.
The memory associated with the program object will be deleted
when it is no longer part of current rendering state for any
context.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glCreateProgram</function> is available only if
the GL version is 2.0 or greater.</para>
<para>Like display lists and texture objects, the name space for
program objects may be shared across a set of contexts, as long
as the server sides of the contexts share the same address
space. If the name space is shared across contexts, any attached
objects and the data associated with those attached objects are
shared as well.</para>
<para>Applications are responsible for providing the
synchronization across API calls when objects are accessed from
different execution threads.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>This function returns 0 if an error occurs creating the program object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glCreateProgram</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with the argument <constant>GL_CURRENT_PROGRAM</constant></para>
<para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
with a valid program object and the index of an active attribute
variable</para>
<para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
with a valid program object and the index of an active uniform
variable</para>
<para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
with a valid program object</para>
<para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
with a valid program object and the name of an attribute
variable</para>
<para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
with a valid program object and the parameter to be queried</para>
<para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
with a valid program object</para>
<para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
with a valid program object and the location of a uniform
variable</para>
<para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
with a valid program object and the name of a uniform
variable</para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

111
Source/Bind/Specifications/Docs/glCreateShader.xml Normal file
View file

@ -0,0 +1,111 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCreateShader">
<refmeta>
<refentrytitle>glCreateShader</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCreateShader</refname>
<refpurpose>Creates a shader object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>GLuint <function>glCreateShader</function></funcdef>
<paramdef>GLenum <parameter>shaderType</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>shaderType</parameter></term>
<listitem>
<para>Specifies the type of shader to be created.
Must be either <constant>GL_VERTEX_SHADER</constant>
or <constant>GL_FRAGMENT_SHADER</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glCreateShader</function> creates an empty
shader object and returns a non-zero value by which it can be
referenced. A shader object is used to maintain the source code
strings that define a shader. <parameter>shaderType</parameter>
indicates the type of shader to be created. Two types of shaders
are supported. A shader of type
<constant>GL_VERTEX_SHADER</constant> is a shader that is
intended to run on the programmable vertex processor and replace
the fixed functionality vertex processing in OpenGL. A shader of
type <constant>GL_FRAGMENT_SHADER</constant> is a shader that is
intended to run on the programmable fragment processor and
replace the fixed functionality fragment processing in
OpenGL.</para>
<para>When created, a shader object's
<constant>GL_SHADER_TYPE</constant> parameter is set to either
<constant>GL_VERTEX_SHADER</constant> or
<constant>GL_FRAGMENT_SHADER</constant>, depending on the value
of <parameter>shaderType</parameter>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glCreateShader</function> is available only if
the GL version is 2.0 or greater.</para>
<para>Like display lists and texture objects, the name space for
shader objects may be shared across a set of contexts, as long
as the server sides of the contexts share the same address
space. If the name space is shared across contexts, any attached
objects and the data associated with those attached objects are
shared as well.</para>
<para>Applications are responsible for providing the
synchronization across API calls when objects are accessed from
different execution threads.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>This function returns 0 if an error occurs creating the
shader object.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if
<parameter>shaderType</parameter> is not an accepted value.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glCreateShader</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with a valid shader object and the parameter to be queried</para>
<para><citerefentry><refentrytitle>glGetShaderInfoLog</refentrytitle></citerefentry>
with a valid shader object</para>
<para><citerefentry><refentrytitle>glGetShaderSource</refentrytitle></citerefentry>
with a valid shader object</para>
<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glShaderSource</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

99
Source/Bind/Specifications/Docs/glCullFace.xml Normal file
View file

@ -0,0 +1,99 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCullFace">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glCullFace</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glCullFace</refname>
<refpurpose>specify whether front- or back-facing facets can be culled</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glCullFace</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies whether front- or back-facing facets are candidates for culling.
Symbolic constants
<constant>GL_FRONT</constant>, <constant>GL_BACK</constant>, and <constant>GL_FRONT_AND_BACK</constant> are accepted.
The initial value is <constant>GL_BACK</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glCullFace</function> specifies whether front- or back-facing facets are culled
(as specified by <emphasis>mode</emphasis>) when facet culling is enabled. Facet
culling is initially disabled.
To enable and disable facet culling, call the
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> commands
with the argument <constant>GL_CULL_FACE</constant>.
Facets include triangles,
quadrilaterals,
polygons, and
rectangles.
</para>
<para>
<citerefentry><refentrytitle>glFrontFace</refentrytitle></citerefentry> specifies which of the clockwise and counterclockwise facets
are front-facing and back-facing.
See <citerefentry><refentrytitle>glFrontFace</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
If <parameter>mode</parameter> is <constant>GL_FRONT_AND_BACK</constant>, no facets are drawn, but other
primitives such as points and lines are drawn.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glCullFace</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_CULL_FACE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CULL_FACE_MODE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFrontFace</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

96
Source/Bind/Specifications/Docs/glDeleteBuffers.xml Normal file
View file

@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteBuffers">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDeleteBuffers</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteBuffers</refname>
<refpurpose>delete named buffer objects</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteBuffers</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLuint * <parameter>buffers</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of buffer objects to be deleted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffers</parameter></term>
<listitem>
<para>
Specifies an array of buffer objects to be deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDeleteBuffers</function> deletes <parameter>n</parameter> buffer objects named by the elements of the array <parameter>buffers</parameter>.
After a buffer object is deleted, it has no contents,
and its name is free for reuse (for example by <citerefentry><refentrytitle>glGenBuffers</refentrytitle></citerefentry>).
If a buffer object that is currently bound is deleted, the binding reverts
to 0 (the absence of any buffer object, which reverts to client memory usage).
</para>
<para>
<function>glDeleteBuffers</function> silently ignores 0's and names that do not correspond to
existing buffer objects.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDeleteBuffers</function> is available only if the GL version is 1.5 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDeleteBuffers</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

108
Source/Bind/Specifications/Docs/glDeleteLists.xml Normal file
View file

@ -0,0 +1,108 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteLists">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDeleteLists</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteLists</refname>
<refpurpose>delete a contiguous group of display lists</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteLists</function></funcdef>
<paramdef>GLuint <parameter>list</parameter></paramdef>
<paramdef>GLsizei <parameter>range</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>list</parameter></term>
<listitem>
<para>
Specifies the integer name of the first display list to delete.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>range</parameter></term>
<listitem>
<para>
Specifies the number of display lists to delete.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDeleteLists</function> causes a contiguous group of display lists to be deleted.
<parameter>list</parameter> is the name of the first display list to be deleted,
and <parameter>range</parameter> is the number of display lists to delete.
All display lists
<inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
with
<inlineequation><mml:math>
<!-- eqn: list <= d <= list + range - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">list</mml:mi>
<mml:mo>&lt;=</mml:mo>
<mml:mi mathvariant="italic">d</mml:mi>
<mml:mo>&lt;=</mml:mo>
<mml:mrow>
<mml:mi mathvariant="italic">list</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">range</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mrow>
</mml:math></inlineequation>
are deleted.
</para>
<para>
All storage locations allocated to the specified display lists are freed,
and the names are available for reuse at a later time.
Names within the range that do not have an associated display list are ignored.
If <parameter>range</parameter> is 0, nothing happens.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>range</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDeleteLists</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

96
Source/Bind/Specifications/Docs/glDeleteProgram.xml Normal file
View file

@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteProgram">
<refmeta>
<refentrytitle>glDeleteProgram</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteProgram</refname>
<refpurpose>Deletes a program object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteProgram</function></funcdef>
<paramdef>GLuint <parameter>program</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>program</parameter></term>
<listitem>
<para>Specifies the program object to be
deleted.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glDeleteProgram</function> frees the memory and
invalidates the name associated with the program object
specified by <parameter>program.</parameter> This command
effectively undoes the effects of a call to
<citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>.</para>
<para>If a program object is in use as part of current rendering
state, it will be flagged for deletion, but it will not be
deleted until it is no longer part of current state for any
rendering context. If a program object to be deleted has shader
objects attached to it, those shader objects will be
automatically detached but not deleted unless they have already
been flagged for deletion by a previous call to
<citerefentry><refentrytitle>glDeleteShader</refentrytitle></citerefentry>.
A value of 0 for <parameter>program</parameter> will be silently
ignored.</para>
<para>To determine whether a program object has been flagged for
deletion, call
<citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and
<constant>GL_DELETE_STATUS</constant>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glDeleteProgram</function> is available only if
the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>program</parameter> is not a value generated by
OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glDeleteProgram</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_CURRENT_PROGRAM</constant></para>
<para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and
<constant>GL_DELETE_STATUS</constant></para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

101
Source/Bind/Specifications/Docs/glDeleteQueries.xml Normal file
View file

@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteQueries">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDeleteQueries</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteQueries</refname>
<refpurpose>delete named query objects</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteQueries</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLuint * <parameter>ids</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of query objects to be deleted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ids</parameter></term>
<listitem>
<para>
Specifies an array of query objects to be deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDeleteQueries</function> deletes <parameter>n</parameter> query objects named by the elements of the array <parameter>ids</parameter>.
After a query object is deleted, it has no contents,
and its name is free for reuse (for example by <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>).
</para>
<para>
<function>glDeleteQueries</function> silently ignores 0's and names that do not correspond to
existing query objects.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDeleteQueries</function> is available only if the GL version is 1.5 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDeleteQueries</function> is executed
between the execution of <citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDeleteQueries</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsQuery</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

92
Source/Bind/Specifications/Docs/glDeleteShader.xml Normal file
View file

@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteShader">
<refmeta>
<refentrytitle>glDeleteShader</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteShader</refname>
<refpurpose>Deletes a shader object</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteShader</function></funcdef>
<paramdef>GLuint <parameter>shader</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>shader</parameter></term>
<listitem>
<para>Specifies the shader object to be deleted.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glDeleteShader</function> frees the memory and
invalidates the name associated with the shader object specified
by <parameter>shader</parameter>. This command effectively
undoes the effects of a call to
<citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>.</para>
<para>If a shader object to be deleted is attached to a program
object, it will be flagged for deletion, but it will not be
deleted until it is no longer attached to any program object,
for any rendering context (i.e., it must be detached from
wherever it was attached before it will be deleted). A value of
0 for <parameter>shader</parameter> will be silently
ignored.</para>
<para>To determine whether an object has been flagged for
deletion, call
<citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with arguments <parameter>shader</parameter> and
<constant>GL_DELETE_STATUS</constant>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glDeleteShader</function> is available only if
the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>shader</parameter> is not a value generated by
OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glDeleteShader</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
with the program object to be queried</para>
<para><citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with arguments <parameter>shader</parameter> and
<constant>GL_DELETE_STATUS</constant></para>
<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

104
Source/Bind/Specifications/Docs/glDeleteTextures.xml Normal file
View file

@ -0,0 +1,104 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDeleteTextures">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDeleteTextures</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDeleteTextures</refname>
<refpurpose>delete named textures</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDeleteTextures</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLuint * <parameter>textures</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of textures to be deleted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>textures</parameter></term>
<listitem>
<para>
Specifies an array of textures to be deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDeleteTextures</function> deletes <parameter>n</parameter> textures named by the elements of the array <parameter>textures</parameter>.
After a texture is deleted, it has no contents or dimensionality,
and its name is free for reuse (for example by <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>).
If a texture that is currently bound is deleted, the binding reverts
to 0 (the default texture).
</para>
<para>
<function>glDeleteTextures</function> silently ignores 0's and names that do not correspond to
existing textures.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDeleteTextures</function> is available only if the GL version is 1.1 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDeleteTextures</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsTexture</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glAreTexturesResident</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPrioritizeTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

173
Source/Bind/Specifications/Docs/glDepthFunc.xml Normal file
View file

@ -0,0 +1,173 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDepthFunc">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDepthFunc</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDepthFunc</refname>
<refpurpose>specify the value used for depth buffer comparisons</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDepthFunc</function></funcdef>
<paramdef>GLenum <parameter>func</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>func</parameter></term>
<listitem>
<para>
Specifies the depth comparison function.
Symbolic constants
<constant>GL_NEVER</constant>,
<constant>GL_LESS</constant>,
<constant>GL_EQUAL</constant>,
<constant>GL_LEQUAL</constant>,
<constant>GL_GREATER</constant>,
<constant>GL_NOTEQUAL</constant>,
<constant>GL_GEQUAL</constant>, and
<constant>GL_ALWAYS</constant> are accepted.
The initial value is <constant>GL_LESS</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDepthFunc</function> specifies the function used to compare each incoming pixel depth value
with the depth value present in the depth buffer.
The comparison is performed only if depth testing is enabled.
(See <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> of <constant>GL_DEPTH_TEST</constant>.)
</para>
<para>
<parameter>func</parameter> specifies the conditions under which the pixel will be drawn.
The comparison functions are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_NEVER</constant></term>
<listitem>
<para>
Never passes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LESS</constant></term>
<listitem>
<para>
Passes if the incoming depth value is less than the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_EQUAL</constant></term>
<listitem>
<para>
Passes if the incoming depth value is equal to the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming depth value is less than or equal to
the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_GREATER</constant></term>
<listitem>
<para>
Passes if the incoming depth value is greater than the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_NOTEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming depth value is not equal to the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_GEQUAL</constant></term>
<listitem>
<para>
Passes if the incoming depth value is greater than or equal to
the stored depth value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_ALWAYS</constant></term>
<listitem>
<para>
Always passes.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The initial value of <parameter>func</parameter> is <constant>GL_LESS</constant>.
Initially, depth testing is disabled. If depth testing is disabled or if no
depth buffer exists, it is as if the depth test always passes.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Even if the depth buffer exists and the depth mask is non-zero, the
depth buffer is not updated if the depth test is disabled.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>func</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDepthFunc</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_FUNC</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_TEST</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

81
Source/Bind/Specifications/Docs/glDepthMask.xml Normal file
View file

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDepthMask">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDepthMask</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDepthMask</refname>
<refpurpose>enable or disable writing into the depth buffer</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDepthMask</function></funcdef>
<paramdef>GLboolean <parameter>flag</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>flag</parameter></term>
<listitem>
<para>
Specifies whether the depth buffer is enabled for writing.
If <parameter>flag</parameter> is <constant>GL_FALSE</constant>,
depth buffer writing is disabled.
Otherwise, it is enabled.
Initially, depth buffer writing is enabled.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDepthMask</function> specifies whether the depth buffer is enabled for writing.
If <parameter>flag</parameter> is <constant>GL_FALSE</constant>,
depth buffer writing is disabled.
Otherwise, it is enabled.
Initially, depth buffer writing is enabled.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDepthMask</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_WRITEMASK</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glStencilMask</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

128
Source/Bind/Specifications/Docs/glDepthRange.xml Normal file
View file

@ -0,0 +1,128 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDepthRange">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDepthRange</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDepthRange</refname>
<refpurpose>specify mapping of depth values from normalized device coordinates to window coordinates</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDepthRange</function></funcdef>
<paramdef>GLclampd <parameter>nearVal</parameter></paramdef>
<paramdef>GLclampd <parameter>farVal</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>nearVal</parameter></term>
<listitem>
<para>
Specifies the mapping of the near clipping plane to window coordinates.
The initial value is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>farVal</parameter></term>
<listitem>
<para>
Specifies the mapping of the far clipping plane to window coordinates.
The initial value is 1.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
After clipping and division by <emphasis>w</emphasis>,
depth coordinates range from
<inlineequation><mml:math>
<!-- eqn: -1:-->
<mml:mn>-1</mml:mn>
</mml:math></inlineequation>
to 1,
corresponding to the near and far clipping planes.
<function>glDepthRange</function> specifies a linear mapping of the normalized depth coordinates
in this range to window depth coordinates.
Regardless of the actual depth buffer implementation,
window coordinate depth values are treated as though they range
from 0 through 1 (like color components).
Thus,
the values accepted by <function>glDepthRange</function> are both clamped to this range
before they are accepted.
</para>
<para>
The setting of (0,1) maps the near plane to 0 and
the far plane to 1.
With this mapping,
the depth buffer range is fully utilized.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
It is not necessary that <parameter>nearVal</parameter> be less than <parameter>farVal</parameter>.
Reverse mappings such as
<inlineequation><mml:math>
<!-- eqn: nearVal = 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">nearVal</mml:mi>
<mml:mo>=</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: farVal = 0:-->
<mml:mrow>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mo>=</mml:mo>
<mml:mn>0</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
are acceptable.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDepthRange</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_RANGE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glViewport</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

102
Source/Bind/Specifications/Docs/glDetachShader.xml Normal file
View file

@ -0,0 +1,102 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDetachShader">
<refmeta>
<refentrytitle>glDetachShader</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDetachShader</refname>
<refpurpose>Detaches a shader object from a program object to which it is attached</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDetachShader</function></funcdef>
<paramdef>GLuint <parameter>program</parameter></paramdef>
<paramdef>GLuint <parameter>shader</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>program</parameter></term>
<listitem>
<para>Specifies the program object from which to
detach the shader object.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>shader</parameter></term>
<listitem>
<para>Specifies the shader object to be
detached.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glDetachShader</function> detaches the shader
object specified by <parameter>shader</parameter> from the
program object specified by <parameter>program</parameter>. This
command can be used to undo the effect of the command
<citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>.</para>
<para>If <parameter>shader</parameter> has already been flagged
for deletion by a call to
<citerefentry><refentrytitle>glDeleteShader</refentrytitle></citerefentry>
and it is not attached to any other program object, it will be
deleted after it has been detached.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glDetachShader</function> is available only if
the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if either
<parameter>program</parameter> or <parameter>shader</parameter>
is a value that was not generated by OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>program</parameter> is not a program object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>shader</parameter> is not a shader object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>shader</parameter> is not attached to
<parameter>program</parameter>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glDetachShader</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
with the handle of a valid program object</para>
<para><citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>
with arguments <parameter>shader</parameter> and
<constant>GL_DELETE_STATUS</constant></para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

150
Source/Bind/Specifications/Docs/glDrawArrays.xml Normal file
View file

@ -0,0 +1,150 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawArrays">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDrawArrays</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawArrays</refname>
<refpurpose>render primitives from array data</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawArrays</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
<paramdef>GLint <parameter>first</parameter></paramdef>
<paramdef>GLsizei <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies what kind of primitives to render.
Symbolic constants
<constant>GL_POINTS</constant>,
<constant>GL_LINE_STRIP</constant>,
<constant>GL_LINE_LOOP</constant>,
<constant>GL_LINES</constant>,
<constant>GL_TRIANGLE_STRIP</constant>,
<constant>GL_TRIANGLE_FAN</constant>,
<constant>GL_TRIANGLES</constant>,
<constant>GL_QUAD_STRIP</constant>,
<constant>GL_QUADS</constant>,
and <constant>GL_POLYGON</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>first</parameter></term>
<listitem>
<para>
Specifies the starting index in the enabled arrays.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
Specifies the number of indices to be rendered.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDrawArrays</function> specifies multiple geometric primitives
with very few subroutine calls. Instead of calling a GL procedure
to pass each individual vertex, normal, texture coordinate, edge
flag, or color, you can prespecify
separate arrays of vertices, normals, and colors and use them to
construct a sequence of primitives with a single
call to <function>glDrawArrays</function>.
</para>
<para>
When <function>glDrawArrays</function> is called, it uses <parameter>count</parameter> sequential elements from each
enabled array to construct a sequence of geometric primitives,
beginning with element <parameter>first</parameter>. <parameter>mode</parameter> specifies what kind of
primitives are constructed and how the array elements
construct those primitives. If <constant>GL_VERTEX_ARRAY</constant> is not enabled, no
geometric primitives are generated.
</para>
<para>
Vertex attributes that are modified by <function>glDrawArrays</function> have an
unspecified value after <function>glDrawArrays</function> returns. For example, if
<constant>GL_COLOR_ARRAY</constant> is enabled, the value of the current color is
undefined after <function>glDrawArrays</function> executes. Attributes that aren't
modified remain well defined.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDrawArrays</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<function>glDrawArrays</function> is included in display lists. If <function>glDrawArrays</function> is entered into a
display list,
the necessary array data (determined by the array pointers and
enables) is also
entered into the display list. Because the array pointers and
enables are client-side state, their values affect display lists
when the lists are created, not when the lists are executed.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>count</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an
enabled array and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawArrays</function> is executed between
the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

239
Source/Bind/Specifications/Docs/glDrawBuffer.xml Normal file
View file

@ -0,0 +1,239 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawBuffer">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDrawBuffer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawBuffer</refname>
<refpurpose>specify which color buffers are to be drawn into</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawBuffer</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies up to four color buffers to be drawn into.
Symbolic constants
<constant>GL_NONE</constant>,
<constant>GL_FRONT_LEFT</constant>,
<constant>GL_FRONT_RIGHT</constant>,
<constant>GL_BACK_LEFT</constant>,
<constant>GL_BACK_RIGHT</constant>,
<constant>GL_FRONT</constant>,
<constant>GL_BACK</constant>,
<constant>GL_LEFT</constant>,
<constant>GL_RIGHT</constant>,
<constant>GL_FRONT_AND_BACK</constant>, and
<constant>GL_AUX</constant><emphasis>i</emphasis>,
where <emphasis>i</emphasis> is between 0 and the value of <constant>GL_AUX_BUFFERS</constant> minus 1,
are accepted. (<constant>GL_AUX_BUFFERS</constant> is not the upper limit; use <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
to query the number of available aux buffers.)
The initial value is <constant>GL_FRONT</constant> for single-buffered contexts,
and <constant>GL_BACK</constant> for double-buffered contexts.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
When colors are written to the frame buffer,
they are written into the color buffers specified by <function>glDrawBuffer</function>.
The specifications are as follows:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_NONE</constant></term>
<listitem>
<para>
No color buffers are written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_LEFT</constant></term>
<listitem>
<para>
Only the front left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_RIGHT</constant></term>
<listitem>
<para>
Only the front right color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_LEFT</constant></term>
<listitem>
<para>
Only the back left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_RIGHT</constant></term>
<listitem>
<para>
Only the back right color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT</constant></term>
<listitem>
<para>
Only the front left and front right color buffers are written.
If there is no front right color buffer,
only the front left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK</constant></term>
<listitem>
<para>
Only the back left and back right color buffers are written.
If there is no back right color buffer,
only the back left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_LEFT</constant></term>
<listitem>
<para>
Only the front left and back left color buffers are written.
If there is no back left color buffer,
only the front left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_RIGHT</constant></term>
<listitem>
<para>
Only the front right and back right color buffers are written.
If there is no back right color buffer,
only the front right color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_AND_BACK</constant></term>
<listitem>
<para>
All the front and back color buffers
(front left, front right, back left, back right)
are written.
If there are no back color buffers,
only the front left and front right color buffers are written.
If there are no right color buffers,
only the front left and back left color buffers are written.
If there are no right or back color buffers,
only the front left color buffer is written.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_AUX</constant><emphasis>i</emphasis></term>
<listitem>
<para>
Only auxiliary color buffer <emphasis>i</emphasis> is written.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If more than one color buffer is selected for drawing,
then blending or logical operations are computed and applied independently
for each color buffer and can produce different results in each buffer.
</para>
<para>
Monoscopic contexts include only
<emphasis>left</emphasis>
buffers, and stereoscopic contexts include both
<emphasis>left</emphasis>
and
<emphasis>right</emphasis>
buffers.
Likewise, single-buffered contexts include only
<emphasis>front</emphasis>
buffers, and double-buffered contexts include both
<emphasis>front</emphasis>
and
<emphasis>back</emphasis>
buffers.
The context is selected at GL initialization.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
It is always the case that <constant>GL_AUX</constant>
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
= <constant>GL_AUX0</constant> +
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if none of the buffers indicated
by <parameter>mode</parameter> exists.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawBuffer</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DRAW_BUFFER</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_AUX_BUFFERS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

196
Source/Bind/Specifications/Docs/glDrawBuffers.xml Normal file
View file

@ -0,0 +1,196 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawBuffers">
<refmeta>
<refentrytitle>glDrawBuffers</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawBuffers</refname>
<refpurpose>Specifies a list of color buffers to be drawn into</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawBuffers</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLenum *<parameter>bufs</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>Specifies the number of buffers in
<parameter>bufs</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bufs</parameter></term>
<listitem>
<para>Points to an array of symbolic constants
specifying the buffers into which fragment colors or
data values will be written.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glDrawBuffers</function> defines an array of
buffers into which fragment color values or fragment data will
be written. If no fragment shader is active, rendering
operations will generate only one fragment color per fragment
and it will be written into each of the buffers specified by
<parameter>bufs</parameter>. If a fragment shader is active and
it writes a value to the output variable
<code>gl_FragColor</code>, then that value will be
written into each of the buffers specified by
<parameter>bufs</parameter>. If a fragment shader is active and
it writes a value to one or more elements of the output array
variable <code>gl_FragData[]</code>, then the value of
<code>gl_FragData[0] </code> will be written into the
first buffer specified by <parameter>bufs</parameter>, the value
of <code>gl_FragData[1] </code> will be written into the
second buffer specified by <parameter>bufs</parameter>, and so
on up to <code>gl_FragData[n-1]</code>. The draw buffer
used for <code>gl_FragData[n]</code> and beyond is
implicitly set to be <constant>GL_NONE</constant>.</para>
<para>The symbolic constants contained in
<parameter>bufs</parameter> may be any of the following:</para>
<variablelist>
<varlistentry>
<term><constant>GL_NONE</constant></term>
<listitem>
<para>The fragment color/data value is not written into
any color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_LEFT</constant></term>
<listitem>
<para>The fragment color/data value is written into the
front left color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_RIGHT</constant></term>
<listitem>
<para>The fragment color/data value is written into the
front right color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_LEFT</constant></term>
<listitem>
<para>The fragment color/data value is written into the
back left color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_RIGHT</constant></term>
<listitem>
<para>The fragment color/data value is written into the
back right color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_AUXi</constant></term>
<listitem>
<para>The fragment color/data value is written into
auxiliary buffer <code>i</code>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Except for <constant>GL_NONE</constant>, the preceding
symbolic constants may not appear more than once in
<parameter>bufs</parameter>. The maximum number of draw buffers
supported is implementation dependent and can be queried by
calling
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with the argument <constant>GL_MAX_DRAW_BUFFERS</constant>. The
number of auxiliary buffers can be queried by calling
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with the argument <constant>GL_AUX_BUFFERS</constant>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glDrawBuffers</function> is available only if
the GL version is 2.0 or greater.</para>
<para>It is always the case that <constant>GL_AUXi</constant> =
<constant>GL_AUX0</constant> + <code>i</code>.</para>
<para>The symbolic constants <constant>GL_FRONT</constant>,
<constant>GL_BACK</constant>, <constant>GL_LEFT</constant>,
<constant>GL_RIGHT</constant>, and
<constant>GL_FRONT_AND_BACK</constant> are not allowed in the
<parameter>bufs</parameter> array since they may refer to
multiple buffers.</para>
<para>If a fragment shader writes to neither
<code>gl_FragColor</code> nor
<code>gl_FragData</code>, the values of the fragment
colors following shader execution are undefined. For each
fragment generated in this situation, a different value may be
written into each of the buffers specified by
<parameter>bufs</parameter>.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_ENUM</constant> is generated if one of the
values in <parameter>bufs</parameter> is not an accepted
value.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if
<parameter>n</parameter> is less than 0.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if a
symbolic constant other than <constant>GL_NONE</constant>
appears more than once in <parameter>bufs</parameter>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if any of
the entries in <parameter>bufs</parameter> (other than
<constant>GL_NONE</constant> ) indicates a color buffer that
does not exist in the current GL context.</para>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>n</parameter> is greater than
<constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<function>glDrawBuffers</function> is executed between the
execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_MAX_DRAW_BUFFERS</constant></para>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_DRAW_BUFFERSi</constant> where
<code>i</code> indicates the number of the draw buffer
whose value is to be queried</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para> <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

162
Source/Bind/Specifications/Docs/glDrawElements.xml Normal file
View file

@ -0,0 +1,162 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawElements">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDrawElements</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawElements</refname>
<refpurpose>render primitives from array data</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawElements</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
<paramdef>GLsizei <parameter>count</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>indices</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies what kind of primitives to render.
Symbolic constants
<constant>GL_POINTS</constant>,
<constant>GL_LINE_STRIP</constant>,
<constant>GL_LINE_LOOP</constant>,
<constant>GL_LINES</constant>,
<constant>GL_TRIANGLE_STRIP</constant>,
<constant>GL_TRIANGLE_FAN</constant>,
<constant>GL_TRIANGLES</constant>,
<constant>GL_QUAD_STRIP</constant>,
<constant>GL_QUADS</constant>,
and <constant>GL_POLYGON</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
Specifies the number of elements to be rendered.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies the type of the values in <parameter>indices</parameter>. Must be one of
<constant>GL_UNSIGNED_BYTE</constant>, <constant>GL_UNSIGNED_SHORT</constant>, or
<constant>GL_UNSIGNED_INT</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>indices</parameter></term>
<listitem>
<para>
Specifies a pointer to the location where the indices are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDrawElements</function> specifies multiple geometric primitives
with very few subroutine calls. Instead of calling a GL function
to pass each individual vertex, normal, texture coordinate, edge
flag, or color, you can prespecify
separate arrays of vertices, normals, and so on, and use them to
construct a sequence of primitives with a single
call to <function>glDrawElements</function>.
</para>
<para>
When <function>glDrawElements</function> is called, it uses <parameter>count</parameter> sequential elements from an
enabled array, starting at <parameter>indices</parameter> to construct a sequence of
geometric primitives. <parameter>mode</parameter> specifies what kind of primitives are
constructed and how the array elements construct these primitives. If
more than one array is enabled, each is used. If
<constant>GL_VERTEX_ARRAY</constant> is not enabled, no geometric primitives are
constructed.
</para>
<para>
Vertex attributes that are modified by <function>glDrawElements</function> have an
unspecified value after <function>glDrawElements</function> returns. For example, if
<constant>GL_COLOR_ARRAY</constant> is enabled, the value of the current color is
undefined after <function>glDrawElements</function> executes. Attributes that aren't
modified maintain their previous values.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDrawElements</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<function>glDrawElements</function> is included in display lists. If <function>glDrawElements</function> is entered into a
display list,
the necessary array data (determined by the array pointers and
enables) is also
entered into the display list. Because the array pointers and
enables are client-side state, their values affect display lists
when the lists are created, not when the lists are executed.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>count</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an
enabled array or the element array and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawElements</function> is executed between
the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

1235
Source/Bind/Specifications/Docs/glDrawPixels.xml Normal file
View file

File diff suppressed because it is too large Load diff

238
Source/Bind/Specifications/Docs/glDrawRangeElements.xml Normal file
View file

@ -0,0 +1,238 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawRangeElements">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glDrawRangeElements</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawRangeElements</refname>
<refpurpose>render primitives from array data</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawRangeElements</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
<paramdef>GLuint <parameter>start</parameter></paramdef>
<paramdef>GLuint <parameter>end</parameter></paramdef>
<paramdef>GLsizei <parameter>count</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const GLvoid * <parameter>indices</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies what kind of primitives to render.
Symbolic constants
<constant>GL_POINTS</constant>,
<constant>GL_LINE_STRIP</constant>,
<constant>GL_LINE_LOOP</constant>,
<constant>GL_LINES</constant>,
<constant>GL_TRIANGLE_STRIP</constant>,
<constant>GL_TRIANGLE_FAN</constant>,
<constant>GL_TRIANGLES</constant>,
<constant>GL_QUAD_STRIP</constant>,
<constant>GL_QUADS</constant>,
and <constant>GL_POLYGON</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>start</parameter></term>
<listitem>
<para>
Specifies the minimum array index contained in <parameter>indices</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>end</parameter></term>
<listitem>
<para>
Specifies the maximum array index contained in <parameter>indices</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
Specifies the number of elements to be rendered.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies the type of the values in <parameter>indices</parameter>. Must be one of
<constant>GL_UNSIGNED_BYTE</constant>, <constant>GL_UNSIGNED_SHORT</constant>, or
<constant>GL_UNSIGNED_INT</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>indices</parameter></term>
<listitem>
<para>
Specifies a pointer to the location where the indices are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glDrawRangeElements</function> is a restricted form of <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>. <parameter>mode</parameter>, <parameter>start</parameter>, <parameter>end</parameter>,
and <parameter>count</parameter> match the corresponding arguments to <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, with
the additional constraint that all values in the arrays <parameter>count</parameter> must lie
between <parameter>start</parameter> and <parameter>end</parameter>, inclusive.
</para>
<para>
Implementations denote recommended maximum amounts of vertex and
index data,
which may be queried by calling <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
<constant>GL_MAX_ELEMENTS_VERTICES</constant> and <constant>GL_MAX_ELEMENTS_INDICES</constant>.
If
<inlineequation><mml:math>
<!-- eqn: end - start + 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">end</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>
is greater than the value of
<constant>GL_MAX_ELEMENTS_VERTICES</constant>, or if <parameter>count</parameter> is greater than the value of
<constant>GL_MAX_ELEMENTS_INDICES</constant>, then the call may operate at reduced
performance. There is no requirement that all vertices in the range
<inlineequation><mml:math>
<!-- eqn: [start, end]:-->
<mml:mfenced open="[" close="]">
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mi mathvariant="italic">end</mml:mi>
</mml:mfenced>
</mml:math></inlineequation>
be referenced. However, the implementation may
partially process unused vertices, reducing performance from what could
be achieved with an optimal index set.
</para>
<para>
When <function>glDrawRangeElements</function> is called, it uses <parameter>count</parameter> sequential elements from an
enabled array, starting at <parameter>start</parameter> to construct a sequence of
geometric primitives. <parameter>mode</parameter> specifies what kind of primitives are
constructed, and how the array elements construct these primitives. If
more than one array is enabled, each is used. If
<constant>GL_VERTEX_ARRAY</constant> is not enabled, no geometric primitives are
constructed.
</para>
<para>
Vertex attributes that are modified by <function>glDrawRangeElements</function> have an
unspecified value after <function>glDrawRangeElements</function> returns. For example, if
<constant>GL_COLOR_ARRAY</constant> is enabled, the value of the current color is
undefined after <function>glDrawRangeElements</function> executes. Attributes that aren't
modified maintain their previous values.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glDrawRangeElements</function> is available only if the GL version is 1.2 or greater.
</para>
<para>
<function>glDrawRangeElements</function> is included in display lists. If <function>glDrawRangeElements</function> is entered into a
display list,
the necessary array data (determined by the array pointers and
enables) is also
entered into the display list. Because the array pointers and
enables are client-side state, their values affect display lists
when the lists are created, not when the lists are executed.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
It is an error for indices to lie outside the range
<inlineequation><mml:math>
<!-- eqn: [start, end]:-->
<mml:mfenced open="[" close="]">
<mml:mi mathvariant="italic">start</mml:mi>
<mml:mi mathvariant="italic">end</mml:mi>
</mml:mfenced>
</mml:math></inlineequation>,
but implementations may not check for this situation. Such indices
cause implementation-dependent behavior.
</para>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>count</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<inlineequation><mml:math>
<!-- eqn: end < start:-->
<mml:mrow>
<mml:mi mathvariant="italic">end</mml:mi>
<mml:mo>&lt;</mml:mo>
<mml:mi mathvariant="italic">start</mml:mi>
</mml:mrow>
</mml:math></inlineequation>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an
enabled array or the element array and the buffer object's data store is currently mapped.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawRangeElements</function> is executed between
the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_ELEMENTS_VERTICES</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_ELEMENTS_INDICES</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

112
Source/Bind/Specifications/Docs/glEdgeFlag.xml Normal file
View file

@ -0,0 +1,112 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEdgeFlag">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEdgeFlag</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEdgeFlag</refname>
<refpurpose>flag edges as either boundary or nonboundary</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEdgeFlag</function></funcdef>
<paramdef>GLboolean <parameter>flag</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>flag</parameter></term>
<listitem>
<para>
Specifies the current edge flag value,
either <constant>GL_TRUE</constant> or <constant>GL_FALSE</constant>. The initial value is <constant>GL_TRUE</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEdgeFlagv</function></funcdef>
<paramdef>const GLboolean * <parameter>flag</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>flag</parameter></term>
<listitem>
<para>
Specifies a pointer to an array that contains a single boolean element,
which replaces the current edge flag value.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Each vertex of a polygon,
separate triangle,
or separate quadrilateral specified between a <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>/<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> pair
is marked as the start of either a boundary or nonboundary edge.
If the current edge flag is true when the vertex is specified,
the vertex is marked as the start of a boundary edge.
Otherwise, the vertex is marked as the start of a nonboundary edge.
<function>glEdgeFlag</function> sets the edge flag bit to <constant>GL_TRUE</constant> if <parameter>flag</parameter> is <constant>GL_TRUE</constant>
and to <constant>GL_FALSE</constant> otherwise.
</para>
<para>
The vertices of connected triangles and connected quadrilaterals are always
marked as boundary,
regardless of the value of the edge flag.
</para>
<para>
Boundary and nonboundary edge flags on vertices are significant only if
<constant>GL_POLYGON_MODE</constant> is set to <constant>GL_POINT</constant> or <constant>GL_LINE</constant>.
See <citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
The current edge flag can be updated at any time.
In particular,
<function>glEdgeFlag</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_EDGE_FLAG</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
<function>glEdgeFlagPointer</function>,
<citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

166
Source/Bind/Specifications/Docs/glEdgeFlagPointer.xml Normal file
View file

@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEdgeFlagPointer">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEdgeFlagPointer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEdgeFlagPointer</refname>
<refpurpose>define an array of edge flags</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEdgeFlagPointer</function></funcdef>
<paramdef>GLsizei <parameter>stride</parameter></paramdef>
<paramdef>const GLvoid * <parameter>pointer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>stride</parameter></term>
<listitem>
<para>
Specifies the byte offset between consecutive edge flags.
If <parameter>stride</parameter> is 0, the edge flags are understood
to be tightly packed in the array. The initial value is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pointer</parameter></term>
<listitem>
<para>
Specifies a pointer to the first edge flag in the array. The initial
value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glEdgeFlagPointer</function> specifies the location and data format of an array of boolean edge
flags to use when rendering. <parameter>stride</parameter> specifies the byte stride from one
edge flag to the next, allowing vertices and attributes
to be packed into a single array or stored in separate arrays.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_ARRAY_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while an edge flag array is
specified, <parameter>pointer</parameter> is treated as a byte offset into the buffer object's data store.
Also, the buffer object binding (<constant>GL_ARRAY_BUFFER_BINDING</constant>) is saved as edge flag vertex array
client-side state (<constant>GL_EDGE_FLAG_ARRAY_BUFFER_BINDING</constant>).
</para>
<para>
When an edge flag array is
specified, <parameter>stride</parameter> and <parameter>pointer</parameter> are saved as client-side
state, in addition to the current vertex array buffer object binding.
</para>
<para>
To enable and disable the edge flag array, call
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry> with the argument
<constant>GL_EDGE_FLAG_ARRAY</constant>. If
enabled, the edge flag array is used
when <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry> is called.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glEdgeFlagPointer</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
Edge flags are not supported for interleaved vertex array formats
(see <citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>).
</para>
<para>
The edge flag array is initially disabled and isn't accessed when
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>
is called.
</para>
<para>
Execution of <function>glEdgeFlagPointer</function> is not allowed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
but an error may or may not be generated. If no error is generated,
the operation is undefined.
</para>
<para>
<function>glEdgeFlagPointer</function> is typically implemented on the client side.
</para>
<para>
Edge flag array parameters are client-side state and are therefore
not saved or restored by <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>.
Use <citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry> instead.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>stride</parameter> is negative.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_EDGE_FLAG_ARRAY</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_EDGE_FLAG_ARRAY_STRIDE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_EDGE_FLAG_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry> with argument <constant>GL_EDGE_FLAG_ARRAY_POINTER</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

1110
Source/Bind/Specifications/Docs/glEnable.xml Normal file
View file

File diff suppressed because it is too large Load diff

223
Source/Bind/Specifications/Docs/glEnableClientState.xml Normal file
View file

@ -0,0 +1,223 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEnableClientState">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEnableClientState</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEnableClientState</refname>
<refpurpose>enable or disable client-side capability</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEnableClientState</function></funcdef>
<paramdef>GLenum <parameter>cap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>cap</parameter></term>
<listitem>
<para>
Specifies the capability to enable.
Symbolic constants
<constant>GL_COLOR_ARRAY</constant>,
<constant>GL_EDGE_FLAG_ARRAY</constant>,
<constant>GL_FOG_COORD_ARRAY</constant>,
<constant>GL_INDEX_ARRAY</constant>,
<constant>GL_NORMAL_ARRAY</constant>,
<constant>GL_SECONDARY_COLOR_ARRAY</constant>,
<constant>GL_TEXTURE_COORD_ARRAY</constant>, and
<constant>GL_VERTEX_ARRAY</constant>
are accepted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDisableClientState</function></funcdef>
<paramdef>GLenum <parameter>cap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>cap</parameter></term>
<listitem>
<para>
Specifies the capability to disable.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glEnableClientState</function> and <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>
enable or disable individual client-side capabilities. By default, all
client-side capabilities are disabled.
Both
<function>glEnableClientState</function> and <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry> take a
single argument, <parameter>cap</parameter>, which can assume one of the following
values:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_COLOR_ARRAY</constant></term>
<listitem>
<para>
If enabled, the color array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_EDGE_FLAG_ARRAY</constant></term>
<listitem>
<para>
If enabled, the edge flag array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_COORD_ARRAY</constant></term>
<listitem>
<para>
If enabled, the fog coordinate array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_INDEX_ARRAY</constant></term>
<listitem>
<para>
If enabled, the index array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_NORMAL_ARRAY</constant></term>
<listitem>
<para>
If enabled, the normal array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_SECONDARY_COLOR_ARRAY</constant></term>
<listitem>
<para>
If enabled, the secondary color array is enabled for writing and used
during rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_TEXTURE_COORD_ARRAY</constant></term>
<listitem>
<para>
If enabled, the texture coordinate array is enabled for writing and used
during rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_VERTEX_ARRAY</constant></term>
<listitem>
<para>
If enabled, the vertex array is enabled for writing and used during
rendering when <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry> is called. See <citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glEnableClientState</function> is available only if the GL version is 1.1 or greater.
</para>
<para>
<constant>GL_FOG_COORD_ARRAY</constant> and <constant>GL_SECONDARY_COLOR_ARRAY</constant> are available only if the GL version is 1.4 or
greater.
</para>
<para>
For OpenGL versions 1.3 and greater, or when <code>ARB_multitexture</code> is supported, enabling and disabling
<constant>GL_TEXTURE_COORD_ARRAY</constant> affects the active client texture unit.
The active client texture unit is controlled with
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>cap</parameter> is not an accepted value.
</para>
<para>
<function>glEnableClientState</function> is not allowed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the
corresponding <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>, but an error may or may not be generated. If
no error is generated, the behavior is undefined.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

109
Source/Bind/Specifications/Docs/glEnableVertexAttribArray.xml Normal file
View file

@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEnableVertexAttribArray">
<refmeta>
<refentrytitle>glEnableVertexAttribArray</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refdescriptor>glEnableVertexAttribArray</refdescriptor>
<refname>glEnableVertexAttribArray</refname>
<refname>glDisableVertexAttribArray</refname>
<refpurpose>Enable or disable a generic vertex attribute array</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEnableVertexAttribArray</function></funcdef>
<paramdef>GLuint <parameter>index</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>glDisableVertexAttribArray</function></funcdef>
<paramdef>GLuint <parameter>index</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>index</parameter></term>
<listitem>
<para>Specifies the index of the generic vertex
attribute to be enabled or disabled.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para><function>glEnableVertexAttribArray</function> enables the
generic vertex attribute array specified by
<parameter>index</parameter>.
<function>glDisableVertexAttribArray</function> disables the
generic vertex attribute array specified by
<parameter>index</parameter>. By default, all client-side
capabilities are disabled, including all generic vertex
attribute arrays. If enabled, the values in the generic vertex
attribute array will be accessed and used for rendering when
calls are made to vertex array commands such as
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
or
<citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para><function>glEnableVertexAttribArray</function> and
<function>glDisableVertexAttribArray </function> are available
only if the GL version is 2.0 or greater.</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>index</parameter> is greater than or equal to
<constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if either
<function>glEnableVertexAttribArray </function> or
<function>glDisableVertexAttribArray </function> is executed
between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of
<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
<para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
with arguments <parameter>index</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_ENABLED</constant>
<parameter></parameter></para>
<para><citerefentry><refentrytitle>glGetVertexAttribPointerv</refentrytitle></citerefentry>
with arguments <parameter>index</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_POINTER</constant></para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

362
Source/Bind/Specifications/Docs/glEvalCoord.xml Normal file
View file

@ -0,0 +1,362 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEvalCoord">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEvalCoord</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEvalCoord</refname>
<refpurpose>evaluate enabled one- and two-dimensional maps</refpurpose>
</refnamediv>
<!-- eqn: ignoring delim $$ -->
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord1f</function></funcdef>
<paramdef>GLfloat <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord1d</function></funcdef>
<paramdef>GLdouble <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord2f</function></funcdef>
<paramdef>GLfloat <parameter>u</parameter></paramdef>
<paramdef>GLfloat <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord2d</function></funcdef>
<paramdef>GLdouble <parameter>u</parameter></paramdef>
<paramdef>GLdouble <parameter>v</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>u</parameter></term>
<listitem>
<para>
Specifies a value that is the domain coordinate
<inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
to the basis function
defined in a previous <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>v</parameter></term>
<listitem>
<para>
Specifies a value that is the domain coordinate
<inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>
to the basis function
defined in a previous <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> command.
This argument is not present in a <function>glEvalCoord1</function> command.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord1fv</function></funcdef>
<paramdef>const GLfloat * <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord1dv</function></funcdef>
<paramdef>const GLdouble * <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord2fv</function></funcdef>
<paramdef>const GLfloat * <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalCoord2dv</function></funcdef>
<paramdef>const GLdouble * <parameter>u</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>u</parameter></term>
<listitem>
<para>
Specifies a pointer to an array containing
either one or two domain coordinates.
The first coordinate is
<inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>.
The second coordinate is
<inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>,
which is present only in <function>glEvalCoord2</function> versions.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glEvalCoord1</function> evaluates enabled one-dimensional maps at argument
<parameter>u</parameter>.
<function>glEvalCoord2</function> does the same for two-dimensional maps using
two domain values,
<parameter>u</parameter> and <parameter>v</parameter>.
To define a map, call <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>; to enable and
disable it, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>.
</para>
<para>
When one of the <function>glEvalCoord</function> commands is issued,
all currently enabled maps of the indicated dimension are evaluated.
Then,
for each enabled map,
it is as if the corresponding GL command had been issued with the
computed value.
That is,
if <constant>GL_MAP1_INDEX</constant> or
<constant>GL_MAP2_INDEX</constant> is enabled,
a <citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry> command is simulated.
If <constant>GL_MAP1_COLOR_4</constant> or
<constant>GL_MAP2_COLOR_4</constant> is enabled,
a <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry> command is simulated.
If <constant>GL_MAP1_NORMAL</constant> or <constant>GL_MAP2_NORMAL</constant> is enabled,
a normal vector is produced,
and if any of
<constant>GL_MAP1_TEXTURE_COORD_1</constant>,
<constant>GL_MAP1_TEXTURE_COORD_2</constant>,
<constant>GL_MAP1_TEXTURE_COORD_3</constant>,
<constant>GL_MAP1_TEXTURE_COORD_4</constant>,
<constant>GL_MAP2_TEXTURE_COORD_1</constant>,
<constant>GL_MAP2_TEXTURE_COORD_2</constant>,
<constant>GL_MAP2_TEXTURE_COORD_3</constant>, or
<constant>GL_MAP2_TEXTURE_COORD_4</constant> is enabled, then an appropriate <citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry> command is simulated.
</para>
<para>
For color,
color index,
normal,
and texture coordinates the GL uses evaluated values instead of current values for those evaluations
that are enabled,
and current values otherwise,
However,
the evaluated values do not update the current values.
Thus, if <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry> commands are interspersed with <function>glEvalCoord</function>
commands, the color,
normal,
and texture coordinates associated with the <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry> commands are not
affected by the values generated by the <function>glEvalCoord</function> commands,
but only by the most recent
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormal</refentrytitle></citerefentry>, and
<citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry> commands.
</para>
<para>
No commands are issued for maps that are not enabled.
If more than one texture evaluation is enabled for a particular dimension
(for example, <constant>GL_MAP2_TEXTURE_COORD_1</constant> and
<constant>GL_MAP2_TEXTURE_COORD_2</constant>),
then only the evaluation of the map that produces the larger
number of coordinates
(in this case, <constant>GL_MAP2_TEXTURE_COORD_2</constant>)
is carried out.
<constant>GL_MAP1_VERTEX_4</constant> overrides <constant>GL_MAP1_VERTEX_3</constant>,
and
<constant>GL_MAP2_VERTEX_4</constant> overrides <constant>GL_MAP2_VERTEX_3</constant>,
in the same manner.
If neither a three- nor a four-component vertex map is enabled for the
specified dimension,
the <function>glEvalCoord</function> command is ignored.
</para>
<para>
If you have enabled automatic normal generation,
by calling <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> with argument <constant>GL_AUTO_NORMAL</constant>,
<function>glEvalCoord2</function> generates surface normals analytically,
regardless of the contents or enabling of the <constant>GL_MAP2_NORMAL</constant> map.
Let
</para>
<para>
<informalequation><mml:math>
<!-- eqn: bold m = { {partial bold p} over {partial u} } times { {partial bold p} over {partial v} }:-->
<mml:mrow>
<mml:mi mathvariant="bold">m</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>&PartialD;</mml:mo>
<mml:mi mathvariant="bold">p</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>&PartialD;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
<mml:mo>&times;</mml:mo>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>&PartialD;</mml:mo>
<mml:mi mathvariant="bold">p</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>&PartialD;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
Then the generated normal
<inlineequation><mml:math>
<!-- eqn: bold n:-->
<mml:mi mathvariant="bold">n</mml:mi>
</mml:math></inlineequation>
is
<inlineequation><mml:math>
<!-- eqn: bold n = bold m over { || bold m || }:-->
<mml:mrow>
<mml:mi mathvariant="bold">n</mml:mi>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mi mathvariant="bold">m</mml:mi>
<mml:mfenced open="" close="">
<mml:mfenced open="&DoubleVerticalBar;" close="&DoubleVerticalBar;">
<mml:mi mathvariant="bold">m</mml:mi>
</mml:mfenced>
</mml:mfenced>
</mml:mfrac>
</mml:mrow>
</mml:math></inlineequation>
</para>
<para>
If automatic normal generation is disabled,
the corresponding normal map <constant>GL_MAP2_NORMAL</constant>,
if enabled,
is used to produce a normal.
If neither automatic normal generation nor a normal map is enabled,
no normal is generated for
<function>glEvalCoord2</function> commands.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_VERTEX_3</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_VERTEX_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_INDEX</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_COLOR_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_NORMAL</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_TEXTURE_COORD_1</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_TEXTURE_COORD_2</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_TEXTURE_COORD_3</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP1_TEXTURE_COORD_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_VERTEX_3</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_VERTEX_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_INDEX</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_COLOR_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_NORMAL</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_TEXTURE_COORD_1</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_TEXTURE_COORD_2</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_TEXTURE_COORD_3</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_MAP2_TEXTURE_COORD_4</constant>
</para>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_AUTO_NORMAL</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetMap</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapGrid</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormal</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

626
Source/Bind/Specifications/Docs/glEvalMesh.xml Normal file
View file

@ -0,0 +1,626 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEvalMesh">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEvalMesh</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEvalMesh</refname>
<refpurpose>compute a one- or two-dimensional grid of points or lines</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalMesh1</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
<paramdef>GLint <parameter>i1</parameter></paramdef>
<paramdef>GLint <parameter>i2</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
In <function>glEvalMesh1</function>, specifies whether to compute a one-dimensional mesh of points or lines.
Symbolic constants
<constant>GL_POINT</constant> and
<constant>GL_LINE</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>i1</parameter></term>
<term><parameter>i2</parameter></term>
<listitem>
<para>
Specify the first and last integer values for grid domain variable
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalMesh2</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
<paramdef>GLint <parameter>i1</parameter></paramdef>
<paramdef>GLint <parameter>i2</parameter></paramdef>
<paramdef>GLint <parameter>j1</parameter></paramdef>
<paramdef>GLint <parameter>j2</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
In <function>glEvalMesh2</function>, specifies whether to compute a two-dimensional mesh of points, lines,
or polygons.
Symbolic constants
<constant>GL_POINT</constant>,
<constant>GL_LINE</constant>, and
<constant>GL_FILL</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>i1</parameter></term>
<term><parameter>i2</parameter></term>
<listitem>
<para>
Specify the first and last integer values for grid domain variable
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>j1</parameter></term>
<term><parameter>j2</parameter></term>
<listitem>
<para>
Specify the first and last integer values for grid domain variable
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<citerefentry><refentrytitle>glMapGrid</refentrytitle></citerefentry> and <function>glEvalMesh</function> are used in tandem to efficiently
generate and evaluate a series of evenly-spaced map domain values.
<function>glEvalMesh</function> steps through the integer domain of a one- or two-dimensional grid,
whose range is the domain of the evaluation maps specified by
<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>.
<parameter>mode</parameter> determines whether the resulting vertices are connected as
points,
lines,
or filled polygons.
</para>
<para>
In the one-dimensional case,
<function>glEvalMesh1</function>,
the mesh is generated as if the following code fragment were executed:
</para>
<para>
<programlisting>
glBegin( <parameter>type</parameter> );
for ( i = <parameter>i1</parameter>; i &lt;= <parameter>i2</parameter>; i += 1 )
glEvalCoord1( <mml:math>
<!-- eqn: i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
glEnd();
</programlisting>
where
</para>
<para>
<informalequation><mml:math>
<!-- eqn: DELTA u = (u sub 2 - u sub 1 ) / n:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 1:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>
are the arguments to the most recent
<citerefentry><refentrytitle>glMapGrid1</refentrytitle></citerefentry> command.
<emphasis>type</emphasis> is <constant>GL_POINTS</constant> if <parameter>mode</parameter> is <constant>GL_POINT</constant>,
or <constant>GL_LINES</constant> if <parameter>mode</parameter> is <constant>GL_LINE</constant>.
</para>
<para>
The one absolute numeric requirement is that if
<inlineequation><mml:math>
<!-- eqn: i = n:-->
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the
value computed from
<inlineequation><mml:math>
<!-- eqn: i cdot DELTA u + u sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>.
</para>
<para>
In the two-dimensional case, <function>glEvalMesh2</function>, let
.cp
<informalequation><mml:math>
<!-- eqn: DELTA u = ( u sub 2 - u sub 1 ) / n:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: DELTA v = ( v sub 2 - v sub 1 ) / m:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
where
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 1:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: v sub 1:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: v sub 2:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>
are the
arguments to the most recent <citerefentry><refentrytitle>glMapGrid2</refentrytitle></citerefentry> command. Then, if
<parameter>mode</parameter> is <constant>GL_FILL</constant>, the <function>glEvalMesh2</function> command is equivalent
to:
</para>
<para>
<programlisting>
for ( j = <parameter>j1</parameter>; j &lt; <parameter>j2</parameter>; j += 1 ) {
glBegin( GL_QUAD_STRIP );
for ( i = <parameter>i1</parameter>; i &lt;= <parameter>i2</parameter>; i += 1 ) {
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- j \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1, :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- (j + 1) \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
}
glEnd();
}
</programlisting>
</para>
<para>
If <parameter>mode</parameter> is <constant>GL_LINE</constant>, then a call to <function>glEvalMesh2</function> is equivalent to:
</para>
<para>
<programlisting>
for ( j = <parameter>j1</parameter>; j &lt;= <parameter>j2</parameter>; j += 1 ) {
glBegin( GL_LINE_STRIP );
for ( i = <parameter>i1</parameter>; i &lt;= <parameter>i2</parameter>; i += 1 )
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- i \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
glEnd();
}
for ( i = <parameter>i1</parameter>; i &lt;= <parameter>i2</parameter>; i += 1 ) {
glBegin( GL_LINE_STRIP );
for ( j = <parameter>j1</parameter>; j &lt;= <parameter>j1</parameter>; j += 1 )
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- i \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
glEnd();
}
</programlisting>
</para>
<para>
And finally, if <parameter>mode</parameter> is <constant>GL_POINT</constant>, then a call to
<function>glEvalMesh2</function> is equivalent to:
</para>
<para>
<programlisting>
glBegin( GL_POINTS );
for ( j = <parameter>j1</parameter>; j &lt;= <parameter>j2</parameter>; j += 1 )
for ( i = <parameter>i1</parameter>; i &lt;= <parameter>i2</parameter>; i += 1 )
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- i \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
glEnd();
</programlisting>
</para>
<para>
In all three cases, the only absolute numeric requirements are that if
<inlineequation><mml:math>
<!-- eqn: i = n:-->
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the value computed from
<inlineequation><mml:math>
<!-- eqn: i cdot DELTA u + u sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and if
<inlineequation><mml:math>
<!-- eqn: j = m:-->
<mml:mrow>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the value computed from
<inlineequation><mml:math>
<!-- eqn: j cdot DELTA v + v sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: v sub 2:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glEvalMesh</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_DOMAIN</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_DOMAIN</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_SEGMENTS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_SEGMENTS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapGrid</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

380
Source/Bind/Specifications/Docs/glEvalPoint.xml Normal file
View file

@ -0,0 +1,380 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glEvalPoint">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glEvalPoint</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glEvalPoint</refname>
<refpurpose>generate and evaluate a single point in a mesh</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalPoint1</function></funcdef>
<paramdef>GLint <parameter>i</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glEvalPoint2</function></funcdef>
<paramdef>GLint <parameter>i</parameter></paramdef>
<paramdef>GLint <parameter>j</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>i</parameter></term>
<listitem>
<para>
Specifies the integer value for grid domain variable
<inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>j</parameter></term>
<listitem>
<para>
Specifies the integer value for grid domain variable
<inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>
(<function>glEvalPoint2</function> only).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<citerefentry><refentrytitle>glMapGrid</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry> are used in tandem to efficiently
generate and evaluate a series of evenly spaced map domain values.
<function>glEvalPoint</function> can be used to evaluate a single grid point in the same gridspace
that is traversed by <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry>.
Calling <function>glEvalPoint1</function> is equivalent to calling
<programlisting>
glEvalCoord1( <mml:math>
<!-- eqn: i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
</programlisting>
where
<informalequation><mml:math>
<!-- eqn: DELTA u = ( u sub 2 - u sub 1 ) / n:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
and
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 1:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>
are the arguments to the most recent <citerefentry><refentrytitle>glMapGrid1</refentrytitle></citerefentry> command.
The one absolute numeric requirement is that if
<inlineequation><mml:math>
<!-- eqn: i = n:-->
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the value computed from
<inlineequation><mml:math>
<!-- eqn: i cdot DELTA u + u sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>.
</para>
<para>
In the two-dimensional case, <function>glEvalPoint2</function>, let
</para>
<para>
<informalequation><mml:math>
<!-- eqn: DELTA u = ( u sub 2 - u sub 1 ) / n:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
<para>
<informalequation><mml:math>
<!-- eqn: DELTA v = ( v sub 2 - v sub 1 ) / m:-->
<mml:mrow>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:mfenced>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
</para>
<para>
where
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 1:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: v sub 1:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and
<inlineequation><mml:math>
<!-- eqn: v sub 2:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>
are the arguments to the most recent <citerefentry><refentrytitle>glMapGrid2</refentrytitle></citerefentry> command.
Then the <function>glEvalPoint2</function> command is equivalent to calling
<programlisting>
glEvalCoord2( <mml:math>
<!-- i \cdot DELTA u + u sub 1 :-->
<mml:mrow>
<mml:mrow>
<mml:mn>i</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
<mml:mo>,</mml:mo>
<!-- j \cdot DELTA v + v sub 1 :-->
<mml:mrow>
<mml:mn>j</mml:mn>
<mml:mo>&CenterDot;</mml:mo>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub>
<mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math> );
</programlisting>
The only absolute numeric requirements are that if
<inlineequation><mml:math>
<!-- eqn: i = n:-->
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">n</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the value computed from
<inlineequation><mml:math>
<!-- eqn: i cdot DELTA u + u sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">i</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">u</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: u sub 2:-->
<mml:msub><mml:mi mathvariant="italic">u</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>,
and if
<inlineequation><mml:math>
<!-- eqn: j = m:-->
<mml:mrow>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>=</mml:mo>
<mml:mi mathvariant="italic">m</mml:mi>
</mml:mrow>
</mml:math></inlineequation>,
then the value computed from
<inlineequation><mml:math>
<!-- eqn: j cdot DELTA v + v sub 1:-->
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">j</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mrow>
<mml:mo>&Delta;</mml:mo>
<mml:mi mathvariant="italic">v</mml:mi>
</mml:mrow>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>1</mml:mn>
</mml:msub>
</mml:mrow>
</mml:math></inlineequation>
is exactly
<inlineequation><mml:math>
<!-- eqn: v sub 2:-->
<mml:msub><mml:mi mathvariant="italic">v</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
</mml:math></inlineequation>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_DOMAIN</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_DOMAIN</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_SEGMENTS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_SEGMENTS</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapGrid</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

420
Source/Bind/Specifications/Docs/glFeedbackBuffer.xml Normal file
View file

@ -0,0 +1,420 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFeedbackBuffer">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFeedbackBuffer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFeedbackBuffer</refname>
<refpurpose>controls feedback mode</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFeedbackBuffer</function></funcdef>
<paramdef>GLsizei <parameter>size</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>GLfloat * <parameter>buffer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
Specifies the maximum number of values that can be written into <parameter>buffer</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies a symbolic constant that describes the information
that will be returned for each vertex.
<constant>GL_2D</constant>,
<constant>GL_3D</constant>,
<constant>GL_3D_COLOR</constant>,
<constant>GL_3D_COLOR_TEXTURE</constant>, and
<constant>GL_4D_COLOR_TEXTURE</constant> are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
Returns the feedback data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
The <function>glFeedbackBuffer</function> function controls feedback.
Feedback, like selection, is a GL mode.
The mode is selected by calling
<citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> with <constant>GL_FEEDBACK</constant>.
When the GL is in feedback mode,
no pixels are produced by rasterization.
Instead, information about primitives that would have been
rasterized is fed back to the application using the GL.
</para>
<para>
<function>glFeedbackBuffer</function> has three arguments:
<parameter>buffer</parameter> is a pointer to an array of floating-point values
into which feedback information is placed.
<parameter>size</parameter> indicates the size of the array.
<parameter>type</parameter> is a symbolic constant describing the information
that is fed back for each vertex.
<function>glFeedbackBuffer</function> must be issued before feedback mode is enabled
(by calling <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> with argument <constant>GL_FEEDBACK</constant>).
Setting <constant>GL_FEEDBACK</constant> without establishing the feedback buffer,
or calling <function>glFeedbackBuffer</function> while the GL is in feedback mode,
is an error.
</para>
<para>
When <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called while in feedback mode, it returns the number of entries
placed in the feedback array and resets the feedback array pointer to the base
of the feedback buffer. The returned value never exceeds <parameter>size</parameter>. If the feedback
data required more room than was available in <parameter>buffer</parameter>,
<citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> returns a negative value.
To take the GL out of feedback mode, call
<citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> with a parameter value other than <constant>GL_FEEDBACK</constant>.
</para>
<para>
While in feedback mode,
each primitive, bitmap, or pixel rectangle that would be rasterized
generates a block of values that are copied into the feedback array.
If doing so would cause the number of entries to exceed the maximum,
the block is partially written so as to fill the array
(if there is any room left at all),
and an overflow flag is set.
Each block begins with a code indicating the primitive type,
followed by values that describe the primitive's vertices and
associated data.
Entries are also written for bitmaps and pixel rectangles.
Feedback occurs after polygon culling and <citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry> interpretation
of polygons has taken place,
so polygons that are culled are not returned in the feedback buffer.
It can also occur after polygons with more than three edges are broken up
into triangles,
if the GL implementation renders polygons by performing this decomposition.
</para>
<para>
The <citerefentry><refentrytitle>glPassThrough</refentrytitle></citerefentry> command can be used to insert a marker
into the feedback buffer.
See <citerefentry><refentrytitle>glPassThrough</refentrytitle></citerefentry>.
</para>
<para>
Following is the grammar for the blocks of values written
into the feedback buffer.
Each primitive is indicated with a unique identifying value
followed by some number of vertices.
Polygon entries include an integer value indicating how many vertices follow.
A vertex is fed back as some number of floating-point values,
as determined by <parameter>type</parameter>.
Colors are fed back as four values in RGBA mode and one value
in color index mode.
</para>
<para>
<para>
feedbackList <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> feedbackItem feedbackList | feedbackItem
</para>
<para>
feedbackItem <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> point | lineSegment | polygon | bitmap | pixelRectangle | passThru
</para>
<para>
point <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_POINT_TOKEN</constant> vertex
</para>
<para>
lineSegment <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_LINE_TOKEN</constant> vertex vertex | <constant>GL_LINE_RESET_TOKEN</constant> vertex vertex
</para>
<para>
polygon <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_POLYGON_TOKEN</constant> n polySpec
</para>
<para>
polySpec <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> polySpec vertex | vertex vertex vertex
</para>
<para>
bitmap <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_BITMAP_TOKEN</constant> vertex
</para>
<para>
pixelRectangle <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_DRAW_PIXEL_TOKEN</constant> vertex | <constant>GL_COPY_PIXEL_TOKEN</constant> vertex
</para>
<para>
passThru <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> <constant>GL_PASS_THROUGH_TOKEN</constant> value
</para>
<para>
vertex <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture
</para>
<para>
2d <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value
</para>
<para>
3d <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value
</para>
<para>
3dColor <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value color
</para>
<para>
3dColorTexture <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value color tex
</para>
<para>
4dColorTexture <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value value color tex
</para>
<para>
color <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> rgba | index
</para>
<para>
rgba <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value value
</para>
<para>
index <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value
</para>
<para>
tex <inlineequation><mml:math><mml:mrow><mml:mn>&#x2190;</mml:mn></mml:mrow></mml:math></inlineequation> value value value value
</para>
<para>
</para>
</para>
<para>
<emphasis>value</emphasis>
is a floating-point number,
and
<emphasis>n</emphasis>
is a floating-point integer giving the number of vertices in the polygon.
<constant>GL_POINT_TOKEN</constant>,
<constant>GL_LINE_TOKEN</constant>,
<constant>GL_LINE_RESET_TOKEN</constant>,
<constant>GL_POLYGON_TOKEN</constant>,
<constant>GL_BITMAP_TOKEN</constant>,
<constant>GL_DRAW_PIXEL_TOKEN</constant>,
<constant>GL_COPY_PIXEL_TOKEN</constant> and
<constant>GL_PASS_THROUGH_TOKEN</constant> are symbolic floating-point constants.
<constant>GL_LINE_RESET_TOKEN</constant> is returned whenever the line stipple pattern
is reset.
The data returned as a vertex depends on the feedback <parameter>type</parameter>.
</para>
<para>
The following table gives the correspondence between <parameter>type</parameter>
and the number of values per vertex.
<emphasis>k</emphasis> is 1 in color index mode and 4 in RGBA mode.
</para>
<para>
</para>
<informaltable frame="topbot">
<tgroup cols="5" align="left">
<colspec colwidth="2.7*" />
<colspec colwidth="1.5*" />
<colspec colwidth="1*" align="center"/>
<colspec colwidth="1*" align="center"/>
<colspec colwidth="2.5*" align="center"/>
<thead>
<row>
<entry rowsep="1" align="left"><emphasis role="bold">
Type
</emphasis></entry>
<entry rowsep="1" align="left"><emphasis role="bold">
Coordinates
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Color
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Texture
</emphasis></entry>
<entry rowsep="1" align="center"><emphasis role="bold">
Total Number of Values
</emphasis></entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<constant>GL_2D</constant>
</entry>
<entry align="left">
<emphasis>x</emphasis>, <emphasis>y</emphasis>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
2
</entry>
</row>
<row>
<entry align="left">
<constant>GL_3D</constant>
</entry>
<entry align="left">
<emphasis>x</emphasis>, <emphasis>y</emphasis>, <emphasis>z</emphasis>
</entry>
<entry align="center">
</entry>
<entry align="center">
</entry>
<entry align="center">
3
</entry>
</row>
<row>
<entry align="left">
<constant>GL_3D_COLOR</constant>
</entry>
<entry align="left">
<emphasis>x</emphasis>, <emphasis>y</emphasis>, <emphasis>z</emphasis>
</entry>
<entry align="center">
<inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>
</entry>
<entry align="center">
</entry>
<entry align="center">
<inlineequation><mml:math>
<!-- eqn: 3 + k:-->
<mml:mrow>
<mml:mn>3</mml:mn>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">k</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_3D_COLOR_TEXTURE</constant>
</entry>
<entry align="left">
<emphasis>x</emphasis>, <emphasis>y</emphasis>, <emphasis>z</emphasis>
</entry>
<entry align="center">
<inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>
</entry>
<entry align="center">
4
</entry>
<entry align="center">
<inlineequation><mml:math>
<!-- eqn: 7 + k:-->
<mml:mrow>
<mml:mn>7</mml:mn>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">k</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
</entry>
</row>
<row>
<entry align="left">
<constant>GL_4D_COLOR_TEXTURE</constant>
</entry>
<entry align="left">
<emphasis>x</emphasis>, <emphasis>y</emphasis>, <emphasis>z</emphasis>, <emphasis>w</emphasis>
</entry>
<entry align="center">
<inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>
</entry>
<entry align="center">
4
</entry>
<entry align="center">
<inlineequation><mml:math>
<!-- eqn: 8 + k:-->
<mml:mrow>
<mml:mn>8</mml:mn>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">k</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Feedback vertex coordinates are in window coordinates,
except <emphasis>w</emphasis>,
which is in clip coordinates.
Feedback colors are lighted, if lighting is enabled.
Feedback texture coordinates are generated,
if texture coordinate generation is enabled.
They are always transformed by the texture matrix.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glFeedbackBuffer</function>, when used in a display list, is not compiled into the display list
but is executed immediately.
</para>
<para>
<function>glFeedbackBuffer</function> returns only the texture coordinate of texture unit <constant>GL_TEXTURE0</constant>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFeedbackBuffer</function> is called while the
render mode is <constant>GL_FEEDBACK</constant>,
or if <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called with argument <constant>GL_FEEDBACK</constant> before
<function>glFeedbackBuffer</function> is called at least once.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFeedbackBuffer</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_RENDER_MODE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FEEDBACK_BUFFER_POINTER</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FEEDBACK_BUFFER_SIZE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FEEDBACK_BUFFER_TYPE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLineStipple</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPassThrough</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSelectBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

61
Source/Bind/Specifications/Docs/glFinish.xml Normal file
View file

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFinish">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFinish</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFinish</refname>
<refpurpose>block until all GL execution is complete</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFinish</function></funcdef>
<paramdef> <parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="description"><title>Description</title>
<para>
<function>glFinish</function> does not return until the effects of all previously
called GL commands are complete.
Such effects include all changes to GL state,
all changes to connection state,
and all changes to the frame buffer contents.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glFinish</function> requires a round trip to the server.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFinish</function> is executed between
the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

75
Source/Bind/Specifications/Docs/glFlush.xml Normal file
View file

@ -0,0 +1,75 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFlush">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFlush</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFlush</refname>
<refpurpose>force execution of GL commands in finite time</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFlush</function></funcdef>
<paramdef> <parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="description"><title>Description</title>
<para>
Different GL implementations buffer commands in several different locations,
including network buffers and the graphics accelerator itself.
<function>glFlush</function> empties all of these buffers,
causing all issued commands to be executed as quickly as
they are accepted by the actual rendering engine.
Though this execution may not be completed in any particular
time period,
it does complete in finite time.
</para>
<para>
Because any GL program might be executed over a network,
or on an accelerator that buffers commands,
all programs should call <function>glFlush</function> whenever they count on having
all of their previously issued commands completed.
For example,
call <function>glFlush</function> before waiting for user input that depends on
the generated image.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glFlush</function> can return at any time.
It does not wait until the execution of all previously
issued GL commands is complete.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFlush</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

492
Source/Bind/Specifications/Docs/glFog.xml Normal file
View file

@ -0,0 +1,492 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFog">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFog</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFog</refname>
<refpurpose>specify fog parameters</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogf</function></funcdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLfloat <parameter>param</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogi</function></funcdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLint <parameter>param</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
Specifies a single-valued fog parameter.
<constant>GL_FOG_MODE</constant>,
<constant>GL_FOG_DENSITY</constant>,
<constant>GL_FOG_START</constant>,
<constant>GL_FOG_END</constant>,
<constant>GL_FOG_INDEX</constant>, and
<constant>GL_FOG_COORD_SRC</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>param</parameter></term>
<listitem>
<para>
Specifies the value that <parameter>pname</parameter> will be set to.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogfv</function></funcdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLfloat * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogiv</function></funcdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLint * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
Specifies a fog parameter.
<constant>GL_FOG_MODE</constant>,
<constant>GL_FOG_DENSITY</constant>,
<constant>GL_FOG_START</constant>,
<constant>GL_FOG_END</constant>,
<constant>GL_FOG_INDEX</constant>,
<constant>GL_FOG_COLOR</constant>, and
<constant>GL_FOG_COORD_SRC</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
Specifies the value or values to be assigned to <parameter>pname</parameter>.
<constant>GL_FOG_COLOR</constant> requires an array of four values.
All other parameters accept an array containing only a single value.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
Fog is initially disabled.
While enabled, fog affects rasterized geometry,
bitmaps, and pixel blocks, but not buffer clear operations. To enable
and disable fog, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
<constant>GL_FOG</constant>.
</para>
<para>
<function>glFog</function> assigns the value or values in <parameter>params</parameter> to the fog parameter
specified by <parameter>pname</parameter>.
The following values are accepted for <parameter>pname</parameter>:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_FOG_MODE</constant></term>
<listitem>
<para>
<parameter>params</parameter> is a single integer or floating-point value that specifies
the equation to be used to compute the fog blend factor,
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
Three symbolic constants are accepted:
<constant>GL_LINEAR</constant>,
<constant>GL_EXP</constant>,
and <constant>GL_EXP2</constant>.
The equations corresponding to these symbolic constants are defined below.
The initial fog mode is <constant>GL_EXP</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_DENSITY</constant></term>
<listitem>
<para>
<parameter>params</parameter> is a single integer or floating-point value that specifies
<inlineequation><mml:math><mml:mi mathvariant="italic">density</mml:mi></mml:math></inlineequation>,
the fog density used in both exponential fog equations.
Only nonnegative densities are accepted.
The initial fog density is 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_START</constant></term>
<listitem>
<para>
<parameter>params</parameter> is a single integer or floating-point value that specifies
<inlineequation><mml:math><mml:mi mathvariant="italic">start</mml:mi></mml:math></inlineequation>,
the near distance used in the linear fog equation.
The initial near distance is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_END</constant></term>
<listitem>
<para>
<parameter>params</parameter> is a single integer or floating-point value that specifies
<inlineequation><mml:math><mml:mi mathvariant="italic">end</mml:mi></mml:math></inlineequation>,
the far distance used in the linear fog equation.
The initial far distance is 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_INDEX</constant></term>
<listitem>
<para>
<parameter>params</parameter> is a single integer or floating-point value that specifies
<inlineequation><mml:math>
<!-- eqn: i sub f:-->
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:msub>
</mml:math></inlineequation>,
the fog color index.
The initial fog index is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_COLOR</constant></term>
<listitem>
<para>
<parameter>params</parameter> contains four integer or floating-point values that specify
<inlineequation><mml:math>
<!-- eqn: C sub f:-->
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:msub>
</mml:math></inlineequation>,
the fog color.
Integer values are mapped linearly such that the most positive representable
value maps to 1.0,
and the most negative representable value maps to
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>.
Floating-point values are mapped directly.
After conversion,
all color components are clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>.
The initial fog color is (0, 0, 0, 0).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FOG_COORD_SRC</constant></term>
<listitem>
<para>
<parameter>params</parameter> contains either of the following symbolic constants:
<constant>GL_FOG_COORD</constant> or <constant>GL_FRAGMENT_DEPTH</constant>. <constant>GL_FOG_COORD</constant>
specifies that the current fog coordinate should be used as distance value
in the fog color computation. <constant>GL_FRAGMENT_DEPTH</constant> specifies that the
current fragment depth should be used as distance value in the fog
computation.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Fog blends a fog color with each rasterized pixel fragment's post-texturing
color using a blending factor
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
Factor
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
is computed in one of three ways,
depending on the fog mode.
Let
<inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
be either the distance in eye coordinate from the origin (in the
case that the <constant>GL_FOG_COORD_SRC</constant> is <constant>GL_FRAGMENT_DEPTH</constant>) or
the current fog coordinate (in the case that <constant>GL_FOG_COORD_SRC</constant>
is <constant>GL_FOG_COORD</constant>).
The equation for <constant>GL_LINEAR</constant> fog is
<informalequation><mml:math>
<!-- eqn: f = {end - c} over {end - start}:-->
<mml:mrow>
<mml:mi mathvariant="italic">f</mml:mi>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">end</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">c</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">end</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">start</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
The equation for <constant>GL_EXP</constant> fog is
<informalequation><mml:math>
<!-- eqn: f = e sup {-(density cdot c)}:-->
<mml:mrow>
<mml:mi mathvariant="italic">f</mml:mi>
<mml:mo>=</mml:mo>
<mml:msup><mml:mi mathvariant="italic">e</mml:mi>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">density</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mi mathvariant="italic">c</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mfenced>
</mml:msup>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
The equation for <constant>GL_EXP2</constant> fog is
<informalequation><mml:math>
<!-- eqn: f = e sup {-(density cdot c)} sup 2:-->
<mml:mrow>
<mml:mi mathvariant="italic">f</mml:mi>
<mml:mo>=</mml:mo>
<mml:msup><mml:mi mathvariant="italic">e</mml:mi>
<mml:msup><mml:mfenced open="" close="">
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mi mathvariant="italic">density</mml:mi>
<mml:mo>&CenterDot;</mml:mo>
<mml:mi mathvariant="italic">c</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mrow>
</mml:mfenced>
<mml:mn>2</mml:mn>
</mml:msup></mml:msup>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
Regardless of the fog mode,
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
is clamped to the range
<inlineequation><mml:math>
<!-- eqn: [0,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>0</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>
after it is computed.
Then,
if the GL is in RGBA color mode,
the fragment's red, green, and blue colors, represented by
<inlineequation><mml:math>
<!-- eqn: C sub r:-->
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:math></inlineequation>,
are replaced by
</para>
<para>
<informalequation><mml:math>
<!-- eqn: {C sub r} sup prime = f * C sub r + (1 - f) * C sub f:-->
<mml:mrow>
<mml:msup><mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&Prime;</mml:mo>
</mml:msup>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mrow>
<mml:mi mathvariant="italic">f</mml:mi>
<mml:mo>&times;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mrow>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mn>1</mml:mn>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&times;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
Fog does not affect a fragment's alpha component.
</para>
<para>
In color index mode, the fragment's color index
<inlineequation><mml:math>
<!-- eqn: i sub r:-->
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:math></inlineequation>
is replaced by
</para>
<para>
<informalequation><mml:math>
<!-- eqn: {i sub r} sup prime = i sub r + (1 - f) * i sub f:-->
<mml:mrow>
<mml:msup><mml:mfenced open="" close="">
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
</mml:mfenced>
<mml:mo>&Prime;</mml:mo>
</mml:msup>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
<mml:mi mathvariant="italic">r</mml:mi>
</mml:msub>
<mml:mo>+</mml:mo>
<mml:mrow>
<mml:mfenced open="(" close=")">
<mml:mrow>
<mml:mn>1</mml:mn>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mo>&times;</mml:mo>
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
<mml:mi mathvariant="italic">f</mml:mi>
</mml:msub>
</mml:mrow>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<constant>GL_FOG_COORD_SRC</constant> is available only if the GL version is 1.4 or
greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not an accepted value,
or if <parameter>pname</parameter> is <constant>GL_FOG_MODE</constant> and <parameter>params</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>pname</parameter> is <constant>GL_FOG_DENSITY</constant>
and <parameter>params</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFog</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_FOG</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COLOR</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_INDEX</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_DENSITY</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_START</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_END</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_MODE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

109
Source/Bind/Specifications/Docs/glFogCoord.xml Normal file
View file

@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFogCoord">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFogCoord</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFogCoord</refname>
<refpurpose>set the current fog coordinates</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogCoordd</function></funcdef>
<paramdef>GLdouble <parameter>coord</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogCoordf</function></funcdef>
<paramdef>GLfloat <parameter>coord</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>coord</parameter></term>
<listitem>
<para>
Specify the fog distance.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogCoorddv</function></funcdef>
<paramdef>GLdouble * <parameter>coord</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogCoordfv</function></funcdef>
<paramdef>GLfloat * <parameter>coord</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters2"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>coord</parameter></term>
<listitem>
<para>
Specifies a pointer to an array containing a single value representing the
fog distance.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glFogCoord</function> specifies the fog coordinate that is associated with each vertex and
the current raster position. The value specified is interpolated and used
in computing the fog color (see <citerefentry><refentrytitle>glFog</refentrytitle></citerefentry>).
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glFogCoord</function> is available only if the GL version is 1.4 or greater.
</para>
<para>
The current fog coordinate can be updated at any time. In particular,
<function>glFogCoord</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_FOG_COORD</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glFog</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

187
Source/Bind/Specifications/Docs/glFogCoordPointer.xml Normal file
View file

@ -0,0 +1,187 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFogCoordPointer">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFogCoordPointer</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFogCoordPointer</refname>
<refpurpose>define an array of fog coordinates</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFogCoordPointer</function></funcdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>GLsizei <parameter>stride</parameter></paramdef>
<paramdef>GLvoid * <parameter>pointer</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
Specifies the data type of each fog coordinate.
Symbolic constants
<constant>GL_FLOAT</constant>,
or <constant>GL_DOUBLE</constant>
are accepted. The initial value is <constant>GL_FLOAT</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>stride</parameter></term>
<listitem>
<para>
Specifies the byte offset between consecutive fog coordinates.
If <parameter>stride</parameter> is 0, the array elements are understood
to be tightly packed. The initial value is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pointer</parameter></term>
<listitem>
<para>
Specifies a pointer to the first coordinate of the first fog coordinate in the
array. The initial value is 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glFogCoordPointer</function> specifies the location and data format of an array of fog coordinates
to use when rendering. <parameter>type</parameter> specifies the data type of each fog
coordinate, and <parameter>stride</parameter> specifies the byte stride from one fog coordinate to
the next, allowing vertices and attributes to be packed into a single array
or stored in separate arrays.
</para>
<para>
If a non-zero named buffer object is bound to the <constant>GL_ARRAY_BUFFER</constant> target
(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a fog coordinate array is
specified, <parameter>pointer</parameter> is treated as a byte offset into the buffer object's data store.
Also, the buffer object binding (<constant>GL_ARRAY_BUFFER_BINDING</constant>) is saved as fog coordinate vertex array
client-side state (<constant>GL_FOG_COORD_ARRAY_BUFFER_BINDING</constant>).
</para>
<para>
When a fog coordinate array is specified,
<parameter>type</parameter>, <parameter>stride</parameter>, and <parameter>pointer</parameter> are saved as client-side
state, in addition to the current vertex array buffer object binding.
</para>
<para>
To enable and disable the fog coordinate array, call
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry> with the argument
<constant>GL_FOG_COORD_ARRAY</constant>. If
enabled, the fog coordinate array is used
when <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry> is called.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glFogCoordPointer</function> is available only if the GL version is 1.4 or greater.
</para>
<para>
Fog coordinates are not supported for interleaved vertex array formats
(see <citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>).
</para>
<para>
The fog coordinate array is initially disabled and isn't accessed when
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>
is called.
</para>
<para>
Execution of <function>glFogCoordPointer</function> is not allowed between the execution of
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
but an error may or may not be generated. If no error is generated,
the operation is undefined.
</para>
<para>
<function>glFogCoordPointer</function> is typically implemented on the client side with no protocol.
</para>
<para>
Fog coordinate array parameters are client-side state and are
therefore not saved or restored by <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>.
Use <citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry> instead.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not either <constant>GL_FLOAT</constant>
or <constant>GL_DOUBLE</constant>.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>stride</parameter> is negative.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_FOG_COORD_ARRAY</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COORD_ARRAY_STRIDE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COORD_ARRAY_TYPE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COORD_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ARRAY_BUFFER_BINDING</constant>
</para>
<para>
<citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry> with argument <constant>GL_FOG_COORD_ARRAY_POINTER</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glFogCoord</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

101
Source/Bind/Specifications/Docs/glFrontFace.xml Normal file
View file

@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFrontFace">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFrontFace</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFrontFace</refname>
<refpurpose>define front- and back-facing polygons</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFrontFace</function></funcdef>
<paramdef>GLenum <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
Specifies the orientation of front-facing polygons.
<constant>GL_CW</constant> and <constant>GL_CCW</constant> are accepted.
The initial value is <constant>GL_CCW</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
In a scene composed entirely of opaque closed surfaces,
back-facing polygons are never visible.
Eliminating these invisible polygons has the obvious benefit
of speeding up the rendering of the image.
To enable and disable elimination of back-facing polygons, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_CULL_FACE</constant>.
</para>
<para>
The projection of a polygon to window coordinates is said to have
clockwise winding if an imaginary object following the path
from its first vertex,
its second vertex,
and so on,
to its last vertex,
and finally back to its first vertex,
moves in a clockwise direction about the interior of the polygon.
The polygon's winding is said to be counterclockwise if the imaginary
object following the same path moves in a counterclockwise direction
about the interior of the polygon.
<function>glFrontFace</function> specifies whether polygons with clockwise winding in window coordinates,
or counterclockwise winding in window coordinates,
are taken to be front-facing.
Passing <constant>GL_CCW</constant> to <parameter>mode</parameter> selects counterclockwise polygons as
front-facing;
<constant>GL_CW</constant> selects clockwise polygons as front-facing.
By default, counterclockwise polygons are taken to be front-facing.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFrontFace</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FRONT_FACE</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCullFace</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

420
Source/Bind/Specifications/Docs/glFrustum.xml Normal file
View file

@ -0,0 +1,420 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glFrustum">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glFrustum</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glFrustum</refname>
<refpurpose>multiply the current matrix by a perspective matrix</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glFrustum</function></funcdef>
<paramdef>GLdouble <parameter>left</parameter></paramdef>
<paramdef>GLdouble <parameter>right</parameter></paramdef>
<paramdef>GLdouble <parameter>bottom</parameter></paramdef>
<paramdef>GLdouble <parameter>top</parameter></paramdef>
<paramdef>GLdouble <parameter>nearVal</parameter></paramdef>
<paramdef>GLdouble <parameter>farVal</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>left</parameter></term>
<term><parameter>right</parameter></term>
<listitem>
<para>
Specify the coordinates for the left and right vertical clipping planes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bottom</parameter></term>
<term><parameter>top</parameter></term>
<listitem>
<para>
Specify the coordinates for the bottom and top horizontal clipping planes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nearVal</parameter></term>
<term><parameter>farVal</parameter></term>
<listitem>
<para>
Specify the distances to the near and far depth clipping planes.
Both distances must be positive.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glFrustum</function> describes a perspective matrix that produces a perspective projection.
The current matrix (see <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>) is multiplied by this matrix
and the result replaces the current matrix, as if
<citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called with the following matrix
as its argument:
</para>
<para>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: left [ matrix { ccol { {{2 nearVal} over {right - left}} above 0 above 0 above 0 } ccol { 0 above {{2 nearVal} over {top - bottom}} above 0 above 0 } ccol { A above B above C above -1 } ccol { 0 above 0 above D above 0} } right ]:-->
<mml:mfenced open="[" close="]">
<mml:mtable>
<mml:mtr>
<mml:mtd>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">right</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">left</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mi mathvariant="italic">A</mml:mi>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
</mml:mtr>
<mml:mtr>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">top</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">bottom</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
</mml:mtd>
<mml:mtd>
<mml:mi mathvariant="italic">B</mml:mi>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
</mml:mtr>
<mml:mtr>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mi mathvariant="italic">C</mml:mi>
</mml:mtd>
<mml:mtd>
<mml:mi mathvariant="italic">D</mml:mi>
</mml:mtd>
</mml:mtr>
<mml:mtr>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mn>-1</mml:mn>
</mml:mtd>
<mml:mtd>
<mml:mn>0</mml:mn>
</mml:mtd>
</mml:mtr>
</mml:mtable>
</mml:mfenced>
</mml:math></informalequation>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: A = {right + left} over {right - left}:-->
<mml:mrow>
<mml:mi mathvariant="italic">A</mml:mi>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">right</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">left</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">right</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">left</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: B = {top + bottom} over {top - bottom}:-->
<mml:mrow>
<mml:mi mathvariant="italic">B</mml:mi>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">top</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">bottom</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">top</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">bottom</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: C = -{{farVal + nearVal} over {farVal - nearVal}}:-->
<mml:mrow>
<mml:mi mathvariant="italic">C</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
<informalequation><mml:math>
<!-- eqn: D = -{{2 farVal nearVal} over {farVal - nearVal}}:-->
<mml:mrow>
<mml:mi mathvariant="italic">D</mml:mi>
<mml:mo>=</mml:mo>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mfenced open="" close="">
<mml:mfrac>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mn>2</mml:mn>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mo>&it;</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
<mml:mfenced open="" close="">
<mml:mrow>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:mfrac>
</mml:mfenced>
</mml:mrow>
</mml:mrow>
</mml:math></informalequation>
</para>
<para>
</para>
<para>
Typically, the matrix mode is <constant>GL_PROJECTION</constant>, and
<inlineequation><mml:math>
<!-- eqn: (left, bottom, -nearVal):-->
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">left</mml:mi>
<mml:mi mathvariant="italic">bottom</mml:mi>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>
and
<inlineequation><mml:math>
<!-- eqn: (right, top, -nearVal):-->
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">right</mml:mi>
<mml:mi mathvariant="italic">top</mml:mi>
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math></inlineequation>
specify the points on the near clipping plane that are mapped
to the lower left and upper right corners of the window,
assuming that the eye is located at (0, 0, 0).
<inlineequation><mml:math>
<!-- eqn: -farVal:-->
<mml:mrow>
<mml:mo>-</mml:mo>
<mml:mi mathvariant="italic">farVal</mml:mi>
</mml:mrow>
</mml:math></inlineequation>
specifies the location of the far clipping plane.
Both <parameter>nearVal</parameter> and <parameter>farVal</parameter> must be positive.
</para>
<para>
Use <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to save and restore
the current matrix stack.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
Depth buffer precision is affected by the values specified for
<parameter>nearVal</parameter> and <parameter>farVal</parameter>.
The greater the ratio of <parameter>farVal</parameter> to <parameter>nearVal</parameter> is,
the less effective the depth buffer will be at distinguishing between
surfaces that are near each other.
If
</para>
<para>
<inlineequation><mml:math>
<!-- eqn: r = farVal over nearVal:-->
<mml:mrow>
<mml:mi mathvariant="italic">r</mml:mi>
<mml:mo>=</mml:mo>
<mml:mfrac>
<mml:mi mathvariant="italic">farVal</mml:mi>
<mml:mi mathvariant="italic">nearVal</mml:mi>
</mml:mfrac>
</mml:mrow>
</mml:math></inlineequation>
</para>
<para>
roughly
<inlineequation><mml:math>
<!-- eqn: log sub 2 (r):-->
<mml:mrow>
<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
<mml:mn>2</mml:mn>
</mml:msub>
<mml:mo>&af;</mml:mo>
<mml:mfenced open="(" close=")">
<mml:mi mathvariant="italic">r</mml:mi>
</mml:mfenced>
</mml:mrow>
</mml:math></inlineequation>
bits of depth buffer precision are lost.
Because
<inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>
approaches infinity as <parameter>nearVal</parameter> approaches 0,
<parameter>nearVal</parameter> must never be set to 0.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>nearVal</parameter> or <parameter>farVal</parameter> is not
positive, or if <parameter>left</parameter> = <parameter>right</parameter>, or <parameter>bottom</parameter> = <parameter>top</parameter>,
or <parameter>near</parameter> = <parameter>far</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFrustum</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MATRIX_MODE</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MODELVIEW_MATRIX</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PROJECTION_MATRIX</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_MATRIX</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATRIX</constant>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glOrtho</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glViewport</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

100
Source/Bind/Specifications/Docs/glGenBuffers.xml Normal file
View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glGenBuffers">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glGenBuffers</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGenBuffers</refname>
<refpurpose>generate buffer object names</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glGenBuffers</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>GLuint * <parameter>buffers</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of buffer object names to be generated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffers</parameter></term>
<listitem>
<para>
Specifies an array in which the generated buffer object names are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glGenBuffers</function> returns <parameter>n</parameter> buffer object names in <parameter>buffers</parameter>.
There is no guarantee that the names form a contiguous set of integers;
however, it is guaranteed that none of the returned names was in use
immediately before the call to <function>glGenBuffers</function>.
</para>
<para>
Buffer object names returned by a call to <function>glGenBuffers</function> are not returned by
subsequent calls, unless they are first deleted with
<citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry>.
</para>
<para>
No buffer objects are associated with the returned buffer object names until they are first bound by calling
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glGenBuffers</function> is available only if the GL version is 1.5 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGenBuffers</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

108
Source/Bind/Specifications/Docs/glGenLists.xml Normal file
View file

@ -0,0 +1,108 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glGenLists">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glGenLists</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGenLists</refname>
<refpurpose>generate a contiguous set of empty display lists</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>GLuint <function>glGenLists</function></funcdef>
<paramdef>GLsizei <parameter>range</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>range</parameter></term>
<listitem>
<para>
Specifies the number of contiguous empty display lists
to be generated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glGenLists</function> has one argument, <parameter>range</parameter>.
It returns an integer <emphasis>n</emphasis> such that <parameter>range</parameter> contiguous
empty display lists,
named
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: n+1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: ...:-->
<mml:mi mathvariant="italic">...</mml:mi>
</mml:math></inlineequation>,
<inlineequation><mml:math>
<!-- eqn: n + range - 1:-->
<mml:mrow>
<mml:mi mathvariant="italic">n</mml:mi>
<mml:mo>+</mml:mo>
<mml:mi mathvariant="italic">range</mml:mi>
<mml:mo>-</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
</mml:math></inlineequation>,
are created.
If <parameter>range</parameter> is 0,
if there is no group of <parameter>range</parameter> contiguous names available,
or if any error is generated,
no display lists are generated,
and 0 is returned.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>range</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGenLists</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

105
Source/Bind/Specifications/Docs/glGenQueries.xml Normal file
View file

@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glGenQueries">
<refmeta>
<refmetainfo>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
</refmetainfo>
<refentrytitle>glGenQueries</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGenQueries</refname>
<refpurpose>generate query object names</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glGenQueries</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>GLuint * <parameter>ids</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of query object names to be generated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ids</parameter></term>
<listitem>
<para>
Specifies an array in which the generated query object names are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glGenQueries</function> returns <parameter>n</parameter> query object names in <parameter>ids</parameter>.
There is no guarantee that the names form a contiguous set of integers;
however, it is guaranteed that none of the returned names was in use
immediately before the call to <function>glGenQueries</function>.
</para>
<para>
Query object names returned by a call to <function>glGenQueries</function> are not returned by
subsequent calls, unless they are first deleted with
<citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>.
</para>
<para>
No query objects are associated with the returned query object names until they are first used by calling
<citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glGenQueries</function> is available only if the GL version is 1.5 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGenQueries</function> is executed
between the execution of <citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGenQueries</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsQuery</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>

108
Source/Bind/Specifications/Docs/glGenTextures.xml Normal file
View file

@ -0,0 +1,108 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glGenTextures">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glGenTextures</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGenTextures</refname>
<refpurpose>generate texture names</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glGenTextures</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>GLuint * <parameter>textures</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
Specifies the number of texture names to be generated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>textures</parameter></term>
<listitem>
<para>
Specifies an array in which the generated texture names are stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glGenTextures</function> returns <parameter>n</parameter> texture names in <parameter>textures</parameter>.
There is no guarantee that the names form a contiguous set of integers;
however, it is guaranteed that none of the returned names was in use
immediately before the call to <function>glGenTextures</function>.
</para>
<para>
The generated textures have no dimensionality; they assume the dimensionality
of the texture target to which they are first bound
(see <citerefentry><refentrytitle>glBindTexture</refentrytitle></citerefentry>).
</para>
<para>
Texture names returned by a call to <function>glGenTextures</function> are not returned by
subsequent calls, unless they are first deleted with
<citerefentry><refentrytitle>glDeleteTextures</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
<function>glGenTextures</function> is available only if the GL version is 1.1 or greater.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGenTextures</function> is executed
between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glIsTexture</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindTexture</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDeleteTextures</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
</para>
</refsect1>
</refentry>

4897
Source/Bind/Specifications/Docs/glGet.xml Normal file
View file

File diff suppressed because it is too large Load diff

Some files were not shown because too many files have changed in this diff Show more