Return to glPointSize.xml CVS log

Up to [Development] / projects / ogl-sample / main / doc / gles / xml

OpenGL ES 1.0 and EGL 1.0 reference manual and man pages (written by
Claude Knaus, based on OpenGL SI man pages).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook MathML Module V1.0//EN" "DTD/dbmathml.dtd">

<!--
  License Applicability. Except to the extent portions of this file are
  made subject to an alternative license as permitted in the SGI Free
  Software License B, Version 1.1 (the "License"), the contents of this
  file are subject only to the provisions of the License. You may not use
  this file except in compliance with the License. You may obtain a copy
  of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
  Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:

  http://oss.sgi.com/projects/FreeB

  Note that, as provided in the License, the Software is distributed on an
  "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
  DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
  CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
  PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

  Original Code. The Original Code is: OpenGL ES Reference Manual,
  Version 1.0, released September 2003, developed by Silicon Graphics,
  Inc.  The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
  Copyright in any portions created by third parties is as indicated
  elsewhere herein.  All Rights Reserved.
-->

<refentry id="glPointSize">
  <refmeta>
    <refentrytitle>glPointSize</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>glPointSize</refdescriptor>
    <refname>glPointSize</refname>
    <refname>glPointSizex</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>
      <funcprototype>
        <funcdef>void <function>glPointSizex</function></funcdef>
        <paramdef>GLfixed <parameter>size</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <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>
    <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>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><math>
      <mfenced><mi>x</mi><mi>y</mi></mfenced>
    </math></inlineequation>
    of the pixel fragment that represents the point is computed
    as</para>

    <informalequation><math>
      <mfenced> 
        <mrow>
          <mo>&LeftFloor;</mo>
          <msub><mi>x</mi><mi>w</mi></msub>
          <mo>&RightFloor;</mo>
          <mo>+</mo>
          <mfrac><mn>1</mn><mn>2</mn></mfrac>
        </mrow>
        <mrow>
          <mo>&LeftFloor;</mo>
          <msub><mi>y</mi><mi>w</mi></msub>
          <mo>&RightFloor;</mo>
          <mo>+</mo>
          <mfrac><mn>1</mn><mn>2</mn></mfrac>
        </mrow>
      </mfenced>
    </math></informalequation>

    <para>where <replaceable>w</replaceable>
    subscripts indicate window coordinates. All pixels that lie
    within the square grid of the rounded size centered at
    <inlineequation><math>
      <mfenced><mi>x</mi><mi>y</mi></mfenced>
    </math></inlineequation>
    make up the fragment. If the size is even, the center point
    is</para>

    <informalequation><math>
      <mfenced> 
        <mrow>
          <mo>&LeftFloor;</mo>
          <msub><mi>x</mi><mi>w</mi></msub>
          <mo>+</mo>
          <mfrac><mn>1</mn><mn>2</mn></mfrac>
          <mo>&RightFloor;</mo>
        </mrow>
        <mrow>
          <mo>&LeftFloor;</mo>
          <msub><mi>y</mi><mi>w</mi></msub>
          <mo>+</mo>
          <mfrac><mn>1</mn><mn>2</mn></mfrac>
          <mo>&RightFloor;</mo>
        </mrow>
      </mfenced>
    </math></informalequation>

    <para>and the rasterized fragment's centers are the
    half-integer window coordinates within the square of the
    rounded size centered at
    <inlineequation><math>
      <mfenced><mi>x</mi><mi>y</mi></mfenced>
    </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><math>
      <mfenced>
        <msub><mi>x</mi><mi>w</mi></msub>
        <msub><mi>y</mi><mi>w</mi></msub>
      </mfenced>
    </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, call 
    <citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
    with the argument 
    <constant>GL_SMOOTH_POINT_SIZE_RANGE</constant>.
    For aliased points, query the supported ranges 
    <citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
    with the argument 
    <constant>GL_ALIASED_POINT_SIZE_RANGE</constant>.</para>
  </refsect1>

  <refsect1>
    <title>Notes</title>

    <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>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>
    <constant>GL_INVALID_VALUE</constant> is generated if 
    <parameter>size</parameter> is less than or equal to 0.</para>
  </refsect1>

  <refsect1>
    <title>Associated Gets</title>

    <para>
    <citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
    with argument <constant>GL_ALIASED_POINT_SIZE_RANGE</constant></para>

    <para>
    <citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
    with argument <constant>GL_SMOOTH_POINT_SIZE_RANGE</constant></para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
    <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>, 
    <citerefentry><refentrytitle>glGetInteger</refentrytitle></citerefentry>
    </para>
  </refsect1>
</refentry>