Class ARBShadingLanguageInclude



  • public class ARBShadingLanguageInclude
    extends java.lang.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.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method and Description
      static void glCompileShaderIncludeARB(int shader, org.lwjgl.PointerBuffer path, int[] length)
      Array version of: CompileShaderIncludeARB
      static void glCompileShaderIncludeARB(int shader, org.lwjgl.PointerBuffer path, java.nio.IntBuffer length)
      Compiles a shader object.
      static void glDeleteNamedStringARB(java.nio.ByteBuffer name)
      Deletes a named string.
      static void glDeleteNamedStringARB(java.lang.CharSequence name)
      Deletes a named string.
      static void glGetNamedStringARB(java.nio.ByteBuffer name, int[] stringlen, java.nio.ByteBuffer string)
      Array version of: GetNamedStringARB
      static void glGetNamedStringARB(java.nio.ByteBuffer name, java.nio.IntBuffer stringlen, java.nio.ByteBuffer string)
      Returns in string the string corresponding to the specified name.
      static java.lang.String glGetNamedStringARB(java.lang.CharSequence name)
      Returns in string the string corresponding to the specified name.
      static java.lang.String glGetNamedStringARB(java.lang.CharSequence name, int bufSize)
      Returns in string the string corresponding to the specified name.
      static void glGetNamedStringARB(java.lang.CharSequence name, int[] stringlen, java.nio.ByteBuffer string)
      Array version of: GetNamedStringARB
      static void glGetNamedStringARB(java.lang.CharSequence name, java.nio.IntBuffer stringlen, java.nio.ByteBuffer string)
      Returns in string the string corresponding to the specified name.
      static int glGetNamedStringiARB(java.lang.CharSequence name, int pname)
      Returns properties of the named string whose tree location corresponds to name.
      static void glGetNamedStringivARB(java.nio.ByteBuffer name, int pname, int[] params)
      Array version of: GetNamedStringivARB
      static void glGetNamedStringivARB(java.nio.ByteBuffer name, int pname, java.nio.IntBuffer params)
      Returns properties of the named string whose tree location corresponds to name.
      static void glGetNamedStringivARB(java.lang.CharSequence name, int pname, int[] params)
      Array version of: GetNamedStringivARB
      static void glGetNamedStringivARB(java.lang.CharSequence name, int pname, java.nio.IntBuffer params)
      Returns properties of the named string whose tree location corresponds to name.
      static boolean glIsNamedStringARB(java.nio.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.
      static boolean glIsNamedStringARB(java.lang.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.
      static void glNamedStringARB(int type, java.nio.ByteBuffer name, java.nio.ByteBuffer string)
      Specifies a string and its name.
      static void glNamedStringARB(int type, java.lang.CharSequence name, java.lang.CharSequence string)
      Specifies a string and its name.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • glNamedStringARB

        public static void glNamedStringARB(int type,
                                            java.nio.ByteBuffer name,
                                            java.nio.ByteBuffer string)
        
        public static void glNamedStringARB(int type,
                                            java.lang.CharSequence name,
                                            java.lang.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
      • glDeleteNamedStringARB

        public static void glDeleteNamedStringARB(java.nio.ByteBuffer name)
        
        public static void glDeleteNamedStringARB(java.lang.CharSequence name)
        
        Deletes a named string.
        Parameters:
        name - the name associated with the string
      • glCompileShaderIncludeARB

        public static void glCompileShaderIncludeARB(int shader,
                                                     org.lwjgl.PointerBuffer path,
                                                     java.nio.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.
      • glIsNamedStringARB

        public static boolean glIsNamedStringARB(java.nio.ByteBuffer name)
        
        public static boolean glIsNamedStringARB(java.lang.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
      • glGetNamedStringARB

        public static void glGetNamedStringARB(java.nio.ByteBuffer name,
                                               java.nio.IntBuffer stringlen,
                                               java.nio.ByteBuffer string)
        
        public static void glGetNamedStringARB(java.lang.CharSequence name,
                                               java.nio.IntBuffer stringlen,
                                               java.nio.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 java.lang.String glGetNamedStringARB(java.lang.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 java.lang.String glGetNamedStringARB(java.lang.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
      • glGetNamedStringivARB

        public static void glGetNamedStringivARB(java.nio.ByteBuffer name,
                                                 int pname,
                                                 java.nio.IntBuffer params)
        
        public static void glGetNamedStringivARB(java.lang.CharSequence name,
                                                 int pname,
                                                 java.nio.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(java.lang.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,
                                                     int[] length)
        Array version of: CompileShaderIncludeARB
      • glGetNamedStringARB

        public static void glGetNamedStringARB(java.nio.ByteBuffer name,
                                               int[] stringlen,
                                               java.nio.ByteBuffer string)
        
        public static void glGetNamedStringARB(java.lang.CharSequence name,
                                               int[] stringlen,
                                               java.nio.ByteBuffer string)
        
        Array version of: GetNamedStringARB
      • glGetNamedStringivARB

        public static void glGetNamedStringivARB(java.nio.ByteBuffer name,
                                                 int pname,
                                                 int[] params)
        
        public static void glGetNamedStringivARB(java.lang.CharSequence name,
                                                 int pname,
                                                 int[] params)
        
        Array version of: GetNamedStringivARB