Package org.lwjgl.system

Class APIUtil


  • public final class APIUtil
extends java.lang.Object
    Utility class useful to API bindings. [INTERNAL USE ONLY]

    Method names in this class are prefixed with api to avoid ambiguities when used with static imports.

    See Also:
    Configuration.DEBUG_STREAM

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      static class  APIUtil.APIVersion
      A data class for API versioning information.
      static interface  APIUtil.Encoder 

    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.io.PrintStream DEBUG_STREAM
      The PrintStream used by LWJGL to print debug information and non-fatal errors.

    • Field Detail

      • DEBUG_STREAM

        public static final java.io.PrintStream DEBUG_STREAM
        The PrintStream used by LWJGL to print debug information and non-fatal errors. Defaults to System.err which can be changed with Configuration.DEBUG_STREAM.

    • Method Detail

      • apiLog

        public static void apiLog(java.lang.CharSequence msg)
        Prints the specified message to the APIUtil.DEBUG_STREAM if Checks.DEBUG is true.
        Parameters:
        msg - the message to print

      • apiGetManifestValue

        public static java.util.Optional<java.lang.String> apiGetManifestValue(java.lang.String attributeName)
        Returns the value of the specified manifest attribute in the LWJGL JAR file.
        Parameters:
        attributeName - the attribute name
        Returns:
        the attribute value or null if the attribute was not found or there is no LWJGL JAR file

      • apiCreateLibrary

        public static SharedLibrary apiCreateLibrary(java.lang.String name)

      • apiGetFunctionAddress

        public static long apiGetFunctionAddress(FunctionProvider provider,
                                         java.lang.String functionName)

      • apiCreateCallback

        public static long apiCreateCallback(CallbackI function,
                                     java.lang.String signature)
        Creates a native function that delegates to the specified CallbackI instance when called.

        The native function uses the default calling convention.

        Parameters:
        function - the target CallbackI instance
        signature - the dyncall function signature
        Returns:
        the dynamically generated native function

      • apiCreateCallback

        public static long apiCreateCallback(CallbackI function,
                                     java.lang.String signature,
                                     boolean systemCallConvention)
        Creates a native function that delegates to the specified Callback instance when called.
        Parameters:
        function - the target CallbackI instance
        signature - the dyncall function signature
        systemCallConvention - if true, the system calling convention will be used (i.e. stdcall on Windows x86)
        Returns:
        the dynamically generated native function

      • apiParseVersion

        public static APIUtil.APIVersion apiParseVersion(java.lang.String version)
        Parses a version string. The version string must have the format MAJOR.MINOR.REVISION IMPL, where MAJOR is the major version (integer), MINOR is the minor version (integer), REVISION is the revision version (string, optional) and IMPL is implementation-specific information (string, optional).
        Parameters:
        version - the API version string
        Returns:
        the parsed APIUtil.APIVersion

      • apiParseVersion

        public static APIUtil.APIVersion apiParseVersion(java.lang.String version,
                                                 java.lang.String prefix)
        Parses a version string. The version string must have the format PREFIX MAJOR.MINOR.REVISION IMPL, where PREFIX is the specified prefix (string, optional), MAJOR is the major version (integer), MINOR is the minor version (integer), REVISION is the revision version (string, optional) and IMPL is implementation-specific information (string, optional).
        Parameters:
        version - the version string
        prefix - the version string prefix, may be null
        Returns:
        the parsed APIUtil.APIVersion

      • apiUnknownToken

        public static java.lang.String apiUnknownToken(int token)

      • apiUnknownToken

        public static java.lang.String apiUnknownToken(java.lang.String description,
                                               int token)

      • apiClassTokens

        public static java.util.Map<java.lang.Integer,java.lang.String> apiClassTokens(java.util.function.BiPredicate<java.lang.reflect.Field,java.lang.Integer> filter,
                                                                               java.util.Map<java.lang.Integer,java.lang.String> target,
                                                                               java.lang.Class<?>... tokenClasses)
        Returns a map of public static final integer fields in the specified classes, to their String representations. An optional filter can be specified to only include specific fields. The target map may be null, in which case a new map is allocated and returned.

        This method is useful when debugging to quickly identify values returned from an API.

        Parameters:
        filter - the filter to use (optional)
        target - the target map (optional)
        tokenClasses - the classes to get tokens from
        Returns:
        the token map

      • apiOptionalClass

        public static java.lang.Class<?> apiOptionalClass(java.lang.String className)

      • apiCompareCapabilities

        public static boolean apiCompareCapabilities(java.lang.Iterable<java.lang.reflect.Field> flags,
                                             java.lang.Iterable<java.lang.reflect.Field> funcs,
                                             java.lang.Object a,
                                             java.lang.Object b)

      • apiArray

        public static long apiArray(MemoryStack stack,
                            long... addresses)
        Stores the specified array of pointer addresses on the specified MemoryStack.
        Parameters:
        stack - the stack to use
        addresses - the pointer addresses to store
        Returns:
        the pointer array address on the stack

      • apiArray

        public static long apiArray(MemoryStack stack,
                            java.nio.ByteBuffer... buffers)
        Stores the addresses of the specified array of buffers on the specified MemoryStack.
        Parameters:
        stack - the stack to use
        buffers - the buffers to store
        Returns:
        the pointer array address on the stack

      • apiArrayp

        public static long apiArrayp(MemoryStack stack,
                             java.nio.ByteBuffer... buffers)
        Stores the addresses of the specified array of buffers on the specified MemoryStack. A second array that contains the buffer remaining bytes is stored immediately after the pointer array. Length values are pointer-sized integers.
        Parameters:
        stack - the stack to use
        buffers - the buffers to store
        Returns:
        the pointer array address on the stack

      • apiArray

        public static long apiArray(MemoryStack stack,
                            APIUtil.Encoder encoder,
                            java.lang.CharSequence... strings)
        Encodes the specified strings with the specified APIUtil.Encoder and stores an array of pointers to the encoded data on the specified MemoryStack. The encoded strings include null-termination.
        Parameters:
        stack - the stack to use
        encoder - the encoder to use
        strings - the strings to encode
        Returns:
        the pointer array address on the stack

      • apiArrayi

        public static long apiArrayi(MemoryStack stack,
                             APIUtil.Encoder encoder,
                             java.lang.CharSequence... strings)
        Encodes the specified strings with the specified APIUtil.Encoder and stores an array of pointers to the encoded data on the specified MemoryStack. A second array that contains the string lengths is stored immediately after the pointer array. Length values are 4-byte integers.

        The encoded buffers must be freed with APIUtil.apiArrayFree(long, int).

        Parameters:
        stack - the stack to use
        encoder - the encoder to use
        strings - the strings to encode
        Returns:
        the pointer array address on the stack

      • apiArrayp

        public static long apiArrayp(MemoryStack stack,
                             APIUtil.Encoder encoder,
                             java.lang.CharSequence... strings)
        Encodes the specified strings with the specified APIUtil.Encoder and stores an array of pointers to the encoded data on the specified MemoryStack. A second array that contains the string lengths is stored immediately after the pointer array. Length values are pointer-sized integers.

        The encoded buffers must be freed with APIUtil.apiArrayFree(long, int).

        Parameters:
        stack - the stack to use
        encoder - the encoder to use
        strings - the strings to encode
        Returns:
        the pointer array address on the stack

      • apiArrayFree

        public static void apiArrayFree(long pointers,
                                int length)
        Frees the specified array of pointers.
        Parameters:
        pointers - the pointer array to free
        length - the pointer array length