upstream-man-pages/man4/glInvalidateFramebuffer.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="glInvalidateFramebuffer">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glInvalidateFramebuffer</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glInvalidateFramebuffer</refname>
  17         <refpurpose>invalidate the content some or all of a framebuffer object's attachments</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glInvalidateFramebuffer</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLsizei <parameter>numAttachments</parameter></paramdef>
  25                 <paramdef>const GLenum * <parameter>attachments</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>target</parameter></term>
  33             <listitem>
  34                 <para>
  35                     The target to which the framebuffer is attached. <parameter>target</parameter> must be
  36                     <constant>GL_FRAMEBUFFER</constant>, <constant>GL_DRAW_FRAMEBUFFER</constant>, or <constant>GL_READ_FRAMEBUFFER</constant>.
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>numAttachments</parameter></term>
  42             <listitem>
  43                 <para>
  44                     The number of entries in the <parameter>attachments</parameter> array.
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>attachments</parameter></term>
  50             <listitem>
  51                 <para>
  52                     The address of an array identifying the attachments to be invalidated.
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         </variablelist>
  57     </refsect1>
  58     <refsect1 id="description"><title>Description</title>
  59         <para>
  60             <function>glInvalidateFramebuffer</function> invalidates the content
  61             of a specified set of attachments of a framebuffer. The framebuffer
  62             whose content to invalidate is indicated by setting <parameter>target</parameter>
  63             to the target to which it is bound. <parameter>target</parameter> may be
  64             <constant>GL_FRAMEBUFFER</constant>, <constant>GL_READ_FRAMEBUFFER</constant> or
  65             <constant>GL_DRAW_FRAMEBUFFER</constant>. <constant>GL_FRAMEBUFFER</constant>
  66             is treated as if it were <constant>GL_DRAW_FRAMEBUFFER</constant>.
  67         </para>
  68         <para>
  69             The set of attachments whose content to invalidate are specified in an array whose address is given
  70             by <parameter>attachments</parameter> and which contains <parameter>numAttachments</parameter>
  71             elements. The elements of <parameter>attachments</parameter> must be
  72             <constant>GL_DEPTH_ATTACHMENT</constant>, <constant>GL_STENCIL_ATTACHMENT</constant>
  73             <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>, or <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant>,
  74             where <emphasis>i</emphasis> is between zero and the value of <constant>GL_MAX_FRAMEBUFFER_ATTACHMENTS</constant> minus one.
  75             Furthermore, if the default framebuffer is bound to <parameter>target</parameter>, then
  76             <parameter>attachments</parameter> may contain <constant>GL_FRONT_LEFT</constant>,
  77             <constant>GL_FRONT_RIGHT</constant>, <constant>GL_BACK_LEFT</constant>, <constant>GL_BACK_RIGHT</constant>,
  78             <constant>GL_AUX<emphasis>i</emphasis></constant>, <constant>GL_ACCUM</constant>,
  79             <constant>GL_COLOR</constant>, <constant>GL_DEPTH</constant>, or <constant>GL_STENCIL</constant>, identifying that specific buffer.
  80             <constant>GL_COLOR</constant>, is treated as <constant>GL_BACK_LEFT</constant> for a double-buffered context and
  81             <constant>GL_FRONT_LEFT</constant> for a single-buffered context.
  82             After <function>glInvalidateFramebuffer</function> is executed, the contents
  83             of the specified attachments become undefined.
  84         </para>
  85     </refsect1>
  86     <refsect1 id="errors"><title>Errors</title>
  87         <para>
  88             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the
  89             accepted framebuffer target tokens.
  90         </para>
  91         <para>
  92             <constant>GL_INVALID_ENUM</constant> is generated if any element of <parameter>attachments</parameter> is
  93             not one of the accepted framebuffer attachment tokens.
  94         </para>
  95         <para>
  96             <constant>GL_INVALID_OPERATION</constant> is generated if element of <parameter>attachments</parameter> is
  97             <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant> where <emphasis>i</emphasis> is greater than or equal
  98             to the value of <constant>GL_MAX_COLOR_ATTACHMENTS</constant>.
  99         </para>
 100     </refsect1>
 101     <refsect1 id="associatedgets"><title>Associated Gets</title>
 102         <para>
 103             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_COLOR_ATTACHMENTS</constant>
 104         </para>
 105     </refsect1>
 106     <refsect1 id="seealso"><title>See Also</title>
 107         <para>
 108             <citerefentry><refentrytitle>glInvalidateTexSubImage</refentrytitle></citerefentry>,
 109             <citerefentry><refentrytitle>glInvalidateTexImage</refentrytitle></citerefentry>,
 110             <citerefentry><refentrytitle>glInvalidateBufferSubData</refentrytitle></citerefentry>,
 111             <citerefentry><refentrytitle>glInvalidateBufferData</refentrytitle></citerefentry>,
 112             <citerefentry><refentrytitle>glInvalidateSubFramebuffer</refentrytitle></citerefentry>.
 113         </para>
 114     </refsect1>
 115     <refsect1 id="Copyright"><title>Copyright</title>
 116         <para>
 117             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 118             This material may be distributed subject to the terms and conditions set forth in
 119             the Open Publication License, v 1.0, 8 June 1999.
 120             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 121         </para>
 122     </refsect1>
 123 </refentry>