com.jogamp.opengl.math.geom

## Class Frustum

- java.lang.Object
- - com.jogamp.opengl.math.geom.Frustum

-     public class Frustum
      extends Object

  Providing frustum `planes` derived by different inputs (`P*MV`, ..) used to `classify objects` and to test whether they are `outside`.

  Extracting the world-frustum planes from the P*Mv:

       Fast Extraction of Viewing Frustum Planes from the World-View-Projection Matrix
         Gil Gribb
         Klaus Hartmann
         http://graphics.cs.ucf.edu/cap4720/fall2008/plane_extraction.pdf

  Classifying Point, Sphere and AABBox:

       Efficient View Frustum Culling
         Daniel Sýkora
         Josef Jelínek
         http://www.cg.tuwien.ac.at/hostings/cescg/CESCG-2002/DSykoraJJelinek/index.html

       Lighthouse3d.com
       http://www.lighthouse3d.com/tutorials/view-frustum-culling/

  Fundamentals about Planes, Half-Spaces and Frustum-Culling:

       Planes and Half-Spaces,  Max Wagner
       http://www.emeyex.com/site/tuts/PlanesHalfSpaces.pdf

       Frustum Culling,  Max Wagner
       http://www.emeyex.com/site/tuts/FrustumCulling.pdf

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Frustum.Location`
    `static class` | `Frustum.Plane` Plane equation := dot(n, x - p) = 0 -> ax + bc + cx + d == 0

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BOTTOM` Index for bottom plane: 2
    `static int` | `FAR` Index for far plane: 5
    `static int` | `LEFT` Index for left plane: 0
    `static int` | `NEAR` Index for near plane: 4
    `static int` | `RIGHT` Index for right plane: 1
    `static int` | `TOP` Index for top plane: 3

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Frustum()` Creates an undefined instance w/o calculating the frustum.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Frustum.Location` | `classifyPoint(float[] p)` Check to see if a point is outside, inside or on a plane of the frustum.
    `Frustum.Location` | `classifySphere(float[] p, float radius)` Check to see if a sphere is outside, intersecting or inside of the frustum.
    `Frustum.Plane[]` | `getPlanes()` `Frustum.Plane`s are ordered in the returned array as follows: `LEFT` `RIGHT` `BOTTOM` `TOP` `NEAR` `FAR`
    `boolean` | `isAABBoxOutside(AABBox box)` Check to see if an axis aligned bounding box is completely outside of the frustum.
    `boolean` | `isPointOutside(float[] p)` Check to see if a point is outside of the frustum.
    `boolean` | `isSphereOutside(float[] p, float radius)` Check to see if a sphere is outside of the frustum.
    `String` | `toString()`
    `StringBuilder` | `toString(StringBuilder sb)`
    `void` | `updateByPlanes(Frustum.Plane[] src)` Copy the given `src` planes into this this instance's planes.
    `void` | `updateByPMV(float[] pmv, int pmv_off)` Calculate the frustum planes in world coordinates using the passed float[16] as premultiplied P*MV (column major order).

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### LEFT

          public static final int LEFT

      Index for left plane: 0
      See Also:
        Constant Field Values

    - #### RIGHT

          public static final int RIGHT

      Index for right plane: 1
      See Also:
        Constant Field Values

    - #### BOTTOM

          public static final int BOTTOM

      Index for bottom plane: 2
      See Also:
        Constant Field Values

    - #### TOP

          public static final int TOP

      Index for top plane: 3
      See Also:
        Constant Field Values

    - #### NEAR

          public static final int NEAR

      Index for near plane: 4
      See Also:
        Constant Field Values

    - #### FAR

          public static final int FAR

      Index for far plane: 5
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Frustum

          public Frustum()

      Creates an undefined instance w/o calculating the frustum.

      Use one of the `update(..)` methods to set the `planes`.

      See Also:
        `updateByPlanes(Plane[])`, `updateByPMV(float[], int)`

  - ### Method Detail

    - #### getPlanes

          public final Frustum.Plane[] getPlanes()

      `Frustum.Plane`s are ordered in the returned array as follows:
      - `LEFT`
      - `RIGHT`
      - `BOTTOM`
      - `TOP`
      - `NEAR`
      - `FAR`

      `Frustum.Plane`'s normals are pointing to the inside of the frustum in order to work w/ `isOutside(..)` methods.

      Returns:
        array of normalized `Frustum.Plane`s, order see above.

    - #### updateByPlanes

          public final void updateByPlanes(Frustum.Plane[] src)

      Copy the given `src` planes into this this instance's planes.
      Parameters:
        `src` - the 6 source planes

    - #### updateByPMV

          public void updateByPMV(float[] pmv,
                         int pmv_off)

      Calculate the frustum planes in world coordinates using the passed float[16] as premultiplied P*MV (column major order).

      Frustum plane's normals will point to the inside of the viewing frustum, as required by this class.

    - #### isAABBoxOutside

          public final boolean isAABBoxOutside(AABBox box)

      Check to see if an axis aligned bounding box is completely outside of the frustum.

      Note: If method returns false, the box may only be partially inside.

    - #### classifyPoint

          public final Frustum.Location classifyPoint(float[] p)

      Check to see if a point is outside, inside or on a plane of the frustum.
      Parameters:
        `p` - the point
      Returns:
        `Frustum.Location` of point related to frustum planes

    - #### isPointOutside

          public final boolean isPointOutside(float[] p)

      Check to see if a point is outside of the frustum.
      Parameters:
        `p` - the point
      Returns:
        true if outside of the frustum, otherwise inside or on a plane

    - #### classifySphere

          public final Frustum.Location classifySphere(float[] p,
                                        float radius)

      Check to see if a sphere is outside, intersecting or inside of the frustum.
      Parameters:
        `p` - center of the sphere
        `radius` - radius of the sphere
      Returns:
        `Frustum.Location` of point related to frustum planes

    - #### isSphereOutside

          public final boolean isSphereOutside(float[] p,
                                float radius)

      Check to see if a sphere is outside of the frustum.
      Parameters:
        `p` - center of the sphere
        `radius` - radius of the sphere
      Returns:
        true if outside of the frustum, otherwise inside or intersecting

    - #### toString

          public StringBuilder toString(StringBuilder sb)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright 2010 JogAmp Community.