upstream-man-pages/man2/glPushClientAttrib.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="glPushClientAttrib">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glPushClientAttrib</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glPushClientAttrib</refname>
  17         <refpurpose>push and pop the client attribute stack</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glPushClientAttrib</function></funcdef>
  23                 <paramdef>GLbitfield <parameter>mask</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29         <varlistentry>
  30             <term><parameter>mask</parameter></term>
  31             <listitem>
  32                 <para>
  33                     Specifies a mask that indicates which attributes to save.  Values for
  34                     <parameter>mask</parameter> are listed below.
  35                 </para>
  36             </listitem>
  37         </varlistentry>
  38         </variablelist>
  39     </refsect1>
  40     <refsynopsisdiv><title>C Specification</title>
  41         <funcsynopsis>
  42             <funcprototype>
  43                 <funcdef>void <function>glPopClientAttrib</function></funcdef>
  44                 <paramdef> <parameter>void</parameter></paramdef>
  45             </funcprototype>
  46         </funcsynopsis>
  47     </refsynopsisdiv>
  48     <refsect1 id="description"><title>Description</title>
  49         <para>
  50             <function>glPushClientAttrib</function> takes one argument,
  51             a mask that indicates which groups of client-state variables
  52             to save on the client attribute stack.
  53             Symbolic constants are used to set bits in the mask.
  54             <parameter>mask</parameter>
  55             is typically constructed by specifying the bitwise-or of several
  56             of these constants together.
  57             The special mask
  58             <constant>GL_CLIENT_ALL_ATTRIB_BITS</constant>
  59             can be used to save all stackable client state.
  60         </para>
  61         <para>
  62             The symbolic mask constants and their associated GL client state are as follows
  63             (the second column lists which attributes are saved):
  64         </para>
  65         <para>
  66             <constant>GL_CLIENT_PIXEL_STORE_BIT</constant>      Pixel storage modes
  67             <constant>GL_CLIENT_VERTEX_ARRAY_BIT</constant>     Vertex arrays (and enables)
  68         </para>
  69         <para>
  70             <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry> restores the values of the client-state variables
  71             saved with the last <function>glPushClientAttrib</function>.
  72             Those not saved are left unchanged.
  73         </para>
  74         <para>
  75             It is an error to push attributes onto a full client attribute stack
  76             or to pop attributes off an empty stack.
  77             In either case, the error flag is set,
  78             and no other change is made to GL state.
  79         </para>
  80         <para>
  81             Initially, the client attribute stack is empty.
  82         </para>
  83     </refsect1>
  84     <refsect1 id="notes"><title>Notes</title>
  85         <para>
  86             <function>glPushClientAttrib</function> is available only if the GL version is 1.1 or greater.
  87         </para>
  88         <para>
  89             Not all values for GL client state can be saved on the attribute stack.
  90             For example, select and feedback state cannot be saved.
  91         </para>
  92         <para>
  93             The depth of the attribute stack depends on the implementation,
  94             but it must be at least 16.
  95         </para>
  96         <para>
  97             Use <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry> to push and restore
  98             state that is kept on the server. Only pixel storage modes and
  99             vertex array state may be pushed and popped with
 100             <function>glPushClientAttrib</function> and <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>.
 101         </para>
 102         <para>
 103             For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, pushing and
 104             popping client vertex array state applies to all supported texture units,
 105             and the active client texture state.
 106         </para>
 107     </refsect1>
 108     <refsect1 id="errors"><title>Errors</title>
 109         <para>
 110             <constant>GL_STACK_OVERFLOW</constant> is generated if <function>glPushClientAttrib</function> is called while
 111             the attribute stack is full.
 112         </para>
 113         <para>
 114             <constant>GL_STACK_UNDERFLOW</constant> is generated if <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry> is called while
 115             the attribute stack is empty.
 116         </para>
 117     </refsect1>
 118     <refsect1 id="associatedgets"><title>Associated Gets</title>
 119         <para>
 120             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ATTRIB_STACK_DEPTH</constant>
 121         </para>
 122         <para>
 123             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_CLIENT_ATTRIB_STACK_DEPTH</constant>
 124         </para>
 125     </refsect1>
 126     <refsect1 id="seealso"><title>See Also</title>
 127         <para>
 128             <citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
 129             <citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
 130             <citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
 131             <citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
 132             <citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
 133             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
 134             <citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>,
 135             <citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
 136             <citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
 137             <citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>,
 138             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 139             <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
 140             <citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
 141             <citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
 142         </para>
 143     </refsect1>
 144     <refsect1 id="Copyright"><title>Copyright</title>
 145         <para>
 146             Copyright <trademark class="copyright"></trademark> 1991-2006
 147             Silicon Graphics, Inc. This document is licensed under the SGI
 148             Free Software B License. For details, see
 149             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 150         </para>
 151     </refsect1>
 152 </refentry>