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 Details

  • 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:

    • 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:

    • 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.