404 lines
21 KiB
XML
404 lines
21 KiB
XML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
||
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
||
|
|
<refentry id="glPointSize">
|
||
|
|
<refmeta>
|
||
|
|
<refmetainfo>
|
||
|
|
<copyright>
|
||
|
|
<year>1991-2006</year>
|
||
|
|
<holder>Silicon Graphics, Inc.</holder>
|
||
|
|
</copyright>
|
||
|
|
</refmetainfo>
|
||
|
|
<refentrytitle>glPointSize</refentrytitle>
|
||
|
|
<manvolnum>3G</manvolnum>
|
||
|
|
</refmeta>
|
||
|
|
<refnamediv>
|
||
|
|
<refname>glPointSize</refname>
|
||
|
|
<refpurpose>specify the diameter of rasterized points</refpurpose>
|
||
|
|
</refnamediv>
|
||
|
|
<refsynopsisdiv><title>C Specification</title>
|
||
|
|
<funcsynopsis>
|
||
|
|
<funcprototype>
|
||
|
|
<funcdef>void <function>glPointSize</function></funcdef>
|
||
|
|
<paramdef>GLfloat <parameter>size</parameter></paramdef>
|
||
|
|
</funcprototype>
|
||
|
|
</funcsynopsis>
|
||
|
|
</refsynopsisdiv>
|
||
|
|
<!-- eqn: ignoring delim $$ -->
|
||
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><parameter>size</parameter></term>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
Specifies the diameter of rasterized points.
|
||
|
|
The initial value is 1.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="description"><title>Description</title>
|
||
|
|
<para>
|
||
|
|
<function>glPointSize</function> specifies the rasterized diameter of both aliased and antialiased
|
||
|
|
points. Using a point size other than 1 has different effects, depending
|
||
|
|
on whether point antialiasing is enabled. To enable and disable point
|
||
|
|
antialiasing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
|
||
|
|
<constant>GL_POINT_SMOOTH</constant>. Point antialiasing is initially disabled.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The specified point size is multiplied with a distance attenuation factor
|
||
|
|
and clamped to the specified point size range, and further clamped to the
|
||
|
|
implementation-dependent point size range to produce the derived point size
|
||
|
|
using
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<informalequation><mml:math>
|
||
|
|
<!-- eqn: pointSize = clamp left ( size * sqrt { left ( 1 over {a + b * d + c * {d sup 2}} right ) } right ):-->
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">pointSize</mml:mi>
|
||
|
|
<mml:mo>=</mml:mo>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">clamp</mml:mi>
|
||
|
|
<mml:mo>⁢</mml:mo>
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">size</mml:mi>
|
||
|
|
<mml:mo>×</mml:mo>
|
||
|
|
<mml:msqrt>
|
||
|
|
<mml:mfenced open="" close="">
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:mfrac>
|
||
|
|
<mml:mn>1</mml:mn>
|
||
|
|
<mml:mfenced open="" close="">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">a</mml:mi>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">b</mml:mi>
|
||
|
|
<mml:mo>×</mml:mo>
|
||
|
|
<mml:mi mathvariant="italic">d</mml:mi>
|
||
|
|
</mml:mrow>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">c</mml:mi>
|
||
|
|
<mml:mo>×</mml:mo>
|
||
|
|
<mml:mfenced open="" close="">
|
||
|
|
<mml:msup><mml:mi mathvariant="italic">d</mml:mi>
|
||
|
|
<mml:mn>2</mml:mn>
|
||
|
|
</mml:msup>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mfrac>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:msqrt>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:math></informalequation>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
where
|
||
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
|
||
|
|
is the eye-coordinate distance from the eye to the vertex, and
|
||
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">a</mml:mi></mml:math></inlineequation>,
|
||
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>,
|
||
|
|
and
|
||
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
|
||
|
|
are the distance attenuation coefficients (see
|
||
|
|
<citerefentry><refentrytitle>glPointParameter</refentrytitle></citerefentry>).
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If multisampling is disabled, the computed point size is used as the
|
||
|
|
point's width.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If multisampling is enabled, the point may be faded by modifying the point
|
||
|
|
alpha value (see <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>) instead of allowing the point width
|
||
|
|
to go below a given threshold (see <citerefentry><refentrytitle>glPointParameter</refentrytitle></citerefentry>). In this case,
|
||
|
|
the width is further modified in the following manner:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<informalequation><mml:math>
|
||
|
|
<!-- eqn: pointWidth = left { lpile { pointSize above threshold } lpile { pointSize >= threshold above otherwise }:-->
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">pointWidth</mml:mi>
|
||
|
|
<mml:mo>=</mml:mo>
|
||
|
|
<mml:mfenced open="{" close="">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mtable>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mi mathvariant="italic">pointSize</mml:mi>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mi mathvariant="italic">threshold</mml:mi>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
</mml:mtable>
|
||
|
|
<mml:mo>⁢</mml:mo>
|
||
|
|
<mml:mtable>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">pointSize</mml:mi>
|
||
|
|
<mml:mo>>=</mml:mo>
|
||
|
|
<mml:mi mathvariant="italic">threshold</mml:mi>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mi mathvariant="italic">otherwise</mml:mi>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
</mml:mtable>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:math></informalequation>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The point alpha value is modified by computing:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<informalequation><mml:math>
|
||
|
|
<!-- eqn: pointAlpha = left { lpile { 1 above left ( pointSize over threshold right ) sup 2 } lpile { pointSize >= threshold above otherwise }:-->
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">pointAlpha</mml:mi>
|
||
|
|
<mml:mo>=</mml:mo>
|
||
|
|
<mml:mfenced open="{" close="">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mtable>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mn>1</mml:mn>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:msup><mml:mfenced open="(" close=")">
|
||
|
|
<mml:mfrac>
|
||
|
|
<mml:mi mathvariant="italic">pointSize</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">threshold</mml:mi>
|
||
|
|
</mml:mfrac>
|
||
|
|
</mml:mfenced>
|
||
|
|
<mml:mn>2</mml:mn>
|
||
|
|
</mml:msup>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
</mml:mtable>
|
||
|
|
<mml:mo>⁢</mml:mo>
|
||
|
|
<mml:mtable>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mi mathvariant="italic">pointSize</mml:mi>
|
||
|
|
<mml:mo>>=</mml:mo>
|
||
|
|
<mml:mi mathvariant="italic">threshold</mml:mi>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
<mml:mtr><mml:mtd>
|
||
|
|
<mml:mi mathvariant="italic">otherwise</mml:mi>
|
||
|
|
</mml:mtd></mml:mtr>
|
||
|
|
</mml:mtable>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:math></informalequation>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If point antialiasing is disabled, the actual size is determined by
|
||
|
|
rounding the supplied size to the nearest integer. (If the rounding
|
||
|
|
results in the value 0, it is as if the point size were 1.) If the rounded
|
||
|
|
size is odd, then the center point
|
||
|
|
(<inlineequation><mml:math>
|
||
|
|
<!-- eqn: x:-->
|
||
|
|
<mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
</mml:math></inlineequation>,
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: y:-->
|
||
|
|
<mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
</mml:math></inlineequation>)
|
||
|
|
of the pixel fragment
|
||
|
|
that represents the point is computed as
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: ( \(lf x sub w \(rf + .5 , \(lf y sub w \(rf + .5 ):-->
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mfenced open="⌊" close="⌋">
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
</mml:mfenced>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mn>.5</mml:mn>
|
||
|
|
</mml:mrow>
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:mfenced open="⌊" close="⌋">
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
</mml:mfenced>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mn>.5</mml:mn>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:math></inlineequation>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
where
|
||
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
|
||
|
|
subscripts indicate window coordinates. All pixels that lie
|
||
|
|
within the square grid of the rounded size centered at
|
||
|
|
(<inlineequation><mml:math>
|
||
|
|
<!-- eqn: x:-->
|
||
|
|
<mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
</mml:math></inlineequation>,
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: y:-->
|
||
|
|
<mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
</mml:math></inlineequation>)
|
||
|
|
make
|
||
|
|
up the fragment. If the size is even, the center point is
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: ( \(lf x sub w + .5 \(rf , \(lf y sub w + .5 \(rf ):-->
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:mfenced open="⌊" close="⌋">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mn>.5</mml:mn>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
<mml:mfenced open="⌊" close="⌋">
|
||
|
|
<mml:mrow>
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
<mml:mo>+</mml:mo>
|
||
|
|
<mml:mn>.5</mml:mn>
|
||
|
|
</mml:mrow>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:math></inlineequation>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
and the rasterized fragment's centers are the half-integer window
|
||
|
|
coordinates within the square of the rounded size centered at
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: (x, y):-->
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:math></inlineequation>.
|
||
|
|
All pixel fragments produced in rasterizing a nonantialiased point are
|
||
|
|
assigned the same associated data, that of the vertex corresponding to the
|
||
|
|
point.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If antialiasing is enabled, then point rasterization produces a fragment
|
||
|
|
for each pixel square that intersects the region lying within the circle
|
||
|
|
having diameter equal to the current point size and centered at the point's
|
||
|
|
<inlineequation><mml:math>
|
||
|
|
<!-- eqn: (x sub w, y sub w):-->
|
||
|
|
<mml:mfenced open="(" close=")">
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">x</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
<mml:msub><mml:mi mathvariant="italic">y</mml:mi>
|
||
|
|
<mml:mi mathvariant="italic">w</mml:mi>
|
||
|
|
</mml:msub>
|
||
|
|
</mml:mfenced>
|
||
|
|
</mml:math></inlineequation>.
|
||
|
|
The coverage value for each fragment is the
|
||
|
|
window coordinate area of the intersection of the circular region with the
|
||
|
|
corresponding pixel square. This value is saved and used in the final
|
||
|
|
rasterization step. The data associated with each fragment is the data
|
||
|
|
associated with the point being rasterized.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Not all sizes are supported when point antialiasing is enabled. If an
|
||
|
|
unsupported size is requested, the nearest supported size is used. Only
|
||
|
|
size 1 is guaranteed to be supported; others depend on the implementation.
|
||
|
|
To query the range of supported sizes and the size difference between
|
||
|
|
supported sizes within the range, call <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with arguments
|
||
|
|
<constant>GL_SMOOTH_POINT_SIZE_RANGE</constant> and <constant>GL_SMOOTH_POINT_SIZE_GRANULARITY</constant>.
|
||
|
|
For aliased points, query the supported ranges and granularity with
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with arguments <constant>GL_ALIASED_POINT_SIZE_RANGE</constant>.
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="notes"><title>Notes</title>
|
||
|
|
<para>
|
||
|
|
The point size specified by <function>glPointSize</function> is always returned when
|
||
|
|
<constant>GL_POINT_SIZE</constant> is queried. Clamping and rounding for aliased and
|
||
|
|
antialiased points have no effect on the specified value.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
A non-antialiased point size may be clamped to an implementation-dependent
|
||
|
|
maximum. Although this maximum cannot be queried, it must be no less than
|
||
|
|
the maximum value for antialiased points, rounded to the nearest integer
|
||
|
|
value.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<constant>GL_POINT_SIZE_RANGE</constant> and <constant>GL_POINT_SIZE_GRANULARITY</constant> are
|
||
|
|
deprecated in GL versions 1.2 and greater. Their functionality has been
|
||
|
|
replaced by <constant>GL_SMOOTH_POINT_SIZE_RANGE</constant> and
|
||
|
|
<constant>GL_SMOOTH_POINT_SIZE_GRANULARITY</constant>.
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="errors"><title>Errors</title>
|
||
|
|
<para>
|
||
|
|
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is less than or equal to 0.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glPointSize</function>
|
||
|
|
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
|
||
|
|
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="associatedgets"><title>Associated Gets</title>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ALIASED_POINT_SIZE_RANGE</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POINT_SIZE</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POINT_SIZE_MIN</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POINT_SIZE_MAX</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POINT_FADE_THRESHOLD_SIZE</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POINT_DISTANCE_ATTENUATION</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_SMOOTH_POINT_SIZE_RANGE</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_SMOOTH_POINT_SIZE_GRANULARITY</constant>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_POINT_SMOOTH</constant>
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="seealso"><title>See Also</title>
|
||
|
|
<para>
|
||
|
|
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
|
||
|
|
<citerefentry><refentrytitle>glPointParameter</refentrytitle></citerefentry>
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
||
|
|
<para>
|
||
|
|
Copyright <trademark class="copyright"></trademark> 1991-2006
|
||
|
|
Silicon Graphics, Inc. This document is licensed under the SGI
|
||
|
|
Free Software B License. For details, see
|
||
|
|
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
</refentry>
|