upstream-doc/man4/glGetFramebufferAttachmentParameter.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="glGetFramebufferAttachmentParameter">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetFramebufferAttachmentParameteriv</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetFramebufferAttachmentParameteriv</refname>
  17         <refpurpose>retrieve information about attachments of a bound framebuffer object</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetFramebufferAttachmentParameteriv</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>attachment</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  26                 <paramdef>GLint *<parameter>params</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <!-- eqn: ignoring delim $$ -->
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>target</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specifies the target of the query operation.
  38                 </para>
  39             </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42             <term><parameter>attachment</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies the attachment within <parameter>target</parameter>
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>pname</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the parameter of <parameter>attachment</parameter> to query.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         <varlistentry>
  58             <term><parameter>params</parameter></term>
  59             <listitem>
  60                 <para>
  61                     Specifies the address of a variable receive the value of <parameter>pname</parameter> for <parameter>attachment</parameter>.
  62                 </para>
  63             </listitem>
  64         </varlistentry>
  65         </variablelist>
  66     </refsect1>
  67     <refsect1 id="description"><title>Description</title>
  68         <para>
  69             <function>glGetFramebufferAttachmentParameteriv</function> returns information about attachments of a bound framebuffer
  70             object. <parameter>target</parameter> specifies the framebuffer binding point and must be <constant>GL_DRAW_FRAMEBUFFER</constant>,
  71             <constant>GL_READ_FRAMEBUFFER</constant> or <constant>GL_FRAMEBUFFER</constant>. <constant>GL_FRAMEBUFFER</constant> is equivalent
  72             to <constant>GL_DRAW_FRAMEBUFFER</constant>.
  73         </para>
  74         <para>
  75             If the default framebuffer is bound to <parameter>target</parameter> then <parameter>attachment</parameter> must be one of
  76             <constant>GL_FRONT_LEFT</constant>, <constant>GL_FRONT_RIGHT</constant>, <constant>GL_BACK_LEFT</constant>, or
  77             <constant>GL_BACK_RIGHT</constant>, identifying a color buffer, <constant>GL_DEPTH</constant>, identifying the depth buffer,
  78             or <constant>GL_STENCIL</constant>, identifying the stencil buffer.
  79         </para>
  80         <para>
  81             If a framebuffer object is bound, then <parameter>attachment</parameter> must be one of <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant>,
  82             <constant>GL_DEPTH_ATTACHMENT</constant>, <constant>GL_STENCIL_ATTACHMENT</constant>, or <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>.
  83             <emphasis>i</emphasis> in <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant> must be in the range zero to the value of
  84             <constant>GL_MAX_COLOR_ATTACHMENTS</constant> - 1.
  85         </para>
  86         <para>
  87             If <parameter>attachment</parameter> is <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant> and different objects are bound
  88             to the depth and stencil attachment points of <parameter>target</parameter> the query will fail. If the same object
  89             is bound to both attachment points, information about that object will be returned.
  90         </para>
  91         <para>
  92             Upon successful return from <function>glGetFramebufferAttachmentParameteriv</function>,  if <parameter>pname</parameter> is
  93             <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant>, then <parameter>params</parameter> will contain one of <constant>GL_NONE</constant>,
  94             <constant>GL_FRAMEBUFFER_DEFAULT</constant>, <constant>GL_TEXTURE</constant>, or <constant>GL_RENDERBUFFER</constant>, identifying the type of
  95             object which contains the attached image.  Other values accepted for <parameter>pname</parameter> depend on the type of object, as described below.
  96         </para>
  97         <para>
  98             If the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant> is <constant>GL_NONE</constant>, no framebuffer is bound to
  99             <parameter>target</parameter>. In this case querying <parameter>pname</parameter> <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant>
 100             will return zero, and all other queries will generate an error.
 101         </para>
 102         <para>
 103             If the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant> is not <constant>GL_NONE</constant>, these queries apply to all other
 104             framebuffer types:
 105         </para>
 106         <itemizedlist>
 107             <listitem>
 108                 <para>
 109                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE</constant>,
 110                     <constant>GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE</constant>, <constant>GL_FRAMEBUFFER_ATTACHMENT_BLUE_SIZE</constant>,
 111                     <constant>GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE</constant>, <constant>GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE</constant>,
 112                     or <constant>GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE</constant>, then <parameter>params</parameter> will contain the number
 113                     of bits in the corresponding red, green, blue, alpha, depth, or stencil component of the specified attachment. Zero is returned
 114                     if the requested component is not present in <parameter>attachment</parameter>.
 115                 </para>
 116             </listitem>
 117             <listitem>
 118                 <para>
 119                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE</constant>, <parameter>params</parameter> will
 120                     contain the format of components of the specified attachment, one of <constant>GL_FLOAT</constant>, <parameter>GL_INT</parameter>,
 121                     <parameter>GL_UNSIGNED_INT</parameter>, <parameter>GL_SIGNED_NORMALIZED</parameter>, or <parameter>GL_UNSIGNED_NORMALIZED</parameter>
 122                     for floating-point, signed integer, unsigned integer, signed normalized fixed-point, or unsigned normalized fixed-point components
 123                     respectively. Only color buffers may have  integer components.
 124                 </para>
 125             </listitem>
 126             <listitem>
 127                 <para>
 128                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant>, <parameter>param</parameter> will
 129                     contain the encoding of components of the specified attachment, one of <constant>GL_LINEAR</constant> or <constant>GL_SRGB</constant>
 130                     for linear or sRGB-encoded components, respectively. Only color buffer components may be sRGB-encoded;  such components
 131                     are treated as described in sections 4.1.7 and 4.1.8.  For the default framebuffer, color encoding is determined by the implementation.
 132                     For framebuffer objects, components are sRGB-encoded if the internal format of a color attachment is one of the color-renderable SRGB
 133                     formats.
 134                 </para>
 135             </listitem>
 136         </itemizedlist>
 137         <para>
 138             If the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant> is <constant>GL_RENDERBUFFER</constant>, then:
 139         </para>
 140         <itemizedlist>
 141             <listitem>
 142                 <para>
 143                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant>, <parameter>params</parameter> will contain
 144                     the name of the renderbuffer object which contains the attached image.
 145                 </para>
 146             </listitem>
 147         </itemizedlist>
 148         <para>
 149             If the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant> is <constant>GL_TEXTURE</constant>, then:
 150         </para>
 151         <itemizedlist>
 152             <listitem>
 153                 <para>
 154                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant>, then <parameter>params</parameter> will
 155                     contain the name of the texture object which contains the attached image.
 156                 </para>
 157             </listitem>
 158             <listitem>
 159                 <para>
 160                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL</constant>, then <parameter>params</parameter>
 161                     will contain the mipmap level of the texture object which contains the attached image.
 162                 </para>
 163             </listitem>
 164             <listitem>
 165                 <para>
 166                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE</constant> and the texture object named
 167                     <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant> is a cube map texture, then <parameter>params</parameter> will contain the cube map
 168                     face of the cubemap texture object which contains the attached image.  Otherwise <parameter>params</parameter> will contain the value
 169                     zero.
 170                 </para>
 171             </listitem>
 172             <listitem>
 173                 <para>
 174                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER</constant> and the texture object named
 175                     <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant> is a layer of a three-dimensional texture or a one-or two-dimensional
 176                     array texture, then <parameter>params</parameter> will contain the number of the texture layer which contains the attached image.
 177                     Otherwise <parameter>params</parameter> will contain the value zero.
 178                 </para>
 179             </listitem>
 180             <listitem>
 181                 <para>
 182                     If <parameter>pname</parameter> is <constant>GL_FRAMEBUFFER_ATTACHMENT_LAYERED</constant>, then <parameter>params</parameter> will
 183                     contain <constant>GL_TRUE</constant> if an entire level of a three-dimesional texture, cube map texture, or one-or two-dimensional
 184                     array texture is attached. Otherwise, <parameter>params</parameter> will contain <constant>GL_FALSE</constant>.
 185                 </para>
 186             </listitem>
 187         </itemizedlist>
 188         <para>
 189             Any combinations of framebuffer type and <parameter>pname</parameter> not described above will generate an error.
 190         </para>
 191     </refsect1>
 192     <refsect1 id="errors"><title>Errors</title>
 193         <para>
 194             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the accepted tokens.
 195         </para>
 196         <para>
 197             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not valid for the value of
 198             <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant>.
 199         </para>
 200         <para>
 201             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>attachment</parameter> is not the accepted values
 202             for <parameter>target</parameter>.
 203         </para>
 204         <para>
 205             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>attachment</parameter> is <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>
 206             and different objects are bound to the depth and stencil attachment points of <parameter>target</parameter>.
 207         </para>
 208         <para>
 209             <constant>GL_INVALID_OPERATION</constant> is generated if the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE</constant> is
 210             <constant>GL_NONE</constant> and <parameter>pname</parameter> is not <constant>GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME</constant>.
 211         </para>
 212     </refsect1>
 213     <refsect1 id="seealso"><title>See Also</title>
 214         <para>
 215             <citerefentry><refentrytitle>glGenFramebuffers</refentrytitle></citerefentry>,
 216             <citerefentry><refentrytitle>glBindFramebuffer</refentrytitle></citerefentry>
 217         </para>
 218     </refsect1>
 219     <refsect1 id="Copyright"><title>Copyright</title>
 220         <para>
 221             Copyright <trademark class="copyright"></trademark> 2010-2013 Khronos Group.
 222             This material may be distributed subject to the terms and conditions set forth in
 223             the Open Publication License, v 1.0, 8 June 1999.
 224             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 225         </para>
 226     </refsect1>
 227 </refentry>