upstream-man-pages/man3/glBindFragDataLocationIndexed.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glBindFragDataLocationIndexed">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glBindFragDataLocationIndexed</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glBindFragDataLocationIndexed</refname>
  17         <refpurpose>bind a user-defined varying out variable to a fragment shader color number and index</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glBindFragDataLocationIndexed</function></funcdef>
  23                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  24                 <paramdef>GLuint <parameter>colorNumber</parameter></paramdef>
  25                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  26                 <paramdef>const char *<parameter>name</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>program</parameter></term>
  34             <listitem>
  35                 <para>
  36                     The name of the program containing varying out variable whose binding to modify
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>colorNumber</parameter></term>
  42             <listitem>
  43                 <para>
  44                     The color number to bind the user-defined varying out variable to
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>index</parameter></term>
  50             <listitem>
  51                 <para>
  52                     The index of the color input to bind the user-defined varying out variable to
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57             <term><parameter>name</parameter></term>
  58             <listitem>
  59                 <para>
  60                     The name of the user-defined varying out variable whose binding to modify
  61                 </para>
  62             </listitem>
  63         </varlistentry>
  64         </variablelist>
  65     </refsect1>
  66     <refsect1 id="description"><title>Description</title>
  67         <para>
  68             <function>glBindFragDataLocationIndexed</function> specifies that the varying out variable <parameter>name</parameter> in
  69             <parameter>program</parameter> should be bound to fragment color <parameter>colorNumber</parameter> when the program is next
  70             linked. <parameter>index</parameter> may be zero or one to specify that the color be used as either the first or second color
  71             input to the blend equation, respectively.
  72         </para>
  73         <para>
  74             The bindings specified by <function>glBindFragDataLocationIndexed</function> have no effect until <parameter>program</parameter>
  75             is next linked. Bindings may be specified at any time after <parameter>program</parameter> has been created. Specifically,
  76             they may be specified before shader objects are attached to the program. Therefore, any name may be specified in <parameter>name</parameter>,
  77             including a name that is never used as a varying out variable in any fragment shader object. Names beginning with <constant>gl_</constant> are
  78             reserved by the GL.
  79         </para>
  80         <para>
  81             If <parameter>name</parameter> was bound previously, its assigned binding is replaced with <parameter>colorNumber</parameter> and
  82             <parameter>index</parameter>. <parameter>name</parameter> must be a null-terminated string. <parameter>index</parameter> must be less than or equal to one,
  83             and <parameter>colorNumber</parameter> must be less than the value of <constant>GL_MAX_DRAW_BUFFERS</constant> if <parameter>index</parameter>
  84             is zero, and less than the value of <constant>GL_MAX_DUAL_SOURCE_DRAW_BUFFERS</constant> if index is greater than or equal to one.
  85         </para>
  86         <para>
  87             In addition to the errors generated by <function>glBindFragDataLocationIndexed</function>, the
  88             program <parameter>program</parameter> will fail to link if:
  89             <itemizedlist>
  90                 <listitem>
  91                     <para>
  92                         The number of active outputs is greater than the value <constant>GL_MAX_DRAW_BUFFERS</constant>.
  93                     </para>
  94                 </listitem>
  95                 <listitem>
  96                     <para>
  97                         More than one varying out variable is bound to the same color number.
  98                     </para>
  99                 </listitem>
 100             </itemizedlist>
 101         </para>
 102     </refsect1>
 103     <refsect1 id="notes"><title>Notes</title>
 104         <para>
 105             Varying out varyings may have locations assigned explicitly in the shader text using a <code>location</code>
 106             layout qualifier. If a shader statically assigns a location to a varying out variable in the shader text,
 107             that location is used and any location assigned with <function>glBindFragDataLocation</function> is ignored.
 108         </para>
 109     </refsect1>
 110     <refsect1 id="errors"><title>Errors</title>
 111         <para>
 112             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>colorNumber</parameter> is greater than or equal to <constant>GL_MAX_DRAW_BUFFERS</constant>.
 113         </para>
 114         <para>
 115             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>colorNumber</parameter> is greater than or equal to <constant>GL_MAX_DUAL_SOURCE_DRAW_BUFERS</constant>
 116             and <parameter>index</parameter> is greater than or equal to one.
 117         </para>
 118         <para>
 119             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>index</parameter> is greater than one.
 120         </para>
 121         <para>
 122             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>name</parameter> starts with the reserved <constant>gl_</constant> prefix.
 123         </para>
 124         <para>
 125             <constant>GL_INVALID_OPERATION</constant> is generated if <function>program</function> is not the name of a program object.
 126         </para>
 127     </refsect1>
 128     <refsect1 id="associatedgets"><title>Associated Gets</title>
 129         <para>
 130             <citerefentry><refentrytitle>glGetFragDataLocation</refentrytitle></citerefentry> with a valid program object
 131             and the the name of a user-defined varying out variable
 132         </para>
 133         <para>
 134             <citerefentry><refentrytitle>glGetFragDataIndex</refentrytitle></citerefentry> with a valid program object
 135             and the the name of a user-defined varying out variable
 136         </para>
 137     </refsect1>
 138     <refsect1 id="seealso"><title>See Also</title>
 139         <para>
 140             <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 141             <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
 142             <citerefentry><refentrytitle>glGetFragDataLocation</refentrytitle></citerefentry>,
 143             <citerefentry><refentrytitle>glGetFragDataIndex</refentrytitle></citerefentry>
 144             <citerefentry><refentrytitle>glBindFragDataLocation</refentrytitle></citerefentry>
 145         </para>
 146     </refsect1>
 147     <refsect1 id="Copyright"><title>Copyright</title>
 148         <para>
 149             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 150             This material may be distributed subject to the terms and conditions set forth in
 151             the Open Publication License, v 1.0, 8 June 1999.
 152             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 153         </para>
 154     </refsect1>
 155 </refentry>