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 Description
      static class  APIUtil.APIVersion
      A data class for API versioning information.
      static interface  APIUtil.Encoder  

    • Field Summary

      Fields 
      Modifier and Type Field 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​(@Nullable
                          java.lang.CharSequence msg)
        Prints the specified message to the 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

      • apiFindLibrary

        public static java.lang.String apiFindLibrary​(java.lang.String start,
                                              java.lang.String name)

      • apiCreateLibrary

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

      • apiGetFunctionAddress

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

      • apiGetMappedBuffer

        @Nullable
public static java.nio.ByteBuffer apiGetMappedBuffer​(@Nullable
                                                     java.nio.ByteBuffer buffer,
                                                     long mappedAddress,
                                                     int capacity)

      • apiGetBytes

        public static long apiGetBytes​(int elements,
                               int elementShift)

      • apiCheckAllocation

        public static long apiCheckAllocation​(int elements,
                                      long bytes,
                                      long maxBytes)

      • 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,
                                                 @Nullable
                                                 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​(@Nullable
                                                                               java.util.function.BiPredicate<java.lang.reflect.Field,java.lang.Integer> filter,
                                                                               @Nullable
                                                                               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

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