upstream-doc/man3/glFramebufferTexture.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="glFramebufferTexture">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glFramebufferTexture</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glFramebufferTexture</refname>
  17         <refpurpose>attach a level of a texture object as a logical buffer to the currently bound framebuffer object</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glFramebufferTexture</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>attachment</parameter></paramdef>
  25                 <paramdef>GLuint <parameter>texture</parameter></paramdef>
  26                 <paramdef>GLint <parameter>level</parameter></paramdef>
  27             </funcprototype>
  28             <funcprototype>
  29                 <funcdef>void <function>glFramebufferTexture1D</function></funcdef>
  30                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  31                 <paramdef>GLenum <parameter>attachment</parameter></paramdef>
  32                 <paramdef>GLenum <parameter>textarget</parameter></paramdef>
  33                 <paramdef>GLuint <parameter>texture</parameter></paramdef>
  34                 <paramdef>GLint <parameter>level</parameter></paramdef>
  35             </funcprototype>
  36             <funcprototype>
  37                 <funcdef>void <function>glFramebufferTexture2D</function></funcdef>
  38                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  39                 <paramdef>GLenum <parameter>attachment</parameter></paramdef>
  40                 <paramdef>GLenum <parameter>textarget</parameter></paramdef>
  41                 <paramdef>GLuint <parameter>texture</parameter></paramdef>
  42                 <paramdef>GLint <parameter>level</parameter></paramdef>
  43             </funcprototype>
  44             <funcprototype>
  45                 <funcdef>void <function>glFramebufferTexture3D</function></funcdef>
  46                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  47                 <paramdef>GLenum <parameter>attachment</parameter></paramdef>
  48                 <paramdef>GLenum <parameter>textarget</parameter></paramdef>
  49                 <paramdef>GLuint <parameter>texture</parameter></paramdef>
  50                 <paramdef>GLint <parameter>level</parameter></paramdef>
  51                 <paramdef>GLint <parameter>layer</parameter></paramdef>
  52             </funcprototype>
  53         </funcsynopsis>
  54     </refsynopsisdiv>
  55     <!-- eqn: ignoring delim $$ -->
  56     <refsect1 id="parameters"><title>Parameters</title>
  57         <variablelist>
  58         <varlistentry>
  59             <term><parameter>target</parameter></term>
  60             <listitem>
  61                 <para>
  62                     Specifies the framebuffer target. <parameter>target</parameter> must be <constant>GL_DRAW_FRAMEBUFFER</constant>,
  63                     <constant>GL_READ_FRAMEBUFFER</constant>, or <constant>GL_FRAMEBUFFER</constant>. <constant>GL_FRAMEBUFFER</constant>
  64                     is equivalent to <constant>GL_DRAW_FRAMEBUFFER</constant>.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         <varlistentry>
  69             <term><parameter>attachment</parameter></term>
  70             <listitem>
  71                 <para>
  72                     Specifies the attachment point of the framebuffer. <parameter>attachment</parameter> must be
  73                     <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant>, <constant>GL_DEPTH_ATTACHMENT</constant>,
  74                     <constant>GL_STENCIL_ATTACHMENT</constant> or <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>.
  75                 </para>
  76             </listitem>
  77         </varlistentry>
  78         <varlistentry>
  79             <term><parameter>textarget</parameter></term>
  80             <listitem>
  81                 <para>
  82                     For <function>glFramebufferTexture1D</function>, <function>glFramebufferTexture2D</function> and
  83                     <function>glFramebufferTexture3D</function>, specifies what type of texture is expected
  84                     in the <parameter>texture</parameter> parameter, or for cube map textures, which face is to be attached.
  85                 </para>
  86             </listitem>
  87         </varlistentry>
  88         <varlistentry>
  89             <term><parameter>texture</parameter></term>
  90             <listitem>
  91                 <para>
  92                     Specifies the texture object to attach to the framebuffer attachment point named by <parameter>attachment</parameter>.
  93                 </para>
  94             </listitem>
  95         </varlistentry>
  96         <varlistentry>
  97             <term><parameter>level</parameter></term>
  98             <listitem>
  99                 <para>
 100                     Specifies the mipmap level of <parameter>texture</parameter> to attach.
 101                 </para>
 102             </listitem>
 103         </varlistentry>
 104         </variablelist>
 105     </refsect1>
 106     <refsect1 id="description"><title>Description</title>
 107         <para>
 108             <function>glFramebufferTexture</function>, <function>glFramebufferTexture1D</function>, <function>glFramebufferTexture2D</function>,
 109             and <function>glFramebufferTexture</function> attach a selected mipmap level or image of a texture object as one of the
 110             logical buffers of the framebuffer object currently bound to <parameter>target</parameter>. <parameter>target</parameter> must
 111             be <constant>GL_DRAW_FRAMEBUFFER</constant>, <constant>GL_READ_FRAMEBUFFER</constant>, or <constant>GL_FRAMEBUFFER</constant>.
 112             <constant>GL_FRAMEBUFFER</constant> is equivalent to <constant>GL_DRAW_FRAMEBUFFER</constant>.
 113         </para>
 114         <para>
 115             <parameter>attachment</parameter> specifies the logical attachment of the framebuffer and must be
 116             <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant>, <constant>GL_DEPTH_ATTACHMENT</constant>,
 117             <constant>GL_STENCIL_ATTACHMENT</constant> or <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>.
 118             <emphasis>i</emphasis> in <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant> may range from zero to
 119             the value of <constant>GL_MAX_COLOR_ATTACHMENTS</constant> - 1. Attaching a level of a texture to
 120             <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant> is equivalent to attaching that level to both the
 121             <constant>GL_DEPTH_ATTACHMENT</constant> <emphasis>and</emphasis> the <constant>GL_STENCIL_ATTACHMENT</constant>
 122             attachment points simultaneously.
 123         </para>
 124         <para>
 125             <parameter>textarget</parameter> specifies what type of texture is named by <parameter>texture</parameter>, and for
 126             cube map textures, specifies the face that is to be attached. If <parameter>texture</parameter> is not zero, it
 127             must be the name of an existing texture with type <parameter>textarget</parameter>, unless it is a cube map
 128             texture, in which case <parameter>textarget</parameter> must be <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>
 129             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 130             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
 131             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
 132         </para>
 133         <para>
 134             If <parameter>texture</parameter> is non-zero, the specified <parameter>level</parameter> of the texture object named
 135             <parameter>texture</parameter> is attached to the framebfufer attachment point named by <parameter>attachment</parameter>.
 136             For <function>glFramebufferTexture1D</function>, <function>glFramebufferTexture2D</function>, and
 137             <function>glFramebufferTexture3D</function>, <parameter>texture</parameter> must be zero or the name of an existing
 138             texture with a target of <parameter>textarget</parameter>, or <parameter>texture</parameter> must be the name
 139             of an existing cube-map texture and <parameter>textarget</parameter> must be one of <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 140             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 141             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>, <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, or
 142             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
 143         </para>
 144         <para>
 145             If  <parameter>textarget</parameter> is  <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>,
 146             or <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant>, then <parameter>level</parameter> must be zero. If <parameter>textarget</parameter>
 147             is <constant>GL_TEXTURE_3D</constant>, then level must be greater than or equal to zero and less than or equal to log<subscript>2</subscript>
 148             of the value of <constant>GL_MAX_3D_TEXTURE_SIZE</constant>. If <parameter>textarget</parameter> is one of <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 149             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 150             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, or <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, then <parameter>level</parameter> must be greater
 151             than or equal to zero and less than or equal to log<subscript>2</subscript> of the value of <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant>. For all other
 152             values of <parameter>textarget</parameter>, <parameter>level</parameter> must be greater than or equal to zero and no larger than log<subscript>2</subscript>
 153             of the value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 154         </para>
 155         <para>
 156             <parameter>layer</parameter> specifies the layer of a 2-dimensional image within a 3-dimensional texture.
 157         </para>
 158         <para>
 159             For <function>glFramebufferTexture1D</function>, if <parameter>texture</parameter> is not zero, then <parameter>textarget</parameter> must
 160             be <constant>GL_TEXTURE_1D</constant>. For <function>glFramebufferTexture2D</function>, if <parameter>texture</parameter> is not zero,
 161             <parameter>textarget</parameter> must be one of <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_RECTANGLE</constant>,
 162             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>, <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 163             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>, <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>, <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 164             <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>. For <function>glFramebufferTexture3D</function>, if <parameter>texture</parameter> is
 165             not zero, then <parameter>textarget</parameter> must be <constant>GL_TEXTURE_3D</constant>.
 166         </para>
 167     </refsect1>
 168     <refsect1 id="notes"><title>Notes</title>
 169         <para>
 170             <function>glFramebufferTexture</function> is available only if the GL version is 3.2 or greater.
 171         </para>
 172     </refsect1>
 173     <refsect1 id="errors"><title>Errors</title>
 174         <para>
 175             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the accepted tokens.
 176         </para>
 177         <para>
 178             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>renderbuffertarget</parameter> is not <constant>GL_RENDERBUFFER</constant>.
 179         </para>
 180         <para>
 181             <constant>GL_INVALID_OPERATION</constant> is generated if zero is bound to <parameter>target</parameter>.
 182         </para>
 183         <para>
 184             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>textarget</parameter> and <parameter>texture</parameter>
 185             are not compatible.
 186         </para>
 187     </refsect1>
 188     <refsect1 id="seealso"><title>See Also</title>
 189         <para>
 190             <citerefentry><refentrytitle>glGenFramebuffers</refentrytitle></citerefentry>,
 191             <citerefentry><refentrytitle>glBindFramebuffer</refentrytitle></citerefentry>,
 192             <citerefentry><refentrytitle>glGenRenderbuffers</refentrytitle></citerefentry>,
 193             <citerefentry><refentrytitle>glFramebufferTexture</refentrytitle></citerefentry>,
 194             <citerefentry><refentrytitle>glFramebufferTexture1D</refentrytitle></citerefentry>,
 195             <citerefentry><refentrytitle>glFramebufferTexture2D</refentrytitle></citerefentry>,
 196             <citerefentry><refentrytitle>glFramebufferTexture3D</refentrytitle></citerefentry>
 197         </para>
 198     </refsect1>
 199     <refsect1 id="Copyright"><title>Copyright</title>
 200         <para>
 201             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 202             This material may be distributed subject to the terms and conditions set forth in
 203             the Open Publication License, v 1.0, 8 June 1999.
 204             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 205         </para>
 206     </refsect1>
 207 </refentry>