Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?>\r |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"\r | |
3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">\r | |
4 | <refentry id="gl_ClipDistance">\r | |
5 | <refmeta>\r | |
6 | <refmetainfo>\r | |
7 | <copyright>\r | |
8 | <year>2011</year>\r | |
9 | <holder>Khronos Group</holder>\r | |
10 | </copyright>\r | |
11 | </refmetainfo>\r | |
12 | <refentrytitle>gl_ClipDistance</refentrytitle>\r | |
13 | <manvolnum>3G</manvolnum>\r | |
14 | </refmeta>\r | |
15 | <refnamediv>\r | |
16 | <refname>gl_ClipDistance</refname>\r | |
17 | <refpurpose>provides a forward-compatible mechanism for vertex clipping</refpurpose>\r | |
18 | </refnamediv>\r | |
19 | <refsynopsisdiv><title>Declaration</title>\r | |
20 | <para>\r | |
21 | <function>gl_ClipDistance</function> is a member of the <function>gl_PerVertex</function>\r | |
22 | named block:\r | |
23 | </para>\r | |
24 | <funcsynopsis>\r | |
25 | <programlisting><![CDATA[ out gl_PerVertex {\r | |
26 | vec4 gl_Position;\r | |
27 | float gl_PointSize;\r | |
28 | float gl_ClipDistance[];\r | |
29 | };]]></programlisting>\r | |
30 | </funcsynopsis>\r | |
31 | <para>\r | |
32 | In the fragment language, it is intrinsically declared as:\r | |
33 | </para>\r | |
34 | <funcsynopsis>\r | |
35 | <function>in float gl_ClipDistance[];</function>\r | |
36 | </funcsynopsis>\r | |
37 | </refsynopsisdiv>\r | |
38 | <refsect1 id="description"><title>Description</title>\r | |
39 | <para>\r | |
40 | The <function>gl_ClipDistance</function> variable provides a forward compatible\r | |
41 | mechanism for controlling user clipping. The element <function>gl_ClipDistance[<emphasis>i</emphasis>]</function>\r | |
42 | specifies a clip distance for each user clip plane <emphasis>i</emphasis>. A distance of 0.0 means that\r | |
43 | the vertex is on the plane, a positive distance means that the vertex is insider the clip plane, and a negative\r | |
44 | distance means that the point is outside the clip plane. The clip distances will be linearly interpolated across\r | |
45 | the primitive and the portion of the primitive with interpolated distances less than 0.0 will be clipped.\r | |
46 | </para>\r | |
47 | <para>\r | |
48 | The <function>gl_ClipDistance</function> array is initially predeclared as unsized and must be\r | |
49 | sized by the shader either by redeclaring it with an explicit size, or by indexing it\r | |
50 | with only integral constant expressions. The array must be sized to include all\r | |
51 | clip planes that are enabled via the OpenGL API; if the size does not include all enabled planes,\r | |
52 | results are undefined. The size may be at most <function>gl_MaxClipDistances</function>. The number\r | |
53 | of variing components consumed by <function>gl_ClipDistance</function> will match the size of the\r | |
54 | array, no matter how many planes are enabled. The shader must also set all values in <function>gl_ClipDistance</function>\r | |
55 | that have been enabled via the OpenGL API, or results are undefined. Values written into\r | |
56 | <function>gl_ClipDistance</function> planes that are not enabled have no effect.\r | |
57 | </para>\r | |
58 | <para>\r | |
59 | In the vertex, tessellation evaluation and geoemtry languages, a single\r | |
60 | global instance of the <function>gl_PerVertex</function> named block is available and\r | |
61 | its <function>gl_ClipDistance</function> member is an output that receives the\r | |
62 | clip distances for the current vertex. It may be written at any time during shader execution.\r | |
63 | The value written to <function>gl_ClipDistance</function> will be used by primitive assembly,\r | |
64 | clipping, culling and other fixed functionality operations, if present, that operate on\r | |
65 | primitives after vertex processing has occurred.\r | |
66 | </para>\r | |
67 | <para>\r | |
68 | In the tessellation control language, the <function>gl_PerVertex</function> named block\r | |
69 | is used to construct an array, <function>gl_out[]</function>, whose <function>gl_ClipDistance</function>\r | |
70 | members hold clip distances for each of the control points, which become available as inputs to the subsequent\r | |
71 | tessellation evaluation shader.\r | |
72 | </para>\r | |
73 | <para>\r | |
74 | The value of <function>gl_ClipDistance</function> (or the <function>gl_ClipDistance</function> member of the <function>gl_out[]</function>\r | |
75 | array, in the case of the tessellation control shader)\r | |
76 | is undefined after the vertex, tessellation control, and tessellation evaluation\r | |
77 | shading stages if the corresponding shader executable does\r | |
78 | not write to gl_ClipDistance. It is also undefined after the geometry processing stage if the geometry shader executable calls\r | |
79 | <citerefentry><refentrytitle>EmitVertex</refentrytitle></citerefentry> without having\r | |
80 | written <function>gl_ClipDistance</function> since the last call to <citerefentry><refentrytitle>EmitVertex</refentrytitle></citerefentry>\r | |
81 | (or hasn't written it at all).\r | |
82 | </para>\r | |
83 | <para>\r | |
84 | In the tessellation control, tessellation evaluation and geoemetry languages,\r | |
85 | the <function>gl_PerVertex</function> named block is used to construct an array, <function>gl_in[]</function>\r | |
86 | of per-vertex or per-control point inputs whose content represents the corresponding\r | |
87 | outputs written by the previous stage. Only elements of the <function>gl_ClipDistance</function>\r | |
88 | array that correspond to enabled clip planes have defined values.\r | |
89 | </para>\r | |
90 | </refsect1>\r | |
91 | <refsect1 id="versions"><title>Version Support</title>\r | |
92 | <informaltable frame="topbot">\r | |
93 | #VARTABLECOLS#\r | |
94 | <thead>\r | |
95 | #VARTABLEHEADER#\r | |
96 | <row>\r | |
97 | <entry>gl_ClipDistance</entry>#newin13#\r | |
98 | </row>\r | |
99 | </thead>\r | |
100 | </tgroup>\r | |
101 | </informaltable>\r | |
102 | <para>Versions 1.30 to 1.40 - vertex shader only.</para>\r | |
103 | <para>Versions 1.50 to 3.30 - vertex and geometry shaders only.</para>\r | |
104 | </refsect1>\r | |
105 | <refsect1 id="seealso"><title>See Also</title>\r | |
106 | <para>\r | |
107 | <citerefentry><refentrytitle>gl_PointSize</refentrytitle></citerefentry>\r | |
108 | </para>\r | |
109 | </refsect1>\r | |
110 | <refsect1 id="Copyright"><title>Copyright</title>\r | |
111 | <para>\r | |
112 | Copyright <trademark class="copyright"></trademark> 2011 Khronos Group. \r | |
113 | This material may be distributed subject to the terms and conditions set forth in \r | |
114 | the Open Publication License, v 1.0, 8 June 1999.\r | |
115 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.\r | |
116 | </para>\r | |
117 | </refsect1>\r | |
118 | </refentry>\r |