Package icyllis.modernui.core

# Class Core

java.lang.Object
icyllis.modernui.core.Core

public final class Core extends Object
The core class for thread management and sub-system initializing, also provides utility methods of memory operations and thread scheduling.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `checkMainThread()`
  Ensures that the current thread is the main thread, otherwise a runtime exception will be thrown.
  `static void`
  `checkRenderThread()`
  Ensures that the current thread is the render thread, otherwise a runtime exception will be thrown.
  `static void`
  `checkUiThread()`
  Ensures that the current thread is the UI thread, otherwise a runtime exception will be thrown.
  `static void`
  `executeOnMainThread(Runnable r)`
  This should be rarely used.
  `static void`
  `executeOnUiThread(Runnable r)`
  This should be rarely used.
  `static void`
  `flushMainCalls()`
  Flush main thread calls if the main thread is not a looper thread.
  `static Handler`
  `getMainHandlerAsync()`
  Returns a shared main thread handler.
  `static Thread`
  `getMainThread()`
  `static Executor`
  `getMainThreadExecutor()`
  `static Thread`
  `getRenderThread()`
  `static Handler`
  `getUiHandler()`
  Returns the shared `Handler` that created on UI thread, if initialized.
  `static Handler`
  `getUiHandlerAsync()`
  Returns the shared `Handler` that created on UI thread, if initialized.
  `static Thread`
  `getUiThread()`
  `static Executor`
  `getUiThreadExecutor()`
  `static void`
  `glDebugMessage(int source, int type, int id, int severity, int length, long message, long userParam)`
  `static void`
  `glSetupDebugCallback()`
  `static void`
  `glShowCapsErrorDialog()`
  Show a dialog that lists unsupported extensions after initialized.
  `static void`
  `initialize()`
  Initializes the GLFW and the main thread.
  `static boolean`
  `initOpenGL()`
  `static boolean`
  `initOpenGL(ContextOptions options)`
  Initializes OpenGL pipeline and the render thread.
  `static Looper`
  `initUiThread()`
  Initializes UI thread and its event loop.
  `static boolean`
  `initVulkan()`
  `static boolean`
  `initVulkan(ContextOptions options)`
  Initializes Vulkan pipeline and the render thread.
  `static boolean`
  `isOnMainThread()`
  `static boolean`
  `isOnRenderThread()`
  `static boolean`
  `isOnUiThread()`
  `static boolean`
  `openURI(String uri)`
  Launches the associated application to open the URI.
  `static boolean`
  `openURI(URI uri)`
  Launches the associated application to open the URI.
  `static ImmediateContext`
  `peekImmediateContext()`
  `static RecordingContext`
  `peekUiRecordingContext()`
  `static void`
  `postOnMainThread(Runnable r)`
  Post an async operation that will be executed on main thread.
  `static void`
  `postOnUiThread(Runnable r)`
  Post an async operation that will be executed on main thread.
  `static ByteBuffer`
  `readIntoNativeBuffer(InputStream stream)`
  Allocates native memory and read buffered resource.
  `static ByteBuffer`
  `readIntoNativeBuffer(ReadableByteChannel channel)`
  Allocates native memory and read buffered resource.
  `static Cleaner.Cleanable`
  `registerCleanup(Object target, Runnable action)`
  Registers a target and a cleaning action to run when the target becomes phantom reachable.
  `static ImmediateContext`
  `requireImmediateContext()`
  `static RecordingContext`
  `requireUiRecordingContext()`
  `static void`
  `terminate()`
  Terminates the GLFW.
  `static long`
  `timeMillis()`
  Returns the current value of GLFW's highest-resolution monotonic time source, in milliseconds.
  `static long`
  `timeNanos()`
  Returns the current value of GLFW's highest-resolution monotonic time source, in nanoseconds.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### registerCleanup

    @NonNull public static Cleaner.Cleanable registerCleanup(@NonNull Object target, @NonNull Runnable action)
    Registers a target and a cleaning action to run when the target becomes phantom reachable. The action object should never hold any reference to the target object.
    Parameters:
      `target` - the target to monitor
      `action` - a `Runnable` to invoke when the target becomes phantom reachable
    Returns:
      a `Cleanable` instance representing the registry entry

  - ### initialize

    @MainThread public static void initialize()
    Initializes the GLFW and the main thread.

    If the GLFW has already been initialized, this method just specifies the current thread as the main thread. If both are done, it will cause an assertion error.

  - ### terminate

    @MainThread public static void terminate()
    Terminates the GLFW.

  - ### checkMainThread

    public static void checkMainThread()
    Ensures that the current thread is the main thread, otherwise a runtime exception will be thrown.

  - ### getMainThread

    public static Thread getMainThread()
    Returns:
      the main thread if initialized, or null

  - ### isOnMainThread

    public static boolean isOnMainThread()
    Returns:
      whether the current thread is the main thread

  - ### initOpenGL

    @RenderThread public static boolean initOpenGL()

  - ### initOpenGL

    @RenderThread public static boolean initOpenGL(@NonNull ContextOptions options)
    Initializes OpenGL pipeline and the render thread.

    Before calling this method, it is necessary to ensure that the GL library is loaded and that the current thread has an OpenGL context for a certain platform window.

    Returns:
      true if successful

  - ### glSetupDebugCallback

    @RenderThread public static void glSetupDebugCallback()

  - ### glDebugMessage

    public static void glDebugMessage(int source, int type, int id, int severity, int length, long message, long userParam)

  - ### glShowCapsErrorDialog

    @RenderThread public static void glShowCapsErrorDialog()
    Show a dialog that lists unsupported extensions after initialized.

  - ### initVulkan

    @RenderThread public static boolean initVulkan()

  - ### initVulkan

    @RenderThread public static boolean initVulkan(@NonNull ContextOptions options)
    Initializes Vulkan pipeline and the render thread.

    Before calling this method, it is necessary to ensure that the VK library is loaded and that Vulkan is available for the current platform.

    Returns:
      true if successful

  - ### checkRenderThread

    public static void checkRenderThread()
    Ensures that the current thread is the render thread, otherwise a runtime exception will be thrown.

  - ### getRenderThread

    public static Thread getRenderThread()
    Returns:
      the render thread if initialized, or null

  - ### isOnRenderThread

    public static boolean isOnRenderThread()
    Returns:
      whether the current thread is the render thread

  - ### requireImmediateContext

    @NonNull @RenderThread public static ImmediateContext requireImmediateContext()

  - ### peekImmediateContext

    public static ImmediateContext peekImmediateContext()

  - ### getMainHandlerAsync

    @NonNull public static Handler getMainHandlerAsync()
    Returns a shared main thread handler. The handler is not always available. Consider `executeOnMainThread(Runnable)` instead.
    Returns:
      async main handler

  - ### postOnMainThread

    public static void postOnMainThread(@NonNull Runnable r)
    Post an async operation that will be executed on main thread.
    Parameters:
      `r` - the runnable

  - ### executeOnMainThread

    public static void executeOnMainThread(@NonNull Runnable r)
    This should be rarely used. Only when the render thread and the main thread are the same thread, and you need to call some methods that must be called on the main thread.
    Parameters:
      `r` - the runnable

  - ### getMainThreadExecutor

    @NonNull public static Executor getMainThreadExecutor()

  - ### flushMainCalls

    public static void flushMainCalls()
    Flush main thread calls if the main thread is not a looper thread.

  - ### initUiThread

    @NonNull @UiThread public static Looper initUiThread()
    Initializes UI thread and its event loop.

    UI thread can be the main thread iff the main thread is a looper thread.

    Returns:
      the event loop

  - ### checkUiThread

    public static void checkUiThread()
    Ensures that the current thread is the UI thread, otherwise a runtime exception will be thrown.

  - ### getUiThread

    public static Thread getUiThread()
    Returns:
      the UI thread if initialized, or null

  - ### isOnUiThread

    public static boolean isOnUiThread()
    Returns:
      whether the current thread is the UI thread

  - ### requireUiRecordingContext

    @NonNull @UiThread public static RecordingContext requireUiRecordingContext()

  - ### peekUiRecordingContext

    public static RecordingContext peekUiRecordingContext()

  - ### getUiHandler

    public static Handler getUiHandler()
    Returns the shared `Handler` that created on UI thread, if initialized. It can be used for thread scheduling of callback operations.
    Returns:
      the shared UI handler
    See Also:
      - `getUiHandlerAsync()`

  - ### getUiHandlerAsync

    public static Handler getUiHandlerAsync()
    Returns the shared `Handler` that created on UI thread, if initialized. It can be used for thread scheduling of callback operations.

    Differently from `getUiHandler()`, this is an async version. Messages sent to an async handler are guaranteed to be ordered with respect to one another, but not necessarily with respect to messages from other Handlers.

    Returns:
      the shared UI handler
    See Also:
      - `getUiHandler()`

  - ### postOnUiThread

    public static void postOnUiThread(@NonNull Runnable r)
    Post an async operation that will be executed on main thread.
    Parameters:
      `r` - the runnable

  - ### executeOnUiThread

    public static void executeOnUiThread(@NonNull Runnable r)
    This should be rarely used. Only when the render thread and the main thread are the same thread, and you need to call some methods that must be called on the main thread.
    Parameters:
      `r` - the runnable

  - ### getUiThreadExecutor

    @NonNull public static Executor getUiThreadExecutor()

  - ### timeNanos

    public static long timeNanos()
    Returns the current value of GLFW's highest-resolution monotonic time source, in nanoseconds. The resolution of the timer is system dependent, but is usually on the order of a few micro- or nanoseconds. The timer measures time elapsed since GLFW was initialized.

    Calling this method is faster than `System.nanoTime()`. This time base is used in all input events and frame events, but not in high-level API (such as animations).

    Returns:
      current time in nanoseconds

  - ### timeMillis

    public static long timeMillis()
    Returns the current value of GLFW's highest-resolution monotonic time source, in milliseconds. The resolution of the timer is system dependent, but is usually on the order of a few micro- or nanoseconds. The timer measures time elapsed since GLFW was initialized.

    You should NOT use this time base in high-level API (such as animations).

    Returns:
      current time in milliseconds

  - ### readIntoNativeBuffer

    @NonNull public static ByteBuffer readIntoNativeBuffer(@NonNull ReadableByteChannel channel) throws IOException
    Allocates native memory and read buffered resource. The memory MUST be manually freed by `MemoryUtil.memFree(Buffer)`. This method can read up to 2GB. This method does NOT close the channel.
    Parameters:
      `channel` - where to read input from
    Returns:
      the native pointer to `unsigned char *data`
    Throws:
      `IOException` - some errors occurred while reading

  - ### readIntoNativeBuffer

    @NonNull public static ByteBuffer readIntoNativeBuffer(@NonNull InputStream stream) throws IOException
    Allocates native memory and read buffered resource. The memory MUST be manually freed by `MemoryUtil.memFree(Buffer)`. This method can read up to 2GB. This method does NOT close the stream.
    Parameters:
      `stream` - where to read input from
    Returns:
      the native pointer to `unsigned char *data`
    Throws:
      `IOException` - some errors occurred while reading

  - ### openURI

    public static boolean openURI(@NonNull URI uri)
    Launches the associated application to open the URI.
    Returns:
      true on success, false on failure

  - ### openURI

    public static boolean openURI(@NonNull String uri)
    Launches the associated application to open the URI.
    Returns:
      true on success, false on failure