Package icyllis.arc3d.granite

# Class DrawOrder

java.lang.Object
icyllis.arc3d.granite.DrawOrder

public class DrawOrder extends Object
DrawOrder aggregates the three separate sequences that Granite uses to re-order draws and their sub-steps as much as possible while preserving the painter's order semantics of the public API.

To build the full DrawOrder for a draw, start with its assigned PaintersDepth (i.e. the original painter's order of the draw call). From there, the DrawOrder can be updated to reflect dependencies on previous draws, either from depth-only clip draws or because the draw is transparent and must blend with the previous color values. Lastly, once the CompressedPaintersOrder is finalized, the DrawOrder can be updated to reflect whether the draw will involve the stencil buffer--and if so, specify the disjoint stencil set it belongs to.

The original and effective order that draws are executed in is defined by the PaintersDepth. However, the actual execution order is defined by first the CompressedPaintersOrder and then the DisjointStencilIndex. This means that draws with much higher depths can be executed earlier if painter's order compression allows for it.

Orders are 16-bit unsigned integers.

CompressedPaintersOrder is an ordinal number that allows draw commands to be re-ordered so long as when they are executed, the read/writes to the color|depth attachments respect the original painter's order. Logical draws with the same CompressedPaintersOrder can be assumed to be executed in any order, however that may have been determined (e.g. BoundsManager or relying on a depth test during rasterization).

Each DisjointStencilIndex specifies an implicit set of non-overlapping draws. Assuming that two draws have the same CompressedPaintersOrder and the same DisjointStencilIndex, their sub-steps for multi-pass rendering (stencil-then-cover, etc.) can be intermingled with each other and produce the same results as if each draw's sub-steps were executed in order before moving on to the next draw's.

Ordering within a set can be entirely arbitrary (i.e. all stencil steps can go before all cover steps). Ordering between sets is also arbitrary since all draws share the same CompressedPaintersOrder, so long as one set is entirely drawn before the next.

Two draws that have different CompressedPaintersOrders but the same DisjointStencilIndex are unrelated, they may or may not overlap. The painters order scopes the disjoint sets.

Every draw has an associated depth value. The value is constant across the entire draw and is not related to any varying Z coordinate induced by a 4x4 transform. The painter's depth is stored in the depth attachment and the GREATER depth test is used to reject or accept pixels/samples relative to what has already been rendered into the depth attachment. This allows draws that do not depend on the previous color to be radically re-ordered relative to their original painter's order while producing correct results.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BIT_MASK`
  `static final int`
  `CLEAR_DEPTH`
  `static final int`
  `DEPTH_SHIFT`
  `static final int`
  `MAX_VALUE`
  `static final int`
  `MIN_VALUE`
  `static final int`
  `NO_INTERSECTION`
  `static final int`
  `PAINTERS_ORDER_SHIFT`
  `static final int`
  `STENCIL_INDEX_SHIFT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DrawOrder()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `getDepth(long packedDrawOrder)`
  `static float`
  `getDepthAsFloat(long packedDrawOrder)`
  `static int`
  `getPaintersOrder(long packedDrawOrder)`
  `static int`
  `getStencilIndex(long packedDrawOrder)`
  `static long`
  `makeFromDepth(int depth)`
  `static long`
  `makeFromDepthAndPaintersOrder(int depth, int paintersOrder)`
  `static long`
  `updateWithPaintersOrder(long packedDrawOrder, int prevPaintersOrder)`
  `static long`
  `updateWithStencilIndex(long packedDrawOrder, int disjointSet)`

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MIN_VALUE

    public static final int MIN_VALUE
    See Also:
      - Constant Field Values

  - ### MAX_VALUE

    public static final int MAX_VALUE
    See Also:
      - Constant Field Values

  - ### CLEAR_DEPTH

    public static final int CLEAR_DEPTH
    See Also:
      - Constant Field Values

  - ### NO_INTERSECTION

    public static final int NO_INTERSECTION
    See Also:
      - Constant Field Values

  - ### PAINTERS_ORDER_SHIFT

    public static final int PAINTERS_ORDER_SHIFT
    See Also:
      - Constant Field Values

  - ### STENCIL_INDEX_SHIFT

    public static final int STENCIL_INDEX_SHIFT
    See Also:
      - Constant Field Values

  - ### DEPTH_SHIFT

    public static final int DEPTH_SHIFT
    See Also:
      - Constant Field Values

  - ### BIT_MASK

    public static final int BIT_MASK
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DrawOrder

    public DrawOrder()

- ## Method Details

  - ### makeFromDepth

    public static long makeFromDepth(int depth)

  - ### makeFromDepthAndPaintersOrder

    public static long makeFromDepthAndPaintersOrder(int depth, int paintersOrder)

  - ### getPaintersOrder

    public static int getPaintersOrder(long packedDrawOrder)

  - ### getStencilIndex

    public static int getStencilIndex(long packedDrawOrder)

  - ### getDepth

    public static int getDepth(long packedDrawOrder)

  - ### getDepthAsFloat

    public static float getDepthAsFloat(long packedDrawOrder)

  - ### updateWithPaintersOrder

    public static long updateWithPaintersOrder(long packedDrawOrder, int prevPaintersOrder)

  - ### updateWithStencilIndex

    public static long updateWithStencilIndex(long packedDrawOrder, int disjointSet)