Package icyllis.arc3d.opengl

# Class GLDevice

java.lang.Object
icyllis.arc3d.engine.Device
icyllis.arc3d.opengl.GLDevice

All Implemented Interfaces:
  `Engine`

public final class GLDevice extends Device
The OpenGL device.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class icyllis.arc3d.engine.Device

  `Device.Stats`

  ## Nested classes/interfaces inherited from interface icyllis.arc3d.engine.Engine

  `Engine.BackendApi, Engine.BudgetType, Engine.BufferUsageFlags, Engine.DepthStencilFlags, Engine.GLBackendState, Engine.ImageCreateFlags, Engine.ImageType, Engine.IndexType, Engine.IOType, Engine.LoadOp, Engine.LoadStoreOps, Engine.PrimitiveType, Engine.ShaderFlags, Engine.StoreOp, Engine.SurfaceOrigin, Engine.VertexAttribType`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_FRAMEBUFFER`
  The reserved framebuffer that used for swapping buffers with window.
  `static final int`
  `DEFAULT_TEXTURE`
  `static final int`
  `DEFAULT_VERTEX_ARRAY`
  The default vertex array compared to custom vertex array objects.

  ### Fields inherited from class icyllis.arc3d.engine.Device

  `mCompiler, mDeviceIsLost, mOutOfMemoryEncountered, mStats`

  ### Fields inherited from interface icyllis.arc3d.engine.Engine

  `CLAMP_TYPE_AUTO, CLAMP_TYPE_MANUAL, CLAMP_TYPE_NONE, COLOR_ENCODING_FLOAT, COLOR_ENCODING_UNORM, COLOR_ENCODING_UNORM_PACK16, COLOR_ENCODING_UNORM_PACK32, COLOR_ENCODING_UNORM_SRGB, INVALID_RESOURCE_HANDLE, LAST_MASK_FORMAT, MASK_FORMAT_A565, MASK_FORMAT_A8, MASK_FORMAT_ARGB, MASK_FORMAT_COUNT, Ownership_Borrowed, Ownership_Owned`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addFinishedCallback(FlushInfo.FinishedCallback callback)`
  `boolean`
  `checkFence(long fence)`
  Checks a fence on client side to see if signalled.
  `void`
  `checkFinishedCallbacks()`
  `void`
  `clearErrors()`
  Call `getError()` until there are no errors.
  `boolean`
  `copyImage(Image src, int srcL, int srcT, int srcR, int srcB, Image dst, int dstL, int dstT, int dstR, int dstB, int filter)`
  Perform a surface-to-surface copy, with the specified regions.
  `boolean`
  `copyImage(Image src, int srcX, int srcY, Image dst, int dstX, int dstY, int width, int height)`
  Special case of `copyImage(icyllis.arc3d.opengl.GLImage, int, int, int, int, icyllis.arc3d.opengl.GLImage, int, int, int)` that has same dimensions.
  `boolean`
  `copyImage(@RawPtr GLImage src, int srcL, int srcT, int srcR, int srcB, @RawPtr GLImage dst, int dstX, int dstY, int level)`
  Perform an image-to-image copy, with the specified regions.
  `void`
  `deleteFence(long fence)`
  Deletes an existing fence that previously returned by `Device.insertFence()`.
  `void`
  `disconnect(boolean cleanup)`
  Called by context when the underlying backend context is already or will be destroyed before `ImmediateContext`.
  `void`
  `executeRenderCall(Consumer<GLDevice> renderCall)`
  OpenGL only method.
  `@SharedPtr GLFramebuffer`
  `findOrCreateFramebuffer(FramebufferDesc framebufferDesc)`
  `@SharedPtr GLVertexArray`
  `findOrCreateVertexArray(VertexInputLayout inputLayout, String label)`
  `void`
  `flushRenderCalls()`
  `protected void`
  `freeGpuResources()`
  `boolean`
  `generateMipmaps(@RawPtr Image image)`
  Uses the base level of the image to compute the contents of the other mipmap levels.
  `GLCaps`
  `getCaps()`
  Gets the capabilities of the context.
  `int`
  `getError()`
  Polls an error code and sets the OOM and context lost state.
  `GLInterface`
  `getGL()`
  `long`
  `insertFence()`
  Creates a new fence and inserts it into the graphics queue.
  `static GLDevice`
  `make(ContextOptions options, Object capabilities)`
  Create a `GLDevice` with OpenGL context current in the current thread.
  `GLResourceProvider`
  `makeResourceProvider(Context context, long maxResourceBudget)`
  `protected GpuRenderTarget`
  `onCreateRenderTarget(int width, int height, int sampleCount, int numColorTargets, Image[] colorTargets, Image[] resolveTargets, int[] mipLevels, Image depthStencilTarget, int surfaceFlags)`
  `protected OpsRenderPass`
  `onGetOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)`
  `protected void`
  `onResetContext(int resetBits)`
  Called when the 3D context state is unknown.
  `protected void`
  `onResolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)`
  `GLRenderTarget`
  `onWrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)`
  `protected GpuRenderTarget`
  `onWrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)`
  `protected GLRenderTarget`
  `onWrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)`
  `protected void`
  `purgeResourcesNotUsedSince(long timeMillis)`
  `void`
  `purgeStaleResources()`
  `void`
  `recordRenderCall(Consumer<GLDevice> renderCall)`
  `void`
  `waitForQueue()`
  Blocks the current thread and waits for GPU to finish outstanding works.
  `boolean`
  `writePixels(@RawPtr Image texture, int x, int y, int width, int height, int dstColorType, int srcColorType, int rowBytes, long pixels)`
  Updates the pixels in a rectangle of an image.

  ### Methods inherited from class icyllis.arc3d.engine.Device

  `checkOutOfMemory, createRenderTarget, getBackend, getCompressedBackendFormat, getContextID, getDefaultBackendFormat, getExecutingThread, getIndexPool, getInstancePool, getLogger, getMaxSurfaceSampleCount, getOpsRenderPass, getOptions, getRendererProvider, getShaderCodeSource, getShaderCompiler, getSharedResourceCache, getStats, getVertexPool, handleDirtyContext, hashCode, isDeviceLost, isOnExecutingThread, isValid, markContextDirty, resolveRenderTarget, wrapBackendRenderTarget, wrapGLDefaultFramebuffer, wrapRenderableBackendTexture`

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

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

- ## Field Details

  - ### DEFAULT_FRAMEBUFFER

    public static final int DEFAULT_FRAMEBUFFER
    The reserved framebuffer that used for swapping buffers with window.
    See Also:
      - Constant Field Values

  - ### DEFAULT_VERTEX_ARRAY

    public static final int DEFAULT_VERTEX_ARRAY
    The default vertex array compared to custom vertex array objects.
    See Also:
      - Constant Field Values

  - ### DEFAULT_TEXTURE

    public static final int DEFAULT_TEXTURE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### make

    @Nullable public static GLDevice make(ContextOptions options, Object capabilities)
    Create a `GLDevice` with OpenGL context current in the current thread.
    Parameters:
      `options` - the context options
    Returns:
      the engine or null if failed to create

  - ### executeRenderCall

    public void executeRenderCall(Consumer<GLDevice> renderCall)
    OpenGL only method. Execute the GL command as soon as possible.

  - ### recordRenderCall

    public void recordRenderCall(Consumer<GLDevice> renderCall)

  - ### flushRenderCalls

    public void flushRenderCalls()

  - ### getCaps

    public GLCaps getCaps()
    Description copied from class: `Device`
    Gets the capabilities of the context.
    Overrides:
      `getCaps` in class `Device`

  - ### getGL

    public GLInterface getGL()

  - ### disconnect

    public void disconnect(boolean cleanup)
    Description copied from class: `Device`
    Called by context when the underlying backend context is already or will be destroyed before `ImmediateContext`.

    If cleanup is true, free allocated resources (other than `ResourceCache`) before returning and ensure no backend 3D API calls will be made after this method returns. Otherwise, no cleanup should be attempted, immediately cease making backend API calls.

    Overrides:
      `disconnect` in class `Device`

  - ### makeResourceProvider

    public GLResourceProvider makeResourceProvider(Context context, long maxResourceBudget)
    Specified by:
      `makeResourceProvider` in class `Device`

  - ### onResetContext

    protected void onResetContext(int resetBits)
    Description copied from class: `Device`
    Called when the 3D context state is unknown. Subclass should emit any assumed 3D context state and dirty any state cache.
    Overrides:
      `onResetContext` in class `Device`

  - ### clearErrors

    public void clearErrors()
    Call `getError()` until there are no errors.

  - ### getError

    public int getError()
    Polls an error code and sets the OOM and context lost state.

  - ### freeGpuResources

    protected void freeGpuResources()
    Overrides:
      `freeGpuResources` in class `Device`

  - ### purgeResourcesNotUsedSince

    protected void purgeResourcesNotUsedSince(long timeMillis)
    Overrides:
      `purgeResourcesNotUsedSince` in class `Device`

  - ### purgeStaleResources

    public void purgeStaleResources()

  - ### findOrCreateFramebuffer

    @Nullable @SharedPtr public @SharedPtr GLFramebuffer findOrCreateFramebuffer(@Nonnull FramebufferDesc framebufferDesc)

  - ### findOrCreateVertexArray

    @Nullable @SharedPtr public @SharedPtr GLVertexArray findOrCreateVertexArray(@Nonnull VertexInputLayout inputLayout, String label)

  - ### onCreateRenderTarget

    @Nullable protected GpuRenderTarget onCreateRenderTarget(int width, int height, int sampleCount, int numColorTargets, @Nullable Image[] colorTargets, @Nullable Image[] resolveTargets, @Nullable int[] mipLevels, @Nullable Image depthStencilTarget, int surfaceFlags)
    Specified by:
      `onCreateRenderTarget` in class `Device`

  - ### onWrapRenderableBackendTexture

    @Nullable protected GLRenderTarget onWrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)
    Specified by:
      `onWrapRenderableBackendTexture` in class `Device`

  - ### onWrapGLDefaultFramebuffer

    protected GpuRenderTarget onWrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)
    Overrides:
      `onWrapGLDefaultFramebuffer` in class `Device`

  - ### onWrapBackendRenderTarget

    @Nullable public GLRenderTarget onWrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)
    Specified by:
      `onWrapBackendRenderTarget` in class `Device`

  - ### writePixels

    public boolean writePixels(@RawPtr @RawPtr Image texture, int x, int y, int width, int height, int dstColorType, int srcColorType, int rowBytes, long pixels)
    Updates the pixels in a rectangle of an image. No sRGB/linear conversions are performed. The write operation can fail because of the surface doesn't support writing (e.g. read only), the color type is not allowed for the format of the texture or if the rectangle written is not contained in the texture.
    Parameters:
      `texture` - the image to write to
      `dstColorType` - the color type for this use of the surface
      `srcColorType` - the color type of the source data
      `rowBytes` - the row bytes, must be a multiple of srcColorType's bytes-per-pixel.
      `pixels` - the pointer to the texel data for base level image
    Returns:
      true if succeeded, false if not

  - ### generateMipmaps

    public boolean generateMipmaps(@RawPtr @RawPtr Image image)
    Uses the base level of the image to compute the contents of the other mipmap levels.
    Returns:
      success or not

  - ### copyImage

    public boolean copyImage(@RawPtr @RawPtr GLImage src, int srcL, int srcT, int srcR, int srcB, @RawPtr @RawPtr GLImage dst, int dstX, int dstY, int level)
    Perform an image-to-image copy, with the specified regions. Scaling is not allowed.

    If their dimensions are same and formats are compatible, then this method will attempt to perform copy. Otherwise, this method will attempt to perform blit, which may include format conversion.

    Only mipmap level level of 2D images will be copied, without any multisampled buffer and depth/stencil buffer.

    Returns:
      success or not

  - ### copyImage

    public boolean copyImage(Image src, int srcX, int srcY, Image dst, int dstX, int dstY, int width, int height)
    Special case of `copyImage(icyllis.arc3d.opengl.GLImage, int, int, int, int, icyllis.arc3d.opengl.GLImage, int, int, int)` that has same dimensions.

  - ### copyImage

    public boolean copyImage(Image src, int srcL, int srcT, int srcR, int srcB, Image dst, int dstL, int dstT, int dstR, int dstB, int filter)
    Perform a surface-to-surface copy, with the specified regions.

    If their dimensions are same and formats are compatible, then this method will attempt to perform copy. Otherwise, this method will attempt to perform blit, which may include resampling and format conversion. filter can be one of `SamplerDesc.FILTER_NEAREST` and `SamplerDesc.FILTER_LINEAR`.

    Only mipmap level 0 of 2D images will be copied, without any multisampled buffer and depth/stencil buffer.

    Returns:
      success or not

  - ### onGetOpsRenderPass

    protected OpsRenderPass onGetOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)
    Specified by:
      `onGetOpsRenderPass` in class `Device`

  - ### onResolveRenderTarget

    protected void onResolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)
    Specified by:
      `onResolveRenderTarget` in class `Device`

  - ### insertFence

    public long insertFence()
    Description copied from class: `Device`
    Creates a new fence and inserts it into the graphics queue. Calls `Device.deleteFence(long)` if the fence is no longer used.
    Specified by:
      `insertFence` in class `Device`
    Returns:
      the handle to the fence, or null if failed

  - ### checkFence

    public boolean checkFence(long fence)
    Description copied from class: `Device`
    Checks a fence on client side to see if signalled. This method returns immediately.
    Specified by:
      `checkFence` in class `Device`
    Parameters:
      `fence` - the handle to the fence
    Returns:
      true if signalled, false otherwise

  - ### deleteFence

    public void deleteFence(long fence)
    Description copied from class: `Device`
    Deletes an existing fence that previously returned by `Device.insertFence()`.
    Specified by:
      `deleteFence` in class `Device`
    Parameters:
      `fence` - the handle to the fence, cannot be null

  - ### addFinishedCallback

    public void addFinishedCallback(FlushInfo.FinishedCallback callback)
    Specified by:
      `addFinishedCallback` in class `Device`

  - ### checkFinishedCallbacks

    public void checkFinishedCallbacks()
    Specified by:
      `checkFinishedCallbacks` in class `Device`

  - ### waitForQueue

    public void waitForQueue()
    Description copied from class: `Device`
    Blocks the current thread and waits for GPU to finish outstanding works.
    Specified by:
      `waitForQueue` in class `Device`