| 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="glDrawBuffers"> |
| 5 | <refmeta> |
| 6 | <refentrytitle>glDrawBuffers</refentrytitle> |
| 7 | <manvolnum>3G</manvolnum> |
| 8 | </refmeta> |
| 9 | <refnamediv> |
| 10 | <refname>glDrawBuffers</refname> |
| 11 | <refpurpose>Specifies a list of color buffers to be drawn into</refpurpose> |
| 12 | </refnamediv> |
| 13 | <refsynopsisdiv><title>C Specification</title> |
| 14 | <funcsynopsis> |
| 15 | <funcprototype> |
| 16 | <funcdef>void <function>glDrawBuffers</function></funcdef> |
| 17 | <paramdef>GLsizei <parameter>n</parameter></paramdef> |
| 18 | <paramdef>const GLenum *<parameter>bufs</parameter></paramdef> |
| 19 | </funcprototype> |
| 20 | </funcsynopsis> |
| 21 | </refsynopsisdiv> |
| 22 | <refsect1 id="parameters"><title>Parameters</title> |
| 23 | <variablelist> |
| 24 | <varlistentry> |
| 25 | <term><parameter>n</parameter></term> |
| 26 | <listitem> |
| 27 | <para>Specifies the number of buffers in |
| 28 | <parameter>bufs</parameter>.</para> |
| 29 | </listitem> |
| 30 | </varlistentry> |
| 31 | <varlistentry> |
| 32 | <term><parameter>bufs</parameter></term> |
| 33 | <listitem> |
| 34 | <para>Points to an array of symbolic constants |
| 35 | specifying the buffers into which fragment colors or |
| 36 | data values will be written.</para> |
| 37 | </listitem> |
| 38 | </varlistentry> |
| 39 | </variablelist> |
| 40 | </refsect1> |
| 41 | <refsect1 id="description"><title>Description</title> |
| 42 | <para><function>glDrawBuffers</function> defines an array of |
| 43 | buffers into which outputs from the fragment shader data will |
| 44 | be written. If a fragment shader writes a value |
| 45 | to one or more user defined output |
| 46 | variables, then the value of each variable will be written into the |
| 47 | buffer specified at a location within <parameter>bufs</parameter> |
| 48 | corresponding to the location assigned to that user defined output. |
| 49 | The draw buffer used for user defined outputs assigned to locations |
| 50 | greater than or equal to <parameter>n</parameter> is implicitly set |
| 51 | to <constant>GL_NONE</constant> and any data written to such an output |
| 52 | is discarded.</para> |
| 53 | |
| 54 | <para>The symbolic constants contained in |
| 55 | <parameter>bufs</parameter> may be any of the following:</para> |
| 56 | |
| 57 | <variablelist> |
| 58 | <varlistentry> |
| 59 | <term><constant>GL_NONE</constant></term> |
| 60 | <listitem> |
| 61 | <para>The fragment shader output value is not written into |
| 62 | any color buffer.</para> |
| 63 | </listitem> |
| 64 | </varlistentry> |
| 65 | <varlistentry> |
| 66 | <term><constant>GL_FRONT_LEFT</constant></term> |
| 67 | <listitem> |
| 68 | <para>The fragment shader output value is written into the |
| 69 | front left color buffer.</para> |
| 70 | </listitem> |
| 71 | </varlistentry> |
| 72 | <varlistentry> |
| 73 | <term><constant>GL_FRONT_RIGHT</constant></term> |
| 74 | <listitem> |
| 75 | <para>The fragment shader output value is written into the |
| 76 | front right color buffer.</para> |
| 77 | </listitem> |
| 78 | </varlistentry> |
| 79 | <varlistentry> |
| 80 | <term><constant>GL_BACK_LEFT</constant></term> |
| 81 | <listitem> |
| 82 | <para>The fragment shader output value is written into the |
| 83 | back left color buffer.</para> |
| 84 | </listitem> |
| 85 | </varlistentry> |
| 86 | <varlistentry> |
| 87 | <term><constant>GL_BACK_RIGHT</constant></term> |
| 88 | <listitem> |
| 89 | <para>The fragment shader output value is written into the |
| 90 | back right color buffer.</para> |
| 91 | </listitem> |
| 92 | </varlistentry> |
| 93 | <varlistentry> |
| 94 | <term><constant>GL_COLOR_ATTACHMENT<emphasis>n</emphasis></constant></term> |
| 95 | <listitem> |
| 96 | <para>The fragment shader output value is written into the |
| 97 | <emphasis>n</emphasis>th color attachment of the current framebuffer. |
| 98 | <emphasis>n</emphasis> may range from 0 to the value of |
| 99 | <constant>GL_MAX_COLOR_ATTACHMENTS</constant>.</para> |
| 100 | </listitem> |
| 101 | </varlistentry> |
| 102 | </variablelist> |
| 103 | |
| 104 | <para>Except for <constant>GL_NONE</constant>, the preceding |
| 105 | symbolic constants may not appear more than once in |
| 106 | <parameter>bufs</parameter>. The maximum number of draw buffers |
| 107 | supported is implementation dependent and can be queried by |
| 108 | calling |
| 109 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> |
| 110 | with the argument <constant>GL_MAX_DRAW_BUFFERS</constant>.</para> |
| 111 | </refsect1> |
| 112 | <refsect1 id="notes"><title>Notes</title> |
| 113 | |
| 114 | <para>The symbolic constants <constant>GL_FRONT</constant>, |
| 115 | <constant>GL_BACK</constant>, <constant>GL_LEFT</constant>, |
| 116 | <constant>GL_RIGHT</constant>, and |
| 117 | <constant>GL_FRONT_AND_BACK</constant> are not allowed in the |
| 118 | <parameter>bufs</parameter> array since they may refer to |
| 119 | multiple buffers.</para> |
| 120 | |
| 121 | <para>If a fragment shader does not write to a user defined output variable, |
| 122 | the values of the fragment |
| 123 | colors following shader execution are undefined. For each |
| 124 | fragment generated in this situation, a different value may be |
| 125 | written into each of the buffers specified by |
| 126 | <parameter>bufs</parameter>.</para> |
| 127 | </refsect1> |
| 128 | <refsect1 id="errors"><title>Errors</title> |
| 129 | <para><constant>GL_INVALID_ENUM</constant> is generated if one of the |
| 130 | values in <parameter>bufs</parameter> is not an accepted |
| 131 | value.</para> |
| 132 | |
| 133 | <para><constant>GL_INVALID_ENUM</constant> is generated if the GL is bound |
| 134 | to the default framebuffer and one or more of the values in |
| 135 | <parameter>bufs</parameter> is one of the <constant>GL_COLOR_ATTACHMENT<emphasis>n</emphasis></constant> |
| 136 | tokens.</para> |
| 137 | |
| 138 | <para><constant>GL_INVALID_ENUM</constant> is generated if the GL is bound |
| 139 | to a framebuffer object and one or more of the values in <parameter>bufs</parameter> |
| 140 | is anything other than <constant>GL_NONE</constant> or one of the |
| 141 | <constant>GL_COLOR_ATTACHMENTS<emphasis>n</emphasis></constant> tokens.</para> |
| 142 | |
| 143 | <para><constant>GL_INVALID_ENUM</constant> is generated if |
| 144 | <parameter>n</parameter> is less than 0.</para> |
| 145 | |
| 146 | <para><constant>GL_INVALID_OPERATION</constant> is generated if a |
| 147 | symbolic constant other than <constant>GL_NONE</constant> |
| 148 | appears more than once in <parameter>bufs</parameter>.</para> |
| 149 | |
| 150 | <para><constant>GL_INVALID_OPERATION</constant> is generated if any of |
| 151 | the entries in <parameter>bufs</parameter> (other than |
| 152 | <constant>GL_NONE</constant> ) indicates a color buffer that |
| 153 | does not exist in the current GL context.</para> |
| 154 | |
| 155 | <para><constant>GL_INVALID_VALUE</constant> is generated if |
| 156 | <parameter>n</parameter> is greater than |
| 157 | <constant>GL_MAX_DRAW_BUFFERS</constant>.</para> |
| 158 | |
| 159 | </refsect1> |
| 160 | <refsect1 id="associatedgets"><title>Associated Gets</title> |
| 161 | <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> |
| 162 | with argument <constant>GL_MAX_DRAW_BUFFERS</constant></para> |
| 163 | |
| 164 | <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> |
| 165 | with argument <constant>GL_DRAW_BUFFER<emphasis>i</emphasis></constant> where |
| 166 | <code><emphasis>i</emphasis></code> indicates the number of the draw buffer |
| 167 | whose value is to be queried</para> |
| 168 | </refsect1> |
| 169 | <refsect1 id="seealso"><title>See Also</title> |
| 170 | <para> <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>, |
| 171 | <citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>, |
| 172 | <citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>, |
| 173 | <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>, |
| 174 | <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry></para> |
| 175 | </refsect1> |
| 176 | <refsect1 id="Copyright"><title>Copyright</title> |
| 177 | <para> |
| 178 | Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd. |
| 179 | This material may be distributed subject to the terms and conditions set forth in |
| 180 | the Open Publication License, v 1.0, 8 June 1999. |
| 181 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. |
| 182 | </para> |
| 183 | </refsect1> |
| 184 | </refentry> |