Package org.lwjgl.opengl

Class ARBShadingLanguageInclude

java.lang.Object
org.lwjgl.opengl.ARBShadingLanguageInclude
public class ARBShadingLanguageInclude extends Object
Native bindings to the ARB_shading_language_include extension.

This extension introduces a #include GLSL directive to allow reusing the same shader text in multiple shaders and defines the semantics and syntax of the names allowed in #include directives. It also defines API mechanisms to define the named string backing a #include.

Introduction

The GLSL #include mechanism looks up paths in a tree built through the OpenGL API. This appendix describes the syntax and semantic model of the tree and paths into the tree. How the tree is used is up to users of the tree, like the OpenGL API or GLSL.

The Tree

The tree is a singly rooted hierarchy of tree locations. The root may have one or more child locations, and any location may in turn have its own children. Except for the root, each location has exactly one parent; the root has no parent.

Paths into the Tree

The locations in the tree are created or looked up by path strings. The path string "/" locates the root of the tree. The path "/foo" locates the child "foo" of the root. Formally, a valid path is a sequence of tokens delimited by the beginning of the string, by the path-separator forward slash ( / ), and by the end of the string. The string "foo/bar" has two tokens; "foo" and "bar". The string "/foo/./bar" has 3 tokens; "foo", ".", and "bar". The string "/foo/.." has two tokens; "foo" and "..". The string "/foo/.bar" has two tokens; "foo" and ".bar". A path is invalid if

  • path contains any characters not listed in Section 3.1 "Character Set", or the double quote character, or angled brackets, or any white space characters other than the space character.
  • path has consecutive forward slashes ( // ); "/foo//bar" is not valid (zero length tokens are not allowed).
  • path ends with a forward slash ( / )
  • path contains no characters.

There are no path escape characters, so there is no way to get the forward slash delimiter within a single token.

When using a path to lookup a tree location, the path tokens are used to walk the tree. The initial location to start the walk is specified by the user of the tree and is updated as follows by the tokens in the path. (Paths starting with "/" will start at the root.) Taken left to right:

The token ".." walks to the parent. Or, if already at the root, then the location remains at the root.

The token "." leaves the location unchanged.

Any other token is considered the name of a child of the current location, and walks to that child. (If there is no child of that name, this may result in a failed lookup or in the child being created, as specified by the user of the tree for the operation being performed.)

Associated Strings

Each location in the tree can have an additional string associated with it (that a user like the #include mechanism can use as an included string). This is true even for locations that have children: "/foo/bar" can exist in the tree at the same time that "/foo" has an additional string associated with it. Typically, when a path is used to find a location in the tree, it is for the purpose of returning this associated string.

Hence, the tree can be built from a collection of (path,string) pairs, where path is a string establishing the existence of a location in the tree and string is the string associated with the node. Details of how to do this are specified by the user of the tree.

Requires GLSL 1.10.

  • Field Details

    • GL_SHADER_INCLUDE_ARB

      public static final int GL_SHADER_INCLUDE_ARB
      Accepted by the type parameter of NamedStringARB.
      See Also:

    • GL_NAMED_STRING_LENGTH_ARB

      public static final int GL_NAMED_STRING_LENGTH_ARB
      Accepted by the pname parameter of GetNamedStringivARB.
      See Also:

    • GL_NAMED_STRING_TYPE_ARB

      public static final int GL_NAMED_STRING_TYPE_ARB
      Accepted by the pname parameter of GetNamedStringivARB.
      See Also:

  • Method Details

    • nglNamedStringARB

      public static void nglNamedStringARB(int type, int namelen, long name, int stringlen, long string)
      Unsafe version of: NamedStringARB
      Parameters:
      namelen - the number of characters in name. If negative, name is considered to be a null-terminated string.
      stringlen - the number of characters in string. If negative, string is considered to be a null-terminated string.

    • glNamedStringARB

      public static void glNamedStringARB(int type, ByteBuffer name, ByteBuffer string)
      Specifies a string and its name. Such strings can be included by name in shaders during compilation, allowing reuse of the same code segments.

      After calling NamedStringARB, the contents of string are associated with the tree location corresponding to name. If a string is already associated with that tree location, it will be replaced with the new string.

      Parameters:
      type - the string type. Must be:
      SHADER_INCLUDE_ARB
      name - the name associated with the string
      string - an arbitrary string of characters

    • glNamedStringARB

      public static void glNamedStringARB(int type, CharSequence name, CharSequence string)
      Specifies a string and its name. Such strings can be included by name in shaders during compilation, allowing reuse of the same code segments.

      After calling NamedStringARB, the contents of string are associated with the tree location corresponding to name. If a string is already associated with that tree location, it will be replaced with the new string.

      Parameters:
      type - the string type. Must be:
      SHADER_INCLUDE_ARB
      name - the name associated with the string
      string - an arbitrary string of characters

    • nglDeleteNamedStringARB

      public static void nglDeleteNamedStringARB(int namelen, long name)
      Unsafe version of: DeleteNamedStringARB
      Parameters:
      namelen - the number of characters in name. If negative, name is considered to be a null-terminated string.

    • glDeleteNamedStringARB

      public static void glDeleteNamedStringARB(ByteBuffer name)
      Deletes a named string.
      Parameters:
      name - the name associated with the string

    • glDeleteNamedStringARB

      public static void glDeleteNamedStringARB(CharSequence name)
      Deletes a named string.
      Parameters:
      name - the name associated with the string

    • nglCompileShaderIncludeARB

      public static void nglCompileShaderIncludeARB(int shader, int count, long path, long length)
      Unsafe version of: CompileShaderIncludeARB

    • glCompileShaderIncludeARB

      public static void glCompileShaderIncludeARB(int shader, org.lwjgl.PointerBuffer path, @Nullable IntBuffer length)
      Compiles a shader object.

      The ordered list of paths is used during compilation, together with the arguments of #include directives in the shader source, to search for named strings corresponding to the #include directives. If a #include directive does not correspond to a valid named string, compilation will fail.

      Parameters:
      shader - the shader object compile
      path - an ordered array of count pointers to optionally null-terminated character strings defining search paths
      length - an array count values with the number of characters in each string (the string length). If an element in length is negative, its accompanying string is null-terminated. If length is NULL, all strings in the path argument are considered null-terminated.

    • nglIsNamedStringARB

      public static boolean nglIsNamedStringARB(int namelen, long name)
      Unsafe version of: IsNamedStringARB
      Parameters:
      namelen - the number of characters in name. If negative, name is considered to be a null-terminated string.

    • glIsNamedStringARB

      public static boolean glIsNamedStringARB(ByteBuffer name)
      Returns TRUE if the tree location corresponding to name has a string associated with it, and FALSE if the tree location has no string associated with it.
      Parameters:
      name - the name associated with the string

    • glIsNamedStringARB

      public static boolean glIsNamedStringARB(CharSequence name)
      Returns TRUE if the tree location corresponding to name has a string associated with it, and FALSE if the tree location has no string associated with it.
      Parameters:
      name - the name associated with the string

    • nglGetNamedStringARB

      public static void nglGetNamedStringARB(int namelen, long name, int bufSize, long stringlen, long string)
      Unsafe version of: GetNamedStringARB
      Parameters:
      namelen - the number of characters in name. If negative, name is considered to be a null-terminated string.
      bufSize - the maximum number of characters that may be written into string, including the null terminator

    • glGetNamedStringARB

      public static void glGetNamedStringARB(ByteBuffer name, @Nullable IntBuffer stringlen, ByteBuffer string)
      Returns in string the string corresponding to the specified name. The returned string will be null-terminated.
      Parameters:
      name - the name associated with the string
      stringlen - a buffer in which to place the actual number of characters written into string, excluding the null terminator. If NULL, no length is returned.
      string - a buffer in which to place the returned string

    • glGetNamedStringARB

      public static void glGetNamedStringARB(CharSequence name, @Nullable IntBuffer stringlen, ByteBuffer string)
      Returns in string the string corresponding to the specified name. The returned string will be null-terminated.
      Parameters:
      name - the name associated with the string
      stringlen - a buffer in which to place the actual number of characters written into string, excluding the null terminator. If NULL, no length is returned.
      string - a buffer in which to place the returned string

    • glGetNamedStringARB

      public static String glGetNamedStringARB(CharSequence name, int bufSize)
      Returns in string the string corresponding to the specified name. The returned string will be null-terminated.
      Parameters:
      name - the name associated with the string
      bufSize - the maximum number of characters that may be written into string, including the null terminator

    • glGetNamedStringARB

      public static String glGetNamedStringARB(CharSequence name)
      Returns in string the string corresponding to the specified name. The returned string will be null-terminated.
      Parameters:
      name - the name associated with the string

    • nglGetNamedStringivARB

      public static void nglGetNamedStringivARB(int namelen, long name, int pname, long params)
      Unsafe version of: GetNamedStringivARB
      Parameters:
      namelen - the number of characters in name. If negative, name is considered to be a null-terminated string.

    • glGetNamedStringivARB

      public static void glGetNamedStringivARB(ByteBuffer name, int pname, IntBuffer params)
      Returns properties of the named string whose tree location corresponds to name.
      Parameters:
      name - the name associated with the string
      pname - the parameter to query. One of:
      NAMED_STRING_LENGTH_ARBNAMED_STRING_TYPE_ARB
      params - a buffer in which to place the returned value

    • glGetNamedStringivARB

      public static void glGetNamedStringivARB(CharSequence name, int pname, IntBuffer params)
      Returns properties of the named string whose tree location corresponds to name.
      Parameters:
      name - the name associated with the string
      pname - the parameter to query. One of:
      NAMED_STRING_LENGTH_ARBNAMED_STRING_TYPE_ARB
      params - a buffer in which to place the returned value

    • glGetNamedStringiARB

      public static int glGetNamedStringiARB(CharSequence name, int pname)
      Returns properties of the named string whose tree location corresponds to name.
      Parameters:
      name - the name associated with the string
      pname - the parameter to query. One of:
      NAMED_STRING_LENGTH_ARBNAMED_STRING_TYPE_ARB

    • glCompileShaderIncludeARB

      public static void glCompileShaderIncludeARB(int shader, org.lwjgl.PointerBuffer path, @Nullable int[] length)
      Array version of: CompileShaderIncludeARB

    • glGetNamedStringARB

      public static void glGetNamedStringARB(ByteBuffer name, @Nullable int[] stringlen, ByteBuffer string)
      Array version of: GetNamedStringARB

    • glGetNamedStringARB

      public static void glGetNamedStringARB(CharSequence name, @Nullable int[] stringlen, ByteBuffer string)
      Array version of: GetNamedStringARB

    • glGetNamedStringivARB

      public static void glGetNamedStringivARB(ByteBuffer name, int pname, int[] params)
      Array version of: GetNamedStringivARB

    • glGetNamedStringivARB

      public static void glGetNamedStringivARB(CharSequence name, int pname, int[] params)
      Array version of: GetNamedStringivARB