upstream-man-pages/man2/xhtml/glClipPlane.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glClipPlane</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glClipPlane"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glClipPlane — specify a plane against which all geometry is clipped</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glClipPlane</b>(</code></td><td>GLenum  </td><td><var class="pdparam">plane</var>, </td></tr><tr><td> </td><td>const GLdouble *  </td><td><var class="pdparam">equation</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>plane</code></em></span></dt><dd><p>
   4                     Specifies which clipping plane is being positioned.
   5                     Symbolic names of the form <code class="constant">GL_CLIP_PLANE</code><span class="emphasis"><em>i</em></span>,
   6                     where <span class="emphasis"><em>i</em></span> is an integer between 0 and <code class="constant">GL_MAX_CLIP_PLANES</code>
   7                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
   8
   9                         <mml:mn>-1</mml:mn>
  10                     </mml:math>,
  11                     are accepted.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>equation</code></em></span></dt><dd><p>
  13                     Specifies the address of an array of four double-precision floating-point values.
  14                     These values are interpreted as a plane equation.
  15                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  16             Geometry is always clipped against the boundaries of a six-plane frustum
  17             in <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, and <span class="emphasis"><em>z</em></span>.
  18             <code class="function">glClipPlane</code> allows the specification of additional planes,
  19             not necessarily perpendicular to the <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, or <span class="emphasis"><em>z</em></span> axis,
  20             against which all geometry is clipped.
  21             To determine the maximum number of additional clipping planes, call
  22             <a class="citerefentry" href="glGetIntegerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetIntegerv</span></span></a> with argument <code class="constant">GL_MAX_CLIP_PLANES</code>. All
  23             implementations support at least six such clipping planes.
  24             Because the resulting clipping region is the intersection
  25             of the defined half-spaces,
  26             it is always convex.
  27         </p><p>
  28             <code class="function">glClipPlane</code> specifies a half-space using a four-component plane equation.
  29             When <code class="function">glClipPlane</code> is called,
  30             <em class="parameter"><code>equation</code></em> is transformed by the inverse of the modelview matrix
  31             and stored in the resulting eye coordinates.
  32             Subsequent changes to the modelview matrix have no effect on the
  33             stored plane-equation components.
  34             If the dot product of the eye coordinates of a vertex with the
  35             stored plane equation components is positive or zero,
  36             the vertex is <span class="emphasis"><em>in</em></span> with respect to that clipping plane.
  37             Otherwise, it is <span class="emphasis"><em>out</em></span>.
  38         </p><p>
  39             To enable and disable clipping planes, call
  40             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a> with the argument
  41             <code class="constant">GL_CLIP_PLANE</code><span class="emphasis"><em>i</em></span>,
  42             where <span class="emphasis"><em>i</em></span> is the plane number.
  43         </p><p>
  44             All clipping planes are initially defined as (0, 0, 0, 0) in eye coordinates
  45             and are
  46             disabled.
  47         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  48             It is always the case that <code class="constant">GL_CLIP_PLANE</code>
  49             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
  50             = <code class="constant">GL_CLIP_PLANE0</code> +
  51             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>.
  52         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  53             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>plane</code></em> is not an accepted value.
  54         </p><p>
  55             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glClipPlane</code>
  56             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
  57             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
  58         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
  59             <a class="citerefentry" href="glGetClipPlane.xml"><span class="citerefentry"><span class="refentrytitle">glGetClipPlane</span></span></a>
  60         </p><p>
  61             <a class="citerefentry" href="glIsEnabled.xml"><span class="citerefentry"><span class="refentrytitle">glIsEnabled</span></span></a> with argument <code class="constant">GL_CLIP_PLANE</code><span class="emphasis"><em>i</em></span>
  62         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
  63             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>
  64         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
  65             Copyright <span class="trademark"></span>© 1991-2006
  66             Silicon Graphics, Inc. This document is licensed under the SGI
  67             Free Software B License. For details, see
  68             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
  69         </p></div></div></body></html>