    --------------------------------------------------------------------------------
    -- |
    -- Module      :  Graphics.Rendering.OpenGL.GL.Points
    -- Copyright   :  (c) Sven Panne 2002-2006
    -- License     :  BSD-style (see the file libraries/OpenGL/LICENSE)
    --
    -- Maintainer  :  sven.panne@aedion.de
    -- Stability   :  stable
    -- Portability :  portable
    --
    -- This module corresponds to section 3.3 (Points) of the OpenGL 2.1 specs.
    --
    --------------------------------------------------------------------------------

    module Graphics.Rendering.OpenGL.GL.Points (
       -- * Point Rasterization
       pointSize, vertexProgramPointSize,

       -- * Controlling the Derived Size
       pointSizeRange, pointDistanceAttenuation,

       -- * Fading Points
       pointFadeThresholdSize,

       -- * Point Antialiasing
       pointSmooth,

       -- * Point Sprites
       pointSprite,

       -- * Implementation-Dependent Limits
       aliasedPointSizeRange, smoothPointSizeRange, smoothPointSizeGranularity
    ) where

    import Control.Monad ( liftM2 )
    import Foreign.Marshal.Array ( withArray )
    import Graphics.Rendering.OpenGL.GL.Capability (
       EnableCap(CapVertexProgramPointSize,CapPointSmooth,CapPointSprite),
       makeCapability )
    import Graphics.Rendering.OpenGL.GL.BasicTypes ( GLfloat, Capability )
    import Graphics.Rendering.OpenGL.GL.QueryUtils (
       GetPName(GetPointSize,GetAliasedPointSizeRange,GetSmoothPointSizeRange,
                GetSmoothPointSizeGranularity,GetPointSizeMin,GetPointSizeMax,
                GetPointDistanceAttenuation,GetPointFadeThresholdSize),
       getFloat1, getFloat2, getFloat3 )
    import Graphics.Rendering.OpenGL.GL.PointParameter (
       PointParameter(..), pointParameterf, pointParameterfv )
    import Graphics.Rendering.OpenGL.GL.StateVar (
       GettableStateVar, makeGettableStateVar, StateVar, makeStateVar )

    --------------------------------------------------------------------------------

    -- | 'pointSize' contains the rasterized diameter of both aliased and
    -- antialiased points. The initial value is 1. Using a point size other than 1
    -- has different effects, depending on whether point antialiasing is enabled
    -- (see 'pointSmooth') or point sprites are enabled (see 'pointSprite'). Both
    -- are initially disabled.
    --
    -- The specified point size is multiplied with a distance attenuation factor
    -- and clamped to the specified 'pointSizeRange', and further clamped to the
    -- implementation-dependent point size range to produce the derived point size
    -- using
    --
    -- @   /derivedSize/ = /clamp/ (/size/ * /sqrt/ (1 \/ (/a/ + /b/ * /d/ + /c/ * /d/^2)))@
    --
    -- where /d/ is the eye-coordinate distance from the eye to the vertex, and /a/,
    -- /b/, and /c/ are the distance attenuation coefficients (see
    -- 'pointDistanceAttenuation').
    --
    -- If multisampling is disabled, the computed point size is used as the point\'s
    -- width.
    --
    -- If multisampling is enabled, the point may be faded by modifying the point
    -- alpha value (see 'Graphics.Rendering.OpenGL.GL.PerFragment.sampleCoverage')
    -- instead of allowing the point width to go below a given
    -- 'pointFadeThresholdSize'. In this case, the width is further modified in
    -- the following manner:
    --
    -- @   /width/ = if /derivedSize/ >= /threshold/ then /derivedSize/ else /threshold/@
    --
    -- The point alpha value is modified by computing:
    --
    -- @   /alpha/ = if /derivedSize/ >= /threshold/ then 1 else (/derivedSize/ \/ /threshold/)^2@
    --
    -- 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 (/x/, /y/) of the pixel fragment that represents
    -- the point is computed as
    --
    -- @   (/x/, /y/) = (/floor/ /xw/ + 0.5, /floor/ /yw/ + 0.5)@
    --
    -- where /xw/ and /yw/ indicate window coordinates. All pixels that lie within
    -- the square grid of the rounded size centered at (/x/, /y/) make up the
    -- fragment. If the size is even, the center point is
    --
    -- @   (/x/, /y/) = (/floor/ (/xw/ + 0.5), /floor/ (/yw/ + 0.5))@
    --
    -- and the rasterized fragment\'s centers are the half-integer window
    -- coordinates within the square of the rounded size centered at (/x/, /y/). All
    -- pixel fragments produced in rasterizing a nonantialiased point are assigned
    -- the same associated data, that of the vertex corresponding to the point.
    --
    -- 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
    -- (/xw/, /yw/). 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.
    --
    -- 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 for antialiased points and the size
    -- difference between supported sizes within the range, query
    -- 'smoothPointSizeRange' and 'smoothPointSizeGranularity', respectively. For
    -- aliased points, query the supported range with 'aliasedPointSizeRange'.
    --
    -- The point size specified when 'pointSize' is set is always returned when it
    -- is queried. Clamping and rounding for aliased and antialiased points have no
    -- effect on the specified value.
    --
    -- 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.
    --
    -- An 'Graphics.Rendering.OpenGL.GLU.Errors.InvalidValue' is generated if
    -- 'pointSize' is set to a value less than or equal to zero.
    --
    -- An 'Graphics.Rendering.OpenGL.GLU.Errors.InvalidOperation' is generated if
    -- 'pointSize' is set during
    -- 'Graphics.Rendering.OpenGL.GL.BeginEnd.renderPrimitive'.

    pointSize :: StateVar GLfloat
    pointSize = makeStateVar (getFloat1 id GetPointSize) glPointSize

    foreign import CALLCONV unsafe "glPointSize" glPointSize :: GLfloat -> IO ()

    --------------------------------------------------------------------------------

    vertexProgramPointSize :: StateVar Capability
    vertexProgramPointSize = makeCapability CapVertexProgramPointSize

    --------------------------------------------------------------------------------

    -- | The range to which the derived point size is clamped, see 'pointSize'. Note
    -- that the size is further clamped to the implementation-dependent limits, see
    -- 'aliasedPointSizeRange' and 'smoothPointSizeRange'. The initial range is
    -- (0, 1).
    --
    -- An 'Graphics.Rendering.OpenGL.GLU.Errors.InvalidValue' is generated if the
    -- lower or upper bound of the range is set to a value less than zero. If the
    -- lower bound is greater than the upper bound, the point size after clamping is
    -- undefined, but no error is generated.

    pointSizeRange :: StateVar (GLfloat, GLfloat)
    pointSizeRange =
       makeStateVar
       (liftM2 (,) (getFloat1 id GetPointSizeMin) (getFloat1 id GetPointSizeMax))
       (\(sizeMin, sizeMax) -> do pointParameterf PointSizeMin sizeMin
                                  pointParameterf PointSizeMax sizeMax)

    --------------------------------------------------------------------------------

    -- | The  constant, linear, and quadratic distance attenuation coefficients, see
    -- 'pointSize'. The initial coefficients are (1, 0, 0).

    pointDistanceAttenuation :: StateVar (GLfloat, GLfloat, GLfloat)
    pointDistanceAttenuation =
       makeStateVar
          (getFloat3 (,,) GetPointDistanceAttenuation)
          (\(a, b, c) -> withArray [a, b, c] $
                            pointParameterfv PointDistanceAttenuation)

    --------------------------------------------------------------------------------

    -- | The threshold for alpha attenuation of points when multisampling is used,
    -- see 'pointSize'. The initial threshold is 1.
    --
    -- An 'Graphics.Rendering.OpenGL.GLU.Errors.InvalidValue' is generated if the
    -- threshold is set to a value less than zero.

    pointFadeThresholdSize :: StateVar GLfloat
    pointFadeThresholdSize =
       makeStateVar
          (getFloat1 id GetPointFadeThresholdSize)
          (pointParameterf PointFadeThresholdSize)

    --------------------------------------------------------------------------------

    -- | Controls whether point antialiasing is enabled. The initial state is
    -- 'Graphics.Rendering.OpenGL.GL.BasicTypes.Disabled'.

    pointSmooth :: StateVar Capability
    pointSmooth = makeCapability CapPointSmooth

    --------------------------------------------------------------------------------

    -- | Controls whether point sprites are enabled. The initial state is
    -- 'Graphics.Rendering.OpenGL.GL.BasicTypes.Disabled'. When point sprites are
    -- enabled, the state of point antialiasing (i.e. 'pointSmooth') is ignored.

    pointSprite :: StateVar Capability
    pointSprite = makeCapability CapPointSprite

    --------------------------------------------------------------------------------

    -- | The smallest and largest supported size of aliased points.

    aliasedPointSizeRange :: GettableStateVar (GLfloat, GLfloat)
    aliasedPointSizeRange =
       makeGettableStateVar $ getFloat2 (,) GetAliasedPointSizeRange

    -- | The smallest and largest supported size of antialiased points.

    smoothPointSizeRange :: GettableStateVar (GLfloat, GLfloat)
    smoothPointSizeRange =
       makeGettableStateVar $ getFloat2 (,) GetSmoothPointSizeRange

    -- | The antialiased point size granularity, i.e. the size difference between
    -- supported sizes.

    smoothPointSizeGranularity :: GettableStateVar GLfloat
    smoothPointSizeGranularity =
       makeGettableStateVar $ getFloat1 id GetSmoothPointSizeGranularity