Package icyllis.arc3d.engine

# Class Device

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

All Implemented Interfaces:
  `Engine`

Direct Known Subclasses:
  `GLDevice`, `VulkanDevice`

public abstract class Device extends Object implements Engine
The `Device` represents a logical GPU device and provides shared context info of the backend 3D API. A `Device` is created with an `ImmediateContext`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `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
  `protected final Caps`
  `mCaps`
  `protected final ShaderCompiler`
  `mCompiler`
  `protected boolean`
  `mDeviceIsLost`
  `protected boolean`
  `mOutOfMemoryEncountered`
  `protected final Device.Stats`
  `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`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Device(int backend, ContextOptions options, Caps caps)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `addFinishedCallback(FlushInfo.FinishedCallback callback)`
  `abstract boolean`
  `checkFence(long fence)`
  Checks a fence on client side to see if signalled.
  `abstract void`
  `checkFinishedCallbacks()`
  `final boolean`
  `checkOutOfMemory()`
  Checks if we detected an OOM from the underlying 3D API and if so returns true and resets the internal OOM state to false.
  `final @SharedPtr GpuRenderTarget`
  `createRenderTarget(int numColorTargets, Image[] colorTargets, Image[] resolveTargets, int[] mipLevels, Image depthStencilTarget, int surfaceFlags)`
  Deprecated.
  `abstract void`
  `deleteFence(long fence)`
  Deletes an existing fence that previously returned by `insertFence()`.
  `void`
  `disconnect(boolean cleanup)`
  Called by context when the underlying backend context is already or will be destroyed before `ImmediateContext`.
  `protected void`
  `freeGpuResources()`
  `int`
  `getBackend()`
  `Caps`
  `getCaps()`
  Gets the capabilities of the context.
  `BackendFormat`
  `getCompressedBackendFormat(int compressionType)`
  Retrieve the `BackendFormat` for a given `CompressionType`.
  `int`
  `getContextID()`
  `BackendFormat`
  `getDefaultBackendFormat(int colorType, boolean renderable)`
  Retrieve the default `BackendFormat` for a given `ColorType` and renderability.
  `final Thread`
  `getExecutingThread()`
  `GpuBufferPool`
  `getIndexPool()`
  Deprecated.
  `GpuBufferPool`
  `getInstancePool()`
  Deprecated.
  `final org.slf4j.Logger`
  `getLogger()`
  `int`
  `getMaxSurfaceSampleCount(int colorType)`
  Gets the maximum supported sample count for a color type.
  `final OpsRenderPass`
  `getOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)`
  Deprecated.
  `ContextOptions`
  `getOptions()`
  `final RendererProvider`
  `getRendererProvider()`
  `final ShaderCodeSource`
  `getShaderCodeSource()`
  `final ShaderCompiler`
  `getShaderCompiler()`
  Gets the compiler used for compiling AkSL into backend shader code.
  `final SharedResourceCache`
  `getSharedResourceCache()`
  `final Device.Stats`
  `getStats()`
  `GpuBufferPool`
  `getVertexPool()`
  Deprecated.
  `protected void`
  `handleDirtyContext(int state)`
  `int`
  `hashCode()`
  `abstract long`
  `insertFence()`
  Creates a new fence and inserts it into the graphics queue.
  `boolean`
  `isDeviceLost()`
  Returns true if GPU is gone.
  `final boolean`
  `isOnExecutingThread()`
  `boolean`
  `isValid()`
  `abstract ResourceProvider`
  `makeResourceProvider(Context context, long maxResourceBudget)`
  `final void`
  `markContextDirty(int state)`
  The engine object normally assumes that no outsider is setting state within the underlying 3D API's context/device/whatever.
  `protected abstract @SharedPtr GpuRenderTarget`
  `onCreateRenderTarget(int width, int height, int sampleCount, int numColorTargets, Image[] colorTargets, Image[] resolveTargets, int[] mipLevels, Image depthStencilTarget, int surfaceFlags)`
  Deprecated.
  `protected abstract OpsRenderPass`
  `onGetOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)`
  Deprecated.
  `protected void`
  `onResetContext(int resetBits)`
  Called when the 3D context state is unknown.
  `protected abstract void`
  `onResolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)`
  Deprecated.
  `abstract @SharedPtr GpuRenderTarget`
  `onWrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)`
  Deprecated.
  `protected @SharedPtr GpuRenderTarget`
  `onWrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)`
  Deprecated.
  `protected abstract @SharedPtr GpuRenderTarget`
  `onWrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)`
  Deprecated.
  `protected void`
  `purgeResourcesNotUsedSince(long timeMillis)`
  `void`
  `resolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)`
  Deprecated.
  `abstract void`
  `waitForQueue()`
  Blocks the current thread and waits for GPU to finish outstanding works.
  `@SharedPtr GpuRenderTarget`
  `wrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `wrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)`
  Deprecated.
  `@SharedPtr GpuRenderTarget`
  `wrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)`
  Deprecated.

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

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

- ## Field Details

  - ### mCaps

    protected final Caps mCaps

  - ### mCompiler

    protected final ShaderCompiler mCompiler

  - ### mStats

    protected final Device.Stats mStats

  - ### mOutOfMemoryEncountered

    protected volatile boolean mOutOfMemoryEncountered

  - ### mDeviceIsLost

    protected volatile boolean mDeviceIsLost

- ## Constructor Details

  - ### Device

    protected Device(int backend, ContextOptions options, Caps caps)

- ## Method Details

  - ### getLogger

    public final org.slf4j.Logger getLogger()

  - ### getExecutingThread

    public final Thread getExecutingThread()
    Returns:
      the command-executing thread

  - ### isOnExecutingThread

    public final boolean isOnExecutingThread()
    Returns:
      true if calling from the command-executing thread

  - ### getDefaultBackendFormat

    @Nullable public BackendFormat getDefaultBackendFormat(int colorType, boolean renderable)
    Retrieve the default `BackendFormat` for a given `ColorType` and renderability. It is guaranteed that this backend format will be the one used by the following `ColorType` and `SurfaceCharacterization.createBackendFormat(int, BackendFormat)`.

    The caller should check that the returned format is valid (nullability).

    Parameters:
      `colorType` - see `ImageDesc`
      `renderable` - true if the format will be used as color attachments

  - ### getCompressedBackendFormat

    @Nullable public BackendFormat getCompressedBackendFormat(int compressionType)
    Retrieve the `BackendFormat` for a given `CompressionType`. This is guaranteed to match the backend format used by the following createCompressedBackendTexture methods that take a `CompressionType`.

    The caller should check that the returned format is valid (nullability).

    Parameters:
      `compressionType` - see `ImageDesc`

  - ### getMaxSurfaceSampleCount

    public int getMaxSurfaceSampleCount(int colorType)
    Gets the maximum supported sample count for a color type. 1 is returned if only non-MSAA rendering is supported for the color type. 0 is returned if rendering to this color type is not supported at all.
    Parameters:
      `colorType` - see `ImageDesc`

  - ### isValid

    public boolean isValid()
    Returns:
      initialized or not, if `ImmediateContext` is created, it must be true

  - ### getBackend

    @Internal public int getBackend()

  - ### getOptions

    @Internal public ContextOptions getOptions()

  - ### getContextID

    @Internal public int getContextID()

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### getCaps

    public Caps getCaps()
    Gets the capabilities of the context.

  - ### getShaderCompiler

    public final ShaderCompiler getShaderCompiler()
    Gets the compiler used for compiling AkSL into backend shader code.

  - ### makeResourceProvider

    public abstract ResourceProvider makeResourceProvider(Context context, long maxResourceBudget)

  - ### getSharedResourceCache

    public final SharedResourceCache getSharedResourceCache()

  - ### getShaderCodeSource

    public final ShaderCodeSource getShaderCodeSource()

  - ### getRendererProvider

    public final RendererProvider getRendererProvider()

  - ### disconnect

    public void disconnect(boolean cleanup)
    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.

  - ### isDeviceLost

    public boolean isDeviceLost()
    Returns true if GPU is gone.

  - ### getStats

    public final Device.Stats getStats()

  - ### markContextDirty

    public final void markContextDirty(int state)
    The engine object normally assumes that no outsider is setting state within the underlying 3D API's context/device/whatever. This call informs the engine that the state was modified, and it shouldn't make assumptions about the state.

  - ### handleDirtyContext

    protected void handleDirtyContext(int state)

  - ### onResetContext

    protected void onResetContext(int resetBits)
    Called when the 3D context state is unknown. Subclass should emit any assumed 3D context state and dirty any state cache.

  - ### getVertexPool

    @Deprecated public GpuBufferPool getVertexPool()
    Deprecated.

  - ### getInstancePool

    @Deprecated public GpuBufferPool getInstancePool()
    Deprecated.

  - ### getIndexPool

    @Deprecated public GpuBufferPool getIndexPool()
    Deprecated.

  - ### freeGpuResources

    protected void freeGpuResources()

  - ### purgeResourcesNotUsedSince

    protected void purgeResourcesNotUsedSince(long timeMillis)

  - ### createRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget createRenderTarget(int numColorTargets, @Nullable Image[] colorTargets, @Nullable Image[] resolveTargets, @Nullable int[] mipLevels, @Nullable Image depthStencilTarget, int surfaceFlags)
    Deprecated.
    Overridden by backend-specific derived class to create objects.

    Image size and format support will have already been validated in base class before onCreateImage is called.

  - ### onCreateRenderTarget

    @Deprecated @OverrideOnly @Nullable @SharedPtr protected abstract @SharedPtr GpuRenderTarget onCreateRenderTarget(int width, int height, int sampleCount, int numColorTargets, @Nullable Image[] colorTargets, @Nullable Image[] resolveTargets, @Nullable int[] mipLevels, @Nullable Image depthStencilTarget, int surfaceFlags)
    Deprecated.

  - ### wrapRenderableBackendTexture

    @Deprecated @Nullable @SharedPtr public @SharedPtr GpuRenderTarget wrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)
    Deprecated.
    This makes the backend texture be renderable. If `sampleCount` is > 1 and the underlying API uses separate MSAA render buffers then a MSAA render buffer is created that resolves to the texture.

    Ownership specifies rules for external GPU resources imported into Engine. If false, Engine will assume the client will keep the resource alive and Engine will not free it. If true, Engine will assume ownership of the resource and free it.

    Parameters:
      `texture` - the backend texture must be single sample
    Returns:
      a non-cacheable render target, or null if failed

  - ### onWrapRenderableBackendTexture

    @Deprecated @Nullable @SharedPtr protected abstract @SharedPtr GpuRenderTarget onWrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)
    Deprecated.

  - ### wrapGLDefaultFramebuffer

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget wrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)
    Deprecated.

  - ### onWrapGLDefaultFramebuffer

    @Deprecated @OverrideOnly @Nullable @SharedPtr protected @SharedPtr GpuRenderTarget onWrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)
    Deprecated.

  - ### wrapBackendRenderTarget

    @Deprecated @Nullable @SharedPtr public @SharedPtr GpuRenderTarget wrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)
    Deprecated.

  - ### onWrapBackendRenderTarget

    @Deprecated @Nullable @SharedPtr public abstract @SharedPtr GpuRenderTarget onWrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)
    Deprecated.

  - ### getOpsRenderPass

    @Deprecated @Nullable public final OpsRenderPass getOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)
    Deprecated.
    Returns a `OpsRenderPass` which `OpsTasks` record draw commands to.
    Parameters:
      `writeView` - the render target to be rendered to
      `contentBounds` - the clipped content bounds of the render pass
      `colorOps` - the color load/store ops
      `stencilOps` - the stencil load/store ops
      `clearColor` - the color used to clear the color buffer
      `sampledTextures` - list of all textures to be sampled in the render pass (no refs)
      `pipelineFlags` - combination of flags of all pipelines to be used in the render pass
    Returns:
      a render pass used to record draw commands, or null if failed

  - ### onGetOpsRenderPass

    @Deprecated protected abstract OpsRenderPass onGetOpsRenderPass(ImageProxyView writeView, Rect2i contentBounds, byte colorOps, byte stencilOps, float[] clearColor, Set<SurfaceProxy> sampledTextures, int pipelineFlags)
    Deprecated.

  - ### resolveRenderTarget

    @Deprecated public void resolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)
    Deprecated.
    Resolves MSAA. The resolve rectangle must already be in the native destination space.

  - ### onResolveRenderTarget

    @Deprecated protected abstract void onResolveRenderTarget(GpuRenderTarget renderTarget, int resolveLeft, int resolveTop, int resolveRight, int resolveBottom)
    Deprecated.

  - ### insertFence

    public abstract long insertFence()
    Creates a new fence and inserts it into the graphics queue. Calls `deleteFence(long)` if the fence is no longer used.
    Returns:
      the handle to the fence, or null if failed

  - ### checkFence

    public abstract boolean checkFence(long fence)
    Checks a fence on client side to see if signalled. This method returns immediately.
    Parameters:
      `fence` - the handle to the fence
    Returns:
      true if signalled, false otherwise

  - ### deleteFence

    public abstract void deleteFence(long fence)
    Deletes an existing fence that previously returned by `insertFence()`.
    Parameters:
      `fence` - the handle to the fence, cannot be null

  - ### addFinishedCallback

    public abstract void addFinishedCallback(FlushInfo.FinishedCallback callback)

  - ### checkFinishedCallbacks

    public abstract void checkFinishedCallbacks()

  - ### waitForQueue

    public abstract void waitForQueue()
    Blocks the current thread and waits for GPU to finish outstanding works.

  - ### checkOutOfMemory

    public final boolean checkOutOfMemory()
    Checks if we detected an OOM from the underlying 3D API and if so returns true and resets the internal OOM state to false. Otherwise, returns false.