Package icyllis.arc3d.compiler

# Class ShaderCompiler

java.lang.Object
icyllis.arc3d.compiler.ShaderCompiler

public class ShaderCompiler extends Object
Main compiler entry point. The compiler parses the source text directly into a tree of `Nodes`, while performing basic optimizations such as constant-folding and dead-code elimination. Then the `TranslationUnit` is passed into a `CodeGenerator` to produce compiled output.

This class is not thread-safe, you may want a thread-local instance.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `INVALID_TAG`
  `static final String`
  `POISON_TAG`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ShaderCompiler()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ByteBuffer`
  `compileIntoSPIRV(char[] source, int offset, int length, ShaderKind kind, ShaderCaps shaderCaps, CompileOptions options, ModuleUnit parent)`
  Combination of `parse(java.lang.CharSequence, icyllis.arc3d.compiler.ShaderKind, icyllis.arc3d.compiler.CompileOptions, icyllis.arc3d.compiler.ModuleUnit)` and `generateSPIRV(icyllis.arc3d.compiler.TranslationUnit, icyllis.arc3d.compiler.ShaderCaps)`.
  `ByteBuffer`
  `compileIntoSPIRV(CharSequence source, ShaderKind kind, ShaderCaps shaderCaps, CompileOptions options, ModuleUnit parent)`
  Combination of `parse(java.lang.CharSequence, icyllis.arc3d.compiler.ShaderKind, icyllis.arc3d.compiler.CompileOptions, icyllis.arc3d.compiler.ModuleUnit)` and `generateSPIRV(icyllis.arc3d.compiler.TranslationUnit, icyllis.arc3d.compiler.ShaderCaps)`.
  `void`
  `endContext()`
  `int`
  `errorCount()`
  Returns the number of errors during the last parsing or code generation.
  `ByteBuffer`
  `generateSPIRV(TranslationUnit translationUnit, ShaderCaps shaderCaps)`
  Generates translated SPIR-V code and returns the pointer result.
  `Context`
  `getContext()`
  `ErrorHandler`
  `getErrorHandler()`
  Returns the Compiler's error handler.
  `String`
  `getErrorMessage()`
  Returns the concatenated error (and warning) message during the last parsing or code generation.
  `String`
  `getErrorMessage(boolean showCount)`
  Returns the concatenated error (and warning) message during the last parsing or code generation.
  `TranslationUnit`
  `parse(char[] source, int offset, int length, ShaderKind kind, CompileOptions options, ModuleUnit parent)`
  Parse the source into an abstract syntax tree.
  `TranslationUnit`
  `parse(CharSequence source, ShaderKind kind, CompileOptions options, ModuleUnit parent)`
  Parse the source into an abstract syntax tree.
  `ModuleUnit`
  `parseModule(char[] source, int offset, int length, ShaderKind kind, ModuleUnit parent, boolean builtin)`
  Parse the source into an abstract syntax tree.
  `ModuleUnit`
  `parseModule(CharSequence source, ShaderKind kind, ModuleUnit parent, boolean builtin)`
  Parse the source into an abstract syntax tree.
  `void`
  `startContext(ShaderKind kind, CompileOptions options, ModuleUnit parent, boolean isBuiltin, boolean isModule, char[] source, int offset, int length)`
  `static char[]`
  `toChars(CharSequence s)`
  Helper method to copy a char sequence.
  `static char[]`
  `toChars(CharSequence... elements)`
  Helper method to copy a char sequence array.
  `static char[]`
  `toChars(CharSequence[] elements, int start, int end)`
  Helper method to copy a sub-range of char sequences.
  `static char[]`
  `toChars(List<CharSequence> elements)`
  Helper method to copy a sequence of char sequences.
  `int`
  `warningCount()`
  Returns the number of warnings during the last parsing or code generation.

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

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

- ## Field Details

  - ### INVALID_TAG

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

  - ### POISON_TAG

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

- ## Constructor Details

  - ### ShaderCompiler

    public ShaderCompiler()

- ## Method Details

  - ### getContext

    public Context getContext()

  - ### parse

    @Nullable public TranslationUnit parse(@Nonnull CharSequence source, @Nonnull ShaderKind kind, @Nonnull CompileOptions options, @Nonnull ModuleUnit parent)
    Parse the source into an abstract syntax tree. If the source is a `CharBuffer` and backed by a heap array, then the array is used directly. Otherwise, a copy will be made. Typically, if you want to compile a UTF-8 encoded file, you map the file and call `CharsetDecoder.decode(ByteBuffer)` to obtain the CharBuffer, and directly pass it to here. No copy will be made.
    Parameters:
      `source` - the source text
      `kind` - the shader kind
      `options` - the compile options
      `parent` - the parent module that contains common declarations
    Returns:
      the parsed result, or null if there's an error

  - ### parse

    @Nullable public TranslationUnit parse(@Nonnull char[] source, int offset, int length, @Nonnull ShaderKind kind, @Nonnull CompileOptions options, @Nonnull ModuleUnit parent)
    Parse the source into an abstract syntax tree.
    Parameters:
      `source` - the source text, must be immutable
      `offset` - the offset to the first char as the first line
      `length` - the effective number of chars of the source
      `kind` - the shader kind
      `options` - the compile options
      `parent` - the parent module that contains common declarations
    Returns:
      the parsed result, or null if there's an error

  - ### parseModule

    @Nullable public ModuleUnit parseModule(@Nonnull CharSequence source, @Nonnull ShaderKind kind, @Nonnull ModuleUnit parent, boolean builtin)
    Parse the source into an abstract syntax tree.

    A module unit is a pre-compiled result that contains pre-declared variables and optimized functions, used to compile multiple files.

    Parameters:
      `source` - the source text, a copy will be created
      `kind` - the shader kind
      `parent` - the parent module inherited by the new module
    Returns:
      the parsed result, or null if there's an error

  - ### parseModule

    @Nullable public ModuleUnit parseModule(@Nonnull char[] source, int offset, int length, @Nonnull ShaderKind kind, @Nonnull ModuleUnit parent, boolean builtin)
    Parse the source into an abstract syntax tree.

    A module unit is a pre-compiled result that contains pre-declared variables and optimized functions, used to compile multiple files.

    Parameters:
      `source` - the source text, must be immutable
      `kind` - the shader kind
      `parent` - the parent module inherited by the new module
    Returns:
      the parsed result, or null if there's an error

  - ### generateSPIRV

    @Nullable public ByteBuffer generateSPIRV(@Nonnull TranslationUnit translationUnit, @Nonnull ShaderCaps shaderCaps)
    Generates translated SPIR-V code and returns the pointer result. The code size in bytes is `Buffer.remaining()`.

    The return value is a direct buffer, see `ByteBuffer.allocateDirect(int)`. A direct buffer wraps an address that points to off-heap memory, i.e. a native pointer. The byte order is `ByteOrder.nativeOrder()` (i.e. host endianness) and it's safe to pass the result to OpenGL and Vulkan API. There is no way to free this buffer explicitly, as it is subject to GC.

    Check errors via `getErrorMessage()`.

    Returns:
      the translated shader code (uint32_t *), or null if there's an error

  - ### compileIntoSPIRV

    @Nullable public ByteBuffer compileIntoSPIRV(@Nonnull CharSequence source, @Nonnull ShaderKind kind, @Nonnull ShaderCaps shaderCaps, @Nonnull CompileOptions options, @Nonnull ModuleUnit parent)
    Combination of `parse(java.lang.CharSequence, icyllis.arc3d.compiler.ShaderKind, icyllis.arc3d.compiler.CompileOptions, icyllis.arc3d.compiler.ModuleUnit)` and `generateSPIRV(icyllis.arc3d.compiler.TranslationUnit, icyllis.arc3d.compiler.ShaderCaps)`.

    Use this method if you don't need parsed IR, then this method can do some optimizations.

    See Also:
      - `parse(CharSequence, ShaderKind, CompileOptions, ModuleUnit)`
      - `generateSPIRV(TranslationUnit, ShaderCaps)`

  - ### compileIntoSPIRV

    @Nullable public ByteBuffer compileIntoSPIRV(@Nonnull char[] source, int offset, int length, @Nonnull ShaderKind kind, @Nonnull ShaderCaps shaderCaps, @Nonnull CompileOptions options, @Nonnull ModuleUnit parent)
    Combination of `parse(java.lang.CharSequence, icyllis.arc3d.compiler.ShaderKind, icyllis.arc3d.compiler.CompileOptions, icyllis.arc3d.compiler.ModuleUnit)` and `generateSPIRV(icyllis.arc3d.compiler.TranslationUnit, icyllis.arc3d.compiler.ShaderCaps)`.

    Use this method if you don't need parsed IR, then this method can do some optimizations.

    See Also:
      - `parse(char[], int, int, ShaderKind, CompileOptions, ModuleUnit)`
      - `generateSPIRV(TranslationUnit, ShaderCaps)`

  - ### startContext

    @Internal public void startContext(ShaderKind kind, CompileOptions options, ModuleUnit parent, boolean isBuiltin, boolean isModule, char[] source, int offset, int length)

  - ### endContext

    @Internal public void endContext()

  - ### toChars

    @Nonnull public static char[] toChars(@Nonnull CharSequence s)
    Helper method to copy a char sequence.
    Returns:
      a new char buffer copied from the given element

  - ### toChars

    @Nonnull public static char[] toChars(@Nonnull CharSequence... elements)
    Helper method to copy a char sequence array. Character sequences will be concatenated together.
    Returns:
      a new char buffer copied from the given elements

  - ### toChars

    @Nonnull public static char[] toChars(@Nonnull CharSequence[] elements, int start, int end)
    Helper method to copy a sub-range of char sequences. Character sequences will be concatenated together. Empty sequences will be ignored.
    Parameters:
      `start` - start index (inclusive) in elements
      `end` - end index (exclusive) in elements
    Returns:
      a new char buffer copied from the given elements

  - ### toChars

    @Nonnull public static char[] toChars(@Nonnull List<CharSequence> elements)
    Helper method to copy a sequence of char sequences. Character sequences will be concatenated together. Empty sequences will be ignored.
    Returns:
      a new char buffer copied from the given elements

  - ### getErrorMessage

    @Nonnull public String getErrorMessage()
    Returns the concatenated error (and warning) message during the last parsing or code generation. This may be empty or contain multiple lines.

  - ### getErrorMessage

    @Nonnull public String getErrorMessage(boolean showCount)
    Returns the concatenated error (and warning) message during the last parsing or code generation. This may be empty or contain multiple lines.
    Parameters:
      `showCount` - show the number of errors and warnings, if there are any

  - ### getErrorHandler

    public ErrorHandler getErrorHandler()
    Returns the Compiler's error handler.

  - ### errorCount

    public int errorCount()
    Returns the number of errors during the last parsing or code generation.

  - ### warningCount

    public int warningCount()
    Returns the number of warnings during the last parsing or code generation.