upstream-man-pages/man2/glScissor.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="glScissor">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glScissor</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glScissor</refname>
  17         <refpurpose>define the scissor box</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glScissor</function></funcdef>
  23                 <paramdef>GLint <parameter>x</parameter></paramdef>
  24                 <paramdef>GLint <parameter>y</parameter></paramdef>
  25                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>x</parameter></term>
  34             <term><parameter>y</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specify the lower left corner of the scissor box.
  38                     Initially (0, 0).
  39                 </para>
  40             </listitem>
  41         </varlistentry>
  42         <varlistentry>
  43             <term><parameter>width</parameter></term>
  44             <term><parameter>height</parameter></term>
  45             <listitem>
  46                 <para>
  47                     Specify the width and height of the scissor box.
  48                     When a GL context is first attached to a window,
  49                     <parameter>width</parameter> and <parameter>height</parameter> are set to the dimensions of that
  50                     window.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         </variablelist>
  55     </refsect1>
  56     <refsect1 id="description"><title>Description</title>
  57         <para>
  58             <function>glScissor</function> defines a rectangle, called the scissor box,
  59             in window coordinates.
  60             The first two arguments,
  61             <parameter>x</parameter> and <parameter>y</parameter>,
  62             specify the lower left corner of the box.
  63             <parameter>width</parameter> and <parameter>height</parameter> specify the width and height of the box.
  64         </para>
  65         <para>
  66             To enable and disable the scissor test, call
  67             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
  68             <constant>GL_SCISSOR_TEST</constant>. The test is initially disabled.
  69             While the test is enabled, only pixels that lie within the scissor box
  70             can be modified by drawing commands.
  71             Window coordinates have integer values at the shared corners of
  72             frame buffer pixels.
  73             <code>glScissor(0,0,1,1)</code> allows modification of only the lower left
  74             pixel in the window, and <code>glScissor(0,0,0,0)</code> doesn't allow
  75             modification of any pixels in the window.
  76         </para>
  77         <para>
  78             When the scissor test is disabled,
  79             it is as though the scissor box includes the entire window.
  80         </para>
  81     </refsect1>
  82     <refsect1 id="errors"><title>Errors</title>
  83         <para>
  84             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
  85         </para>
  86         <para>
  87             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glScissor</function>
  88             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
  89             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
  90         </para>
  91     </refsect1>
  92     <refsect1 id="associatedgets"><title>Associated Gets</title>
  93         <para>
  94             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_SCISSOR_BOX</constant>
  95         </para>
  96         <para>
  97             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_SCISSOR_TEST</constant>
  98         </para>
  99     </refsect1>
 100     <refsect1 id="seealso"><title>See Also</title>
 101         <para>
 102             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 103             <citerefentry><refentrytitle>glViewport</refentrytitle></citerefentry>
 104         </para>
 105     </refsect1>
 106     <refsect1 id="Copyright"><title>Copyright</title>
 107         <para>
 108             Copyright <trademark class="copyright"></trademark> 1991-2006
 109             Silicon Graphics, Inc. This document is licensed under the SGI
 110             Free Software B License. For details, see
 111             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 112         </para>
 113     </refsect1>
 114 </refentry>