upstream-man-pages/man4/glInvalidateSubFramebuffer.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="glInvalidateSubFramebuffer">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glInvalidateSubFramebuffer</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glInvalidateSubFramebuffer</refname>
  17         <refpurpose>invalidate the content of a region of 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>glInvalidateSubFramebuffer</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                 <paramdef>GLint <parameter>x</parameter></paramdef>
  27                 <paramdef>GLint <parameter>y</parameter></paramdef>
  28                 <paramdef>GLint <parameter>width</parameter></paramdef>
  29                 <paramdef>GLint <parameter>height</parameter></paramdef>
  30             </funcprototype>
  31         </funcsynopsis>
  32     </refsynopsisdiv>
  33     <refsect1 id="parameters"><title>Parameters</title>
  34         <variablelist>
  35         <varlistentry>
  36             <term><parameter>target</parameter></term>
  37             <listitem>
  38                 <para>
  39                     The target to which the framebuffer is attached. <parameter>target</parameter> must be
  40                     <constant>GL_FRAMEBUFFER</constant>, <constant>GL_DRAW_FRAMEBUFFER</constant>, or <constant>GL_READ_FRAMEBUFFER</constant>.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>numAttachments</parameter></term>
  46             <listitem>
  47                 <para>
  48                     The number of entries in the <parameter>attachments</parameter> array.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         <varlistentry>
  53             <term><parameter>attachments</parameter></term>
  54             <listitem>
  55                 <para>
  56                     The address of an array identifying the attachments to be invalidated.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>x</parameter></term>
  62             <listitem>
  63                 <para>
  64                     The X offset of the region to be invalidated.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         <varlistentry>
  69             <term><parameter>y</parameter></term>
  70             <listitem>
  71                 <para>
  72                     The Y offset of the region to be invalidated.
  73                 </para>
  74             </listitem>
  75         </varlistentry>
  76         <varlistentry>
  77             <term><parameter>width</parameter></term>
  78             <listitem>
  79                 <para>
  80                     The width of the region to be invalidated.
  81                 </para>
  82             </listitem>
  83         </varlistentry>
  84         <varlistentry>
  85             <term><parameter>height</parameter></term>
  86             <listitem>
  87                 <para>
  88                     The height of the region to be invalidated.
  89                 </para>
  90             </listitem>
  91         </varlistentry>
  92         </variablelist>
  93     </refsect1>
  94     <refsect1 id="description"><title>Description</title>
  95         <para>
  96             <function>glInvalidateSubFramebuffer</function> invalidates the content of a region
  97             of a specified set of attachments of a framebuffer. The framebuffer
  98             whose content to invalidate is indicated by setting <parameter>target</parameter>
  99             to the target to which it is bound. <parameter>target</parameter> may be
 100             <constant>GL_FRAMEBUFFER</constant>, <constant>GL_READ_FRAMEBUFFER</constant> or
 101             <constant>GL_DRAW_FRAMEBUFFER</constant>. <constant>GL_FRAMEBUFFER</constant>
 102             is treated as if it were <constant>GL_DRAW_FRAMEBUFFER</constant>.
 103         </para>
 104         <para>
 105             A region within a subset of the framebuffer's attachments may be invalidated.
 106             This set of attachments are specified in an array whose address is given
 107             by <parameter>attachments</parameter> and which contains <parameter>numAttachments</parameter>
 108             elements. The elements of <parameter>attachments</parameter> must be
 109             <constant>GL_DEPTH_ATTACHMENT</constant>, <constant>GL_STENCIL_ATTACHMENT</constant>
 110             <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>, or <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant>,
 111             where <emphasis>i</emphasis> is between zero and the value of <constant>GL_MAX_FRAMEBUFFER_ATTACHMENTS</constant> minus one.
 112             Furthermore, if the default framebuffer is bound to <parameter>target</parameter>, then
 113             <parameter>attachments</parameter> may contain <constant>GL_FRONT_LEFT</constant>,
 114             <constant>GL_FRONT_RIGHT</constant>, <constant>GL_BACK_LEFT</constant>, <constant>GL_BACK_RIGHT</constant>,
 115             <constant>GL_AUX<emphasis>i</emphasis></constant>, <constant>GL_ACCUM</constant>,
 116             <constant>GL_COLOR</constant>, <constant>GL_DEPTH</constant>, or <constant>GL_STENCIL</constant>, identifying that specific buffer.
 117             <constant>GL_COLOR</constant>, is treated as <constant>GL_BACK_LEFT</constant> for a double-buffered context and
 118             <constant>GL_FRONT_LEFT</constant> for a single-buffered context.
 119         </para>
 120         <para>
 121             The region of the framebuffer attachments to be invalidated is specified
 122             by <parameter>x</parameter>, <parameter>y</parameter>, <parameter>width</parameter> and <parameter>height</parameter>
 123             where <parameter>x</parameter> and <parameter>y</parameter> give the offset from the origin (with
 124             lower-left corner at (0, 0)) and <parameter>width</parameter> and <parameter>height</parameter>
 125             give the size. Any pixels lying outside of the window allocated
 126             to the current GL context, or outside of the attachments of the currently
 127             bound framebuffer object, are ignored.
 128             After <function>glInvalidateFramebuffer</function> is executed, the contents
 129             of the specified region of the specified attachments become undefined.
 130         </para>
 131     </refsect1>
 132     <refsect1 id="errors"><title>Errors</title>
 133         <para>
 134             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the
 135             accepted framebuffer target tokens.
 136         </para>
 137         <para>
 138             <constant>GL_INVALID_ENUM</constant> is generated if any element of <parameter>attachments</parameter> is
 139             not one of the accepted framebuffer attachment tokens.
 140         </para>
 141         <para>
 142             <constant>GL_INVALID_OPERATION</constant> is generated if element of <parameter>attachments</parameter> is
 143             <constant>GL_COLOR_ATTACHMENT<emphasis>i</emphasis></constant> where <emphasis>i</emphasis> is greater than or equal
 144             to the value of <constant>GL_MAX_COLOR_ATTACHMENTS</constant>.
 145         </para>
 146     </refsect1>
 147     <refsect1 id="associatedgets"><title>Associated Gets</title>
 148         <para>
 149             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_COLOR_ATTACHMENTS</constant>
 150         </para>
 151     </refsect1>
 152     <refsect1 id="seealso"><title>See Also</title>
 153         <para>
 154             <citerefentry><refentrytitle>glInvalidateTexSubImage</refentrytitle></citerefentry>,
 155             <citerefentry><refentrytitle>glInvalidateTexImage</refentrytitle></citerefentry>,
 156             <citerefentry><refentrytitle>glInvalidateBufferSubData</refentrytitle></citerefentry>,
 157             <citerefentry><refentrytitle>glInvalidateBufferData</refentrytitle></citerefentry>,
 158             <citerefentry><refentrytitle>glInvalidateFramebuffer</refentrytitle></citerefentry>.
 159         </para>
 160     </refsect1>
 161     <refsect1 id="Copyright"><title>Copyright</title>
 162         <para>
 163             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 164             This material may be distributed subject to the terms and conditions set forth in
 165             the Open Publication License, v 1.0, 8 June 1999.
 166             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 167         </para>
 168     </refsect1>
 169 </refentry>