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

      public @Nullable TranslationUnit parse(@NonNull CharSequence source, @NonNull ShaderKind kind, @NonNull CompileOptions options, @NonNull ModuleUnit parent)
      Parse the source into an abstract syntax tree.
      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

      public @Nullable TranslationUnit parse(@NonNull String source, @NonNull ShaderKind kind, @NonNull CompileOptions options, @NonNull ModuleUnit parent)
      Parse the source into an abstract syntax tree. The whole source string will be kept by TranslationUnit.
      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

    • parseModule

      public @Nullable 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

      public @Nullable ModuleUnit parseModule(@NonNull String 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, 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

    • generateGLSL

      public @Nullable ByteBuffer generateGLSL(@NonNull TranslationUnit translationUnit, @NonNull ShaderCaps shaderCaps)

    • generateSPIRV

      public @Nullable 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

      public @Nullable 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

      public @Nullable ByteBuffer compileIntoSPIRV(@NonNull String 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:

    • startContext

      @Internal public void startContext(ShaderKind kind, CompileOptions options, ModuleUnit parent, boolean isBuiltin, boolean isModule, String source)

    • endContext

      @Internal public void endContext()

    • toChars

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

    • toChars

      public static char @NonNull [] 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

      public static char @NonNull [] toChars(CharSequence @NonNull [] 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

      public static char @NonNull [] 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

      public @NonNull 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

      public @NonNull 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.