Package icyllis.arc3d.granite

# Class GeometryStep

java.lang.Object
icyllis.arc3d.granite.GeometryStep

Direct Known Subclasses:
  `AnalyticArcStep`, `AnalyticSimpleBoxStep`, `CircleProcessor`, `DefaultGeoProc`, `RasterTextStep`, `SDFRectGeoProc`, `VerticesStep`

@Immutable public abstract class GeometryStep extends Object
The GeometryProcessor represents some kind of geometric primitive. This includes the shape of the primitive and the inherent color of the primitive. The GeometryProcessor is responsible for providing a color and coverage input into the rendering pipeline. Through optimization, Engine may decide a different color, no color, and / or no coverage are required from the GeometryProcessor, so the GeometryProcessor must be able to support this functionality.

There are two feedback loops between the FragmentProcessors, the XferProcessor, and the GeometryProcessor. These loops run on the CPU and to determine known properties of the final color and coverage inputs to the XferProcessor in order to perform optimizations that preserve correctness. The DrawOp seeds these loops with initial color and coverage, in its getProcessorAnalysisInputs implementation. These seed values are processed by the subsequent stages of the rendering pipeline and the output is then fed back into the DrawOp in the applyPipelineOptimizations call, where the op can use the information to inform decisions about GeometryProcessor creation.

Note that all derived classes should hide their constructors and provide a Make factory function that takes an arena (except for Tesselation-specific classes). This is because geometry processors can be created in either the record-time or flush-time arenas which define their lifetimes (i.e., a DDLs life time in the first case and a single flush in the second case).

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `GeometryStep.ProgramImpl`
  Every `GeometryStep` must be capable of creating a subclass of ProgramImpl.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final VertexInputLayout.Attribute`
  `DEPTH`
  Painter's depth.
  `static final int`
  `FLAG_EMIT_COVERAGE`
  Set if there's `emitFragmentCoverageCode(Formatter, String)`.
  `static final int`
  `FLAG_EMIT_PRIMITIVE_COLOR`
  Set if this emits per-vertex color, only used for drawing primitives.
  `static final int`
  `FLAG_HANDLE_SOLID_COLOR`
  Set if this can handle solid color from paint params, and draw op does not require any uniform values.
  `static final int`
  `FLAG_HAS_TEXTURES`
  `static final int`
  `FLAG_OUTSET_BOUNDS_FOR_AA`
  Set for analytic antialiasing (AAA) or distance-to-edge antialiasing (DEAA).
  `static final int`
  `FLAG_PERFORM_SHADING`
  Set if there's fragment shader code and color output, otherwise this is a depth-stencil only step.
  `static final VertexInputLayout.Attribute`
  `MODEL_VIEW`
  Local-to-device transform.
  `static final VertexInputLayout.Attribute`
  `SOLID_COLOR`
  Pre-multiplied solid color in destination color space.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `GeometryStep(String className, String variantName, VertexInputLayout.AttributeSet vertexAttributes, VertexInputLayout.AttributeSet instanceAttributes, int flags, byte primitiveType, DepthStencilSettings depthStencilSettings)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `appendAttributesToKey(KeyBuilder b)`
  `abstract void`
  `appendToKey(KeyBuilder b)`
  Appends a key on the KeyBuilder that reflects any variety in the code that the geometry processor subclass can emit.
  `final int`
  `depthStencilFlags()`
  `final DepthStencilSettings`
  `depthStencilSettings()`
  `void`
  `emitFragmentColorCode(Formatter fs, String outputColor)`
  Emits the fragment color code into the fragment shader.
  `void`
  `emitFragmentCoverageCode(Formatter fs, String outputCoverage)`
  Emits the fragment coverage code into the fragment shader.
  `void`
  `emitSamplers(UniformHandler uniformHandler)`
  `final boolean`
  `emitsCoverage()`
  `final boolean`
  `emitsPrimitiveColor()`
  `void`
  `emitUniforms(UniformHandler uniformHandler, boolean mayRequireLocalCoords)`
  `void`
  `emitVaryings(VaryingHandler varyingHandler, boolean usesFastSolidColor)`
  `void`
  `emitVertexGeomCode(Formatter vs, String worldPosVar, String localPosVar, boolean usesFastSolidColor)`
  Emits the geometry code into the vertex shader.
  `VertexInputLayout`
  `getInputLayout()`
  `final boolean`
  `handlesSolidColor()`
  `final boolean`
  `hasInstanceAttributes()`
  Returns true if `numInstanceAttributes()` will return non-zero.
  `final boolean`
  `hasVertexAttributes()`
  Returns true if `numVertexAttributes()` will return non-zero.
  `final Iterator<VertexInputLayout.Attribute>`
  `instanceAttributes()`
  Returns an iterable of used per-instance attributes.
  `final int`
  `instanceBinding()`
  `final int`
  `instanceStride()`
  Returns the number of bytes from one instance to the next instance, including paddings.
  `protected static VertexInputLayout.Attribute`
  `makeColorAttribute(String name, boolean wideColor)`
  GPs that need to use either float or ubyte colors can just call this to get a correctly configured Attribute struct
  `abstract GeometryStep.ProgramImpl`
  `makeProgramImpl(ShaderCaps caps)`
  Returns a new instance of the appropriate implementation class for the given GeometryProcessor.
  `final String`
  `name()`
  Human-meaningful string to identify this processor; may be embedded in generated shader code and must be a legal AkSL identifier prefix.
  `final int`
  `numInstanceAttributes()`
  Returns the number of used per-instance attributes (input variables).
  `final int`
  `numInstanceLocations()`
  Returns the number of used per-instance attribute locations.
  `int`
  `numTextureSamplers()`
  Currently, GP is limited to one texture sampler at most.
  `final int`
  `numVertexAttributes()`
  Returns the number of used per-vertex attributes (input variables).
  `final int`
  `numVertexLocations()`
  Returns the number of used per-vertex attribute locations (slots).
  `final boolean`
  `performsShading()`
  `final byte`
  `primitiveType()`
  Returns a primitive topology for render passes.
  `int`
  `textureSamplerState(int i)`
  Used to capture the properties of the TextureProxies required/expected by a GeometryProcessor along with an associated SamplerState.
  `short`
  `textureSamplerSwizzle(int i)`
  `final int`
  `uniqueID()`
  `final Iterator<VertexInputLayout.Attribute>`
  `vertexAttributes()`
  Returns an iterable of used per-vertex attributes.
  `final int`
  `vertexBinding()`
  `final int`
  `vertexStride()`
  Returns the number of bytes from one vertex to the next vertex, including paddings.
  `void`
  `writeMesh(MeshDrawWriter writer, Draw draw, float[] solidColor, boolean mayRequireLocalCoords)`
  `void`
  `writeUniformsAndTextures(RecordingContext context, Draw draw, UniformDataGatherer uniformDataGatherer, TextureDataGatherer textureDataGatherer, boolean mayRequireLocalCoords)`

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

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

- ## Field Details

  - ### DEPTH

    public static final VertexInputLayout.Attribute DEPTH
    Painter's depth.

  - ### SOLID_COLOR

    public static final VertexInputLayout.Attribute SOLID_COLOR
    Pre-multiplied solid color in destination color space.

  - ### MODEL_VIEW

    public static final VertexInputLayout.Attribute MODEL_VIEW
    Local-to-device transform.

  - ### FLAG_PERFORM_SHADING

    public static final int FLAG_PERFORM_SHADING
    Set if there's fragment shader code and color output, otherwise this is a depth-stencil only step.
    See Also:
      - Constant Field Values

  - ### FLAG_HAS_TEXTURES

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

  - ### FLAG_EMIT_COVERAGE

    public static final int FLAG_EMIT_COVERAGE
    Set if there's `emitFragmentCoverageCode(Formatter, String)`.
    See Also:
      - Constant Field Values

  - ### FLAG_OUTSET_BOUNDS_FOR_AA

    public static final int FLAG_OUTSET_BOUNDS_FOR_AA
    Set for analytic antialiasing (AAA) or distance-to-edge antialiasing (DEAA).
    See Also:
      - Constant Field Values

  - ### FLAG_EMIT_PRIMITIVE_COLOR

    public static final int FLAG_EMIT_PRIMITIVE_COLOR
    Set if this emits per-vertex color, only used for drawing primitives.

    Not compatible with `FLAG_HANDLE_SOLID_COLOR`, `FLAG_EMIT_COVERAGE`, `FLAG_OUTSET_BOUNDS_FOR_AA`.

    See Also:
      - Constant Field Values

  - ### FLAG_HANDLE_SOLID_COLOR

    public static final int FLAG_HANDLE_SOLID_COLOR
    Set if this can handle solid color from paint params, and draw op does not require any uniform values.

    See `emitFragmentColorCode(Formatter, String)` and `writeMesh(MeshDrawWriter, Draw, float[], boolean)`.

    Not compatible with `FLAG_EMIT_PRIMITIVE_COLOR`.

    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### GeometryStep

    protected GeometryStep(@Nonnull String className, @Nonnull String variantName, @Nullable VertexInputLayout.AttributeSet vertexAttributes, @Nullable VertexInputLayout.AttributeSet instanceAttributes, int flags, byte primitiveType, DepthStencilSettings depthStencilSettings)

- ## Method Details

  - ### makeColorAttribute

    @Nonnull protected static VertexInputLayout.Attribute makeColorAttribute(String name, boolean wideColor)
    GPs that need to use either float or ubyte colors can just call this to get a correctly configured Attribute struct

  - ### name

    @Nonnull public final String name()
    Human-meaningful string to identify this processor; may be embedded in generated shader code and must be a legal AkSL identifier prefix.

  - ### uniqueID

    public final int uniqueID()
    Returns:
      unique ID that identifies this processor class.

  - ### primitiveType

    public final byte primitiveType()
    Returns a primitive topology for render passes. If the return values of different instances are different, they must be reflected in the key, see `appendToKey(KeyBuilder)`.
    See Also:
      - `Engine.PrimitiveType`

  - ### numTextureSamplers

    public int numTextureSamplers()
    Currently, GP is limited to one texture sampler at most.

  - ### textureSamplerState

    public int textureSamplerState(int i)
    Used to capture the properties of the TextureProxies required/expected by a GeometryProcessor along with an associated SamplerState. The actual proxies used are stored in either the fixed or dynamic state arrays. TextureSamplers don't perform any coord manipulation to account for texture origin.
    See Also:
      - `SamplerDesc`

  - ### textureSamplerSwizzle

    public short textureSamplerSwizzle(int i)
    See Also:
      - `Swizzle`

  - ### getInputLayout

    public VertexInputLayout getInputLayout()

  - ### hasVertexAttributes

    public final boolean hasVertexAttributes()
    Returns true if `numVertexAttributes()` will return non-zero.
    Returns:
      true if there are per-vertex attributes

  - ### vertexBinding

    public final int vertexBinding()

  - ### numVertexAttributes

    public final int numVertexAttributes()
    Returns the number of used per-vertex attributes (input variables). Note: attribute of a matrix type counts as just one.
    See Also:
      - `numVertexLocations()`

  - ### numVertexLocations

    public final int numVertexLocations()
    Returns the number of used per-vertex attribute locations (slots). An attribute (variable) may take up multiple consecutive locations.
    See Also:
      - `SLDataType.locations(byte)`
      - `numVertexAttributes()`

  - ### vertexAttributes

    @Nonnull public final Iterator<VertexInputLayout.Attribute> vertexAttributes()
    Returns an iterable of used per-vertex attributes. It's safe to call even if there's no attribute. The iterator handles hides two pieces of complexity:
    1. It skips unused attributes (see mask in
       invalid reference

           #setVertexAttributes(int)

       ).
    2. It always returns an attribute with a known offset.

  - ### vertexStride

    public final int vertexStride()
    Returns the number of bytes from one vertex to the next vertex, including paddings. A common practice is to populate the vertex's memory using an implicit array of structs. In this case, it is best to assert that: stride == sizeof(struct).

  - ### hasInstanceAttributes

    public final boolean hasInstanceAttributes()
    Returns true if `numInstanceAttributes()` will return non-zero.
    Returns:
      true if there are per-instance attributes

  - ### instanceBinding

    public final int instanceBinding()

  - ### numInstanceAttributes

    public final int numInstanceAttributes()
    Returns the number of used per-instance attributes (input variables). Note: attribute of a matrix type counts as just one.
    See Also:
      - `numInstanceLocations()`

  - ### numInstanceLocations

    public final int numInstanceLocations()
    Returns the number of used per-instance attribute locations. (slots). An attribute (variable) may take up multiple consecutive locations.
    See Also:
      - `SLDataType.locations(byte)`
      - `numInstanceAttributes()`

  - ### instanceAttributes

    @Nonnull public final Iterator<VertexInputLayout.Attribute> instanceAttributes()
    Returns an iterable of used per-instance attributes. It's safe to call even if there's no attribute. The iterator handles hides two pieces of complexity:
    1. It skips unused attributes (see mask in
       invalid reference

           #setInstanceAttributes(int)

       ).
    2. It always returns an attribute with a known offset.

  - ### instanceStride

    public final int instanceStride()
    Returns the number of bytes from one instance to the next instance, including paddings. A common practice is to populate the instance's memory using an implicit array of structs. In this case, it is best to assert that: stride == sizeof(struct).

  - ### performsShading

    public final boolean performsShading()

  - ### emitsCoverage

    public final boolean emitsCoverage()

  - ### handlesSolidColor

    public final boolean handlesSolidColor()

  - ### emitsPrimitiveColor

    public final boolean emitsPrimitiveColor()

  - ### depthStencilSettings

    public final DepthStencilSettings depthStencilSettings()

  - ### depthStencilFlags

    public final int depthStencilFlags()

  - ### appendToKey

    public abstract void appendToKey(@Nonnull KeyBuilder b)
    Appends a key on the KeyBuilder that reflects any variety in the code that the geometry processor subclass can emit.
    See Also:
      - `makeProgramImpl(ShaderCaps)`

  - ### appendAttributesToKey

    public final void appendAttributesToKey(@Nonnull KeyBuilder b)

  - ### makeProgramImpl

    @Nonnull public abstract GeometryStep.ProgramImpl makeProgramImpl(ShaderCaps caps)
    Returns a new instance of the appropriate implementation class for the given GeometryProcessor. This method is called only when the specified key does not exist in the program cache.
    See Also:
      - `appendToKey(KeyBuilder)`

  - ### emitVaryings

    public void emitVaryings(VaryingHandler varyingHandler, boolean usesFastSolidColor)

  - ### emitUniforms

    public void emitUniforms(UniformHandler uniformHandler, boolean mayRequireLocalCoords)

  - ### emitSamplers

    public void emitSamplers(UniformHandler uniformHandler)

  - ### emitVertexGeomCode

    public void emitVertexGeomCode(Formatter vs, @Nonnull String worldPosVar, @Nullable String localPosVar, boolean usesFastSolidColor)
    Emits the geometry code into the vertex shader. Implementation must define "vec4 worldPosVar" with the given name and setup it. If localPosVar is not null, then it must write geometry's local pos to it.

  - ### emitFragmentColorCode

    public void emitFragmentColorCode(Formatter fs, String outputColor)
    Emits the fragment color code into the fragment shader. This is either paint's solid color or per-vertex primitive color. See `FLAG_HANDLE_SOLID_COLOR` and `FLAG_EMIT_PRIMITIVE_COLOR`.

  - ### emitFragmentCoverageCode

    public void emitFragmentCoverageCode(Formatter fs, String outputCoverage)
    Emits the fragment coverage code into the fragment shader.

    If `emitsCoverage()` is false, this method is called for hard-edge coverage, discard the fragment if coverage is 0. Otherwise outputCoverage is non-null, and coverage will involve in blending operations.

  - ### writeMesh

    public void writeMesh(MeshDrawWriter writer, Draw draw, @Nullable float[] solidColor, boolean mayRequireLocalCoords)

  - ### writeUniformsAndTextures

    public void writeUniformsAndTextures(RecordingContext context, Draw draw, UniformDataGatherer uniformDataGatherer, TextureDataGatherer textureDataGatherer, boolean mayRequireLocalCoords)