upstream-man-pages/man3/glBindFragDataLocation.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="glBindFragDataLocation">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glBindFragDataLocation</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glBindFragDataLocation</refname>
  17         <refpurpose>bind a user-defined varying out variable to a fragment shader color number</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glBindFragDataLocation</function></funcdef>
  23                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  24                 <paramdef>GLuint <parameter>colorNumber</parameter></paramdef>
  25                 <paramdef>const char * <parameter>name</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>program</parameter></term>
  33             <listitem>
  34                 <para>
  35                     The name of the program containing varying out variable whose binding to modify
  36                 </para>
  37             </listitem>
  38         </varlistentry>
  39         <varlistentry>
  40             <term><parameter>colorNumber</parameter></term>
  41             <listitem>
  42                 <para>
  43                     The color number to bind the user-defined varying out variable to
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         <varlistentry>
  48             <term><parameter>name</parameter></term>
  49             <listitem>
  50                 <para>
  51                     The name of the user-defined varying out variable whose binding to modify
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         </variablelist>
  56     </refsect1>
  57     <refsect1 id="description"><title>Description</title>
  58         <para>
  59             <function>glBindFragDataLocation</function> explicitly specifies the binding of the user-defined varying out variable
  60             <parameter>name</parameter> to fragment shader color number <parameter>colorNumber</parameter> for program
  61             <parameter>program</parameter>. If <parameter>name</parameter> was bound previously, its assigned binding is replaced
  62             with <parameter>colorNumber</parameter>. <parameter>name</parameter> must be a null-terminated string. <parameter>colorNumber</parameter>
  63             must be less than <constant>GL_MAX_DRAW_BUFFERS</constant>.
  64         </para>
  65         <para>
  66             The bindings specified by <function>glBindFragDataLocation</function> have no effect until <parameter>program</parameter>
  67             is next linked. Bindings may be specified at any time after <parameter>program</parameter> has been created. Specifically,
  68             they may be specified before shader objects are attached to the program. Therefore, any name may be specified in <parameter>name</parameter>,
  69             including a name that is never used as a varying out variable in any fragment shader object. Names beginning with <constant>gl_</constant> are
  70             reserved by the GL.
  71         </para>
  72         <para>
  73             In addition to the errors generated by <function>glBindFragDataLocation</function>, the
  74             program <parameter>program</parameter> will fail to link if:
  75             <itemizedlist>
  76                 <listitem>
  77                     <para>
  78                         The number of active outputs is greater than the value <constant>GL_MAX_DRAW_BUFFERS</constant>.
  79                     </para>
  80                 </listitem>
  81                 <listitem>
  82                     <para>
  83                         More than one varying out variable is bound to the same color number.
  84                     </para>
  85                 </listitem>
  86             </itemizedlist>
  87         </para>
  88     </refsect1>
  89     <refsect1 id="notes"><title>Notes</title>
  90         <para>
  91             Varying out varyings may have indexed locations assigned explicitly in the shader text using a <code>location</code>
  92             layout qualifier. If a shader statically assigns a location to a varying out variable in the shader text,
  93             that location is used and any location assigned with <function>glBindFragDataLocation</function> is ignored.
  94         </para>
  95     </refsect1>
  96     <refsect1 id="errors"><title>Errors</title>
  97         <para>
  98             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>colorNumber</parameter> is greater than or equal to <constant>GL_MAX_DRAW_BUFFERS</constant>.
  99         </para>
 100         <para>
 101             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>name</parameter> starts with the reserved <constant>gl_</constant> prefix.
 102         </para>
 103         <para>
 104             <constant>GL_INVALID_OPERATION</constant> is generated if <function>program</function> is not the name of a program object.
 105         </para>
 106     </refsect1>
 107     <refsect1 id="associatedgets"><title>Associated Gets</title>
 108         <para>
 109             <citerefentry><refentrytitle>glGetFragDataLocation</refentrytitle></citerefentry> with a valid program object
 110             and the the name of a user-defined varying out variable
 111         </para>
 112     </refsect1>
 113     <refsect1 id="seealso"><title>See Also</title>
 114         <para>
 115             <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 116             <citerefentry><refentrytitle>glGetFragDataLocation</refentrytitle></citerefentry>
 117         </para>
 118     </refsect1>
 119     <refsect1 id="Copyright"><title>Copyright</title>
 120         <para>
 121             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 122             This material may be distributed subject to the terms and conditions set forth in
 123             the Open Publication License, v 1.0, 8 June 1999.
 124             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 125         </para>
 126     </refsect1>
 127 </refentry>