Package icyllis.arc3d.granite.shading

# Class UniformHandler

java.lang.Object
icyllis.arc3d.granite.shading.UniformHandler

public class UniformHandler extends Object
Class that builds a uniform block.

The uniform blocks are generally defined as:

     // Anonymous block
     layout(std140, binding = 0) uniform UniformBlock {
         layout(offset = 0) vec4 SV_Projection;
         // per-effect uniforms...
     }

Per-effect uniforms are updated more frequently (generally, each draw op). We should limit the UBO size to 128 bytes.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static @interface`
  `UniformHandler.SamplerHandle`
  Marks an integer as an opaque handle to a sampler resource.
  `static @interface`
  `UniformHandler.UniformHandle`
  Marks an integer as an opaque handle to a uniform resource.
  `static class`
  `UniformHandler.UniformInfo`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `INPUT_BINDING`
  The bindings for the input descriptor set.
  `static final int`
  `INPUT_DESC_SET`
  `static final int`
  `MAIN_DESC_SET`
  Binding a descriptor set invalidates all higher index descriptor sets.
  `int`
  `mCurrentOffset`
  `final ArrayList<UniformHandler.UniformInfo>`
  `mSamplers`
  `protected final ShaderCaps`
  `mShaderCaps`
  `final ArrayList<UniformHandler.UniformInfo>`
  `mUniforms`
  `static final String`
  `NO_MANGLE_PREFIX`
  `static final String`
  `PAINT_COLOR_NAME`
  The non-premultiplied paint color, when it cannot be simplified.
  `static final String`
  `PROJECTION_NAME`
  The 2D orthographic projection matrix has only 4 values (others are identity), so this is a vec4.
  `static final int`
  `SAMPLER_DESC_SET`
  `static final int`
  `Std140Layout`
  Layouts.
  `static final int`
  `Std430Layout`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UniformHandler(ShaderCaps shaderCaps, int layout)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected int`
  `addInputSampler(short swizzle, String name)`
  `int`
  `addSampler(byte type, String name, int manglingSuffix)`
  `final int`
  `addUniform(int visibility, byte type, String name, int manglingSuffix)`
  Add a uniform variable to the current program, that has visibility in one or more shaders.
  `final int`
  `addUniformArray(int visibility, byte type, String name, int arraySize, int manglingSuffix)`
  Array version of `addUniform(int, byte, String, int)`.
  `void`
  `appendSamplerDecls(int visibility, StringBuilder out)`
  `boolean`
  `appendUniformDecls(int visibility, int binding, String blockName, StringBuilder out)`
  Append one block declaration.
  `void`
  `finish(boolean reorderUniforms)`
  `static int`
  `getAlignedOffset(int offset, byte type, int arraySize, int layout)`
  Given the current offset into the UBO data, calculate the offset for the uniform we're trying to add taking into consideration all alignment requirements.
  `static int`
  `getAlignedStride(byte type, int arraySize, int layout)`
  `static int`
  `getAlignmentMask(byte type, boolean nonArray, int layout)`
  Returns the base alignment mask in bytes taken up in UBO for SLTypes.
  `static int`
  `getSize(byte type, int layout)`
  Returns the size in bytes taken up in UBO for SLTypes.
  `final String`
  `getUniformName(int handle)`
  Shortcut for getUniformVariable(handle).getName()
  `ShaderVar`
  `getUniformVariable(int handle)`
  `protected String`
  `inputSamplerVariable(int handle)`
  `protected int`
  `internalAddUniformArray(int visibility, byte type, String name, int arraySize, int manglingSuffix)`
  `int`
  `numSamplers()`
  `int`
  `numUniforms()`
  `String`
  `samplerVariable(int handle)`
  `UniformHandler.UniformInfo`
  `uniform(int index)`

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

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

- ## Field Details

  - ### NO_MANGLE_PREFIX

    public static final String NO_MANGLE_PREFIX
    See Also:
      - Constant Field Values

  - ### PROJECTION_NAME

    public static final String PROJECTION_NAME
    The 2D orthographic projection matrix has only 4 values (others are identity), so this is a vec4. Projection maps world space into clip space.
    See Also:
      - Constant Field Values

  - ### PAINT_COLOR_NAME

    public static final String PAINT_COLOR_NAME
    The non-premultiplied paint color, when it cannot be simplified. This value is shared between stages and deduplicated when building uniforms.
    See Also:
      - `UniformDataGatherer.writePaintColor(float, float, float, float)`
      - Constant Field Values

  - ### Std140Layout

    public static final int Std140Layout
    Layouts.
    See Also:
      - Constant Field Values

  - ### Std430Layout

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

  - ### MAIN_DESC_SET

    public static final int MAIN_DESC_SET
    Binding a descriptor set invalidates all higher index descriptor sets. We must bind in the order of this enumeration. Samplers are after Uniforms because Ops can specify GP textures as dynamic state, meaning they get rebound for each draw in a pipeline while uniforms are bound once before all the draws. We bind input attachments after samplers so those also need to be rebound if we bind new samplers.
    See Also:
      - Constant Field Values

  - ### SAMPLER_DESC_SET

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

  - ### INPUT_DESC_SET

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

  - ### INPUT_BINDING

    public static final int INPUT_BINDING
    The bindings for the input descriptor set.
    See Also:
      - Constant Field Values

  - ### mShaderCaps

    protected final ShaderCaps mShaderCaps

  - ### mUniforms

    public final ArrayList<UniformHandler.UniformInfo> mUniforms

  - ### mSamplers

    public final ArrayList<UniformHandler.UniformInfo> mSamplers

  - ### mCurrentOffset

    public int mCurrentOffset

- ## Constructor Details

  - ### UniformHandler

    public UniformHandler(ShaderCaps shaderCaps, int layout)

- ## Method Details

  - ### addUniform

    public final int addUniform(int visibility, byte type, String name, int manglingSuffix)
    Add a uniform variable to the current program, that has visibility in one or more shaders. visibility is a bitfield of ShaderFlag values indicating from which shaders the uniform should be accessible. At least one bit must be set. Geometry shader uniforms are not supported at this time. The actual uniform name will be mangled. The final uniform name can be retrieved by `getUniformName(int)` with the UniformHandle. Use the `addUniformArray(int, byte, String, int, int)` variant to add an array of uniforms.

    If the name starts with `NO_MANGLE_PREFIX`, the uniform will be assigned to Render Block rather than Effect Block, which may be shared across stages and pipelines. Also, the UniformHandle and its data manager may be only visible and internally handled by implementations.

    Parameters:
      `visibility` - combination of ShaderFlags can be zero as placeholder
      `type` - see `SLDataType`
      `name` - the raw name (pre-mangling), cannot be null or empty
    Returns:
      UniformHandle either from Render Block or Effect Block

  - ### addUniformArray

    public final int addUniformArray(int visibility, byte type, String name, int arraySize, int manglingSuffix)
    Array version of `addUniform(int, byte, String, int)`.
    Parameters:
      `visibility` - combination of ShaderFlags, can be zero as placeholder
      `type` - see `SLDataType`
      `name` - the raw name (pre-mangling), cannot be null or empty
      `arraySize` - the number of elements, cannot be zero
    Returns:
      UniformHandle either from Render Block or Effect Block

  - ### getUniformVariable

    public ShaderVar getUniformVariable(int handle)
    Parameters:
      `handle` - UniformHandle from Effect Block

  - ### getUniformName

    public final String getUniformName(int handle)
    Shortcut for getUniformVariable(handle).getName()
    Parameters:
      `handle` - UniformHandle from Effect Block

  - ### numUniforms

    public int numUniforms()

  - ### numSamplers

    public int numSamplers()

  - ### uniform

    public UniformHandler.UniformInfo uniform(int index)

  - ### internalAddUniformArray

    protected int internalAddUniformArray(int visibility, byte type, String name, int arraySize, int manglingSuffix)

  - ### addSampler

    public int addSampler(byte type, String name, int manglingSuffix)

  - ### samplerVariable

    public String samplerVariable(int handle)

  - ### addInputSampler

    protected int addInputSampler(short swizzle, String name)

  - ### inputSamplerVariable

    protected String inputSamplerVariable(int handle)

  - ### finish

    public void finish(boolean reorderUniforms)

  - ### appendUniformDecls

    public boolean appendUniformDecls(int visibility, int binding, String blockName, StringBuilder out)
    Append one block declaration.
    Parameters:
      `visibility` - one of ShaderFlags
    Returns:
      true if block is not empty

  - ### appendSamplerDecls

    public void appendSamplerDecls(int visibility, StringBuilder out)
    Parameters:
      `visibility` - one of ShaderFlags

  - ### getAlignmentMask

    public static int getAlignmentMask(byte type, boolean nonArray, int layout)
    Returns the base alignment mask in bytes taken up in UBO for SLTypes.
    Parameters:
      `type` - see `SLDataType`
      `nonArray` - true for a single scalar or vector, false for an array of scalars or vectors
      `layout` - 1 for std430 layout, 0 for std140 layout
    Returns:
      base alignment mask

  - ### getSize

    public static int getSize(byte type, int layout)
    Returns the size in bytes taken up in UBO for SLTypes. This includes paddings between components, but does not include paddings at the end of the element.
    Parameters:
      `type` - see `SLDataType`
      `layout` - 1 for std430 layout, 0 for std140 layout
    Returns:
      size in bytes
    See Also:
      - `UniformDataManager`

  - ### getAlignedOffset

    public static int getAlignedOffset(int offset, byte type, int arraySize, int layout)
    Given the current offset into the UBO data, calculate the offset for the uniform we're trying to add taking into consideration all alignment requirements. Use aligned offset plus `getAlignedStride(byte, int, int)` to get the offset to the end of the new uniform.
    Parameters:
      `offset` - the current offset
      `type` - see `SLDataType`
      `arraySize` - see `ShaderVar`
      `layout` - 1 for std430 layout, 0 for std140 layout
    Returns:
      the aligned offset for the new uniform

  - ### getAlignedStride

    public static int getAlignedStride(byte type, int arraySize, int layout)
    See Also:
      - `UniformDataManager`