Package icyllis.arc3d.engine

# Class CommandBuffer

java.lang.Object
icyllis.arc3d.engine.CommandBuffer

Direct Known Subclasses:
  `GLCommandBuffer`, `VulkanCommandBuffer`

public abstract class CommandBuffer extends Object
Backend-specific command buffer, executing thread only.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CommandBuffer()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected abstract void`
  `begin()`
  `abstract boolean`
  `beginRenderPass(RenderPassDesc renderPassDesc, FramebufferDesc framebufferDesc, Rect2ic renderPassBounds, float[] clearColors, float clearDepth, int clearStencil)`
  Begin render pass.
  `abstract boolean`
  `bindGraphicsPipeline(@RawPtr GraphicsPipeline graphicsPipeline)`
  Bind graphics pipeline.
  `abstract void`
  `bindIndexBuffer(int indexType, @RawPtr Buffer buffer, long offset)`
  Render pass scope, caller must track the buffer.
  `abstract void`
  `bindTextureSampler(int binding, @RawPtr Image texture, @RawPtr Sampler sampler, short swizzle)`
  Bind texture view and sampler to the same binding point (combined image sampler).
  `abstract void`
  `bindUniformBuffer(int binding, @RawPtr Buffer buffer, long offset, long size)`
  Render pass scope, caller must track the buffer.
  `abstract void`
  `bindVertexBuffer(int binding, @RawPtr Buffer buffer, long offset)`
  Render pass scope, caller must track the buffer.
  `protected final void`
  `callFinishedCallbacks(boolean success)`
  `protected abstract boolean`
  `checkFinishedAndReset()`
  `final boolean`
  `copyBuffer(@RawPtr Buffer srcBuffer, @RawPtr Buffer dstBuffer, long srcOffset, long dstOffset, long size)`
  Performs a buffer-to-buffer copy.
  `final boolean`
  `copyBufferToImage(@RawPtr Buffer srcBuffer, @RawPtr Image dstImage, int srcColorType, int dstColorType, BufferImageCopyData[] copyData)`
  Performs a buffer-to-image copy.
  `final boolean`
  `copyImage(@RawPtr Image srcImage, int srcL, int srcT, int srcR, int srcB, @RawPtr Image dstImage, int dstX, int dstY, int mipLevel)`
  Perform an image-to-image copy, with the specified regions.
  `abstract void`
  `draw(int vertexCount, int baseVertex)`
  Records a non-indexed draw to current command buffer.
  `abstract void`
  `drawIndexed(int indexCount, int baseIndex, int baseVertex)`
  Records an indexed draw to current command buffer.
  `abstract void`
  `drawIndexedInstanced(int indexCount, int baseIndex, int instanceCount, int baseInstance, int baseVertex)`
  Records an indexed draw to current command buffer.
  `abstract void`
  `drawInstanced(int instanceCount, int baseInstance, int vertexCount, int baseVertex)`
  Records a non-indexed draw to current command buffer.
  `abstract void`
  `endRenderPass()`
  End the current render pass.
  `protected abstract boolean`
  `onCopyBuffer(@RawPtr Buffer srcBuffer, @RawPtr Buffer dstBuffer, long srcOffset, long dstOffset, long size)`
  `protected abstract boolean`
  `onCopyBufferToImage(@RawPtr Buffer srcBuffer, @RawPtr Image dstImage, int srcColorType, int dstColorType, BufferImageCopyData[] copyData)`
  `protected abstract boolean`
  `onCopyImage(@RawPtr Image srcImage, int srcL, int srcT, int srcR, int srcB, @RawPtr Image dstImage, int dstX, int dstY, int mipLevel)`
  `protected final void`
  `releaseResources()`
  `abstract void`
  `setScissor(int x, int y, int width, int height)`
  Set scissor, must be called after `beginRenderPass(icyllis.arc3d.engine.RenderPassDesc, icyllis.arc3d.engine.FramebufferDesc, icyllis.arc3d.core.Rect2ic, float[], float, int)`.
  `abstract void`
  `setViewport(int x, int y, int width, int height)`
  Set viewport, must be called after `beginRenderPass(icyllis.arc3d.engine.RenderPassDesc, icyllis.arc3d.engine.FramebufferDesc, icyllis.arc3d.core.Rect2ic, float[], float, int)`.
  `protected abstract boolean`
  `submit(QueueManager queueManager)`
  `final void`
  `trackCommandBufferResource(@SharedPtr Resource resource)`
  Takes a CommandBuffer ref on the Resource that will be released when the command buffer has finished execution.
  `final void`
  `trackResource(@SharedPtr ManagedResource resource)`
  Takes a ref on the ManagedResource that will be released when the command buffer has finished execution.
  `final void`
  `trackResource(@SharedPtr Resource resource)`
  Takes a Usage ref on the Resource that will be released when the command buffer has finished execution.
  `protected abstract void`
  `waitUntilFinished()`
  Blocks the current thread and waits for GPU to finish outstanding works.

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

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

- ## Constructor Details

  - ### CommandBuffer

    public CommandBuffer()

- ## Method Details

  - ### beginRenderPass

    public abstract boolean beginRenderPass(RenderPassDesc renderPassDesc, FramebufferDesc framebufferDesc, Rect2ic renderPassBounds, float[] clearColors, float clearDepth, int clearStencil)
    Begin render pass. If successful, `endRenderPass()` must be called.
    Parameters:
      `renderPassDesc` - descriptor to create a render pass
      `framebufferDesc` - descriptor to create a framebuffer
      `renderPassBounds` - content bounds of this render pass
      `clearColors` - clear color for each color attachment
      `clearDepth` - clear depth
      `clearStencil` - clear stencil (unsigned)
    Returns:
      success or not

  - ### setViewport

    public abstract void setViewport(int x, int y, int width, int height)
    Set viewport, must be called after `beginRenderPass(icyllis.arc3d.engine.RenderPassDesc, icyllis.arc3d.engine.FramebufferDesc, icyllis.arc3d.core.Rect2ic, float[], float, int)`.

  - ### setScissor

    public abstract void setScissor(int x, int y, int width, int height)
    Set scissor, must be called after `beginRenderPass(icyllis.arc3d.engine.RenderPassDesc, icyllis.arc3d.engine.FramebufferDesc, icyllis.arc3d.core.Rect2ic, float[], float, int)`.

  - ### bindGraphicsPipeline

    public abstract boolean bindGraphicsPipeline(@RawPtr @RawPtr GraphicsPipeline graphicsPipeline)
    Bind graphics pipeline. Due to async compiling, it may fail. Render pass scope, caller must track the pipeline.
    Parameters:
      `graphicsPipeline` - the pipeline object
    Returns:
      success or not

  - ### bindIndexBuffer

    public abstract void bindIndexBuffer(int indexType, @RawPtr @RawPtr Buffer buffer, long offset)
    Render pass scope, caller must track the buffer.
    Parameters:
      `indexType` - see `Engine.IndexType`

  - ### bindVertexBuffer

    public abstract void bindVertexBuffer(int binding, @RawPtr @RawPtr Buffer buffer, long offset)
    Render pass scope, caller must track the buffer.

  - ### bindUniformBuffer

    public abstract void bindUniformBuffer(int binding, @RawPtr @RawPtr Buffer buffer, long offset, long size)
    Render pass scope, caller must track the buffer.

  - ### bindTextureSampler

    public abstract void bindTextureSampler(int binding, @RawPtr @RawPtr Image texture, @RawPtr @RawPtr Sampler sampler, short swizzle)
    Bind texture view and sampler to the same binding point (combined image sampler). Render pass scope, caller must track the image and sampler.
    Parameters:
      `binding` - the binding index
      `texture` - the texture image
      `sampler` - the sampler state
      `swizzle` - the swizzle of the texture view for shader read, see `Swizzle`

  - ### draw

    public abstract void draw(int vertexCount, int baseVertex)
    Records a non-indexed draw to current command buffer. Render pass scope.
    Parameters:
      `vertexCount` - the number of vertices to draw
      `baseVertex` - the index of the first vertex to draw

  - ### drawIndexed

    public abstract void drawIndexed(int indexCount, int baseIndex, int baseVertex)
    Records an indexed draw to current command buffer. For OpenGL ES, if base vertex is unavailable, gl_VertexID always begins at 0. Render pass scope.
    Parameters:
      `indexCount` - the number of vertices to draw
      `baseIndex` - the base index within the index buffer
      `baseVertex` - the value added to the vertex index before indexing into the vertex buffer

  - ### drawInstanced

    public abstract void drawInstanced(int instanceCount, int baseInstance, int vertexCount, int baseVertex)
    Records a non-indexed draw to current command buffer. For OpenGL, regardless of the baseInstance value, gl_InstanceID always begins at 0. Render pass scope.
    Parameters:
      `instanceCount` - the number of instances to draw
      `baseInstance` - the instance ID of the first instance to draw
      `vertexCount` - the number of vertices to draw
      `baseVertex` - the index of the first vertex to draw

  - ### drawIndexedInstanced

    public abstract void drawIndexedInstanced(int indexCount, int baseIndex, int instanceCount, int baseInstance, int baseVertex)
    Records an indexed draw to current command buffer. For OpenGL ES, if base vertex is unavailable, gl_VertexID always begins at 0. For OpenGL, regardless of the baseInstance value, gl_InstanceID always begins at 0. Render pass scope.
    Parameters:
      `indexCount` - the number of vertices to draw
      `baseIndex` - the base index within the index buffer
      `instanceCount` - the number of instances to draw
      `baseInstance` - the instance ID of the first instance to draw
      `baseVertex` - the value added to the vertex index before indexing into the vertex buffer

  - ### endRenderPass

    public abstract void endRenderPass()
    End the current render pass.

  - ### copyBuffer

    public final boolean copyBuffer(@RawPtr @RawPtr Buffer srcBuffer, @RawPtr @RawPtr Buffer dstBuffer, long srcOffset, long dstOffset, long size)
    Performs a buffer-to-buffer copy.

    Can only be used outside render passes.

    The caller must track resources if success.

  - ### onCopyBuffer

    protected abstract boolean onCopyBuffer(@RawPtr @RawPtr Buffer srcBuffer, @RawPtr @RawPtr Buffer dstBuffer, long srcOffset, long dstOffset, long size)

  - ### copyBufferToImage

    public final boolean copyBufferToImage(@RawPtr @RawPtr Buffer srcBuffer, @RawPtr @RawPtr Image dstImage, int srcColorType, int dstColorType, BufferImageCopyData[] copyData)
    Performs a buffer-to-image copy.

    Can only be used outside render passes.

    The caller must track resources if success.

  - ### onCopyBufferToImage

    protected abstract boolean onCopyBufferToImage(@RawPtr @RawPtr Buffer srcBuffer, @RawPtr @RawPtr Image dstImage, int srcColorType, int dstColorType, BufferImageCopyData[] copyData)

  - ### copyImage

    public final boolean copyImage(@RawPtr @RawPtr Image srcImage, int srcL, int srcT, int srcR, int srcB, @RawPtr @RawPtr Image dstImage, int dstX, int dstY, int mipLevel)
    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.

    Can only be used outside render passes.

    The caller must track resources if success.

    Returns:
      success or not

  - ### onCopyImage

    protected abstract boolean onCopyImage(@RawPtr @RawPtr Image srcImage, int srcL, int srcT, int srcR, int srcB, @RawPtr @RawPtr Image dstImage, int dstX, int dstY, int mipLevel)

  - ### trackResource

    public final void trackResource(@SharedPtr @SharedPtr Resource resource)
    Takes a Usage ref on the Resource that will be released when the command buffer has finished execution.

    This is mostly commonly used for host-visible Buffers and shared Resources.

    Parameters:
      `resource` - the resource to move

  - ### trackResource

    public final void trackResource(@SharedPtr @SharedPtr ManagedResource resource)
    Takes a ref on the ManagedResource that will be released when the command buffer has finished execution.
    Parameters:
      `resource` - the resource to move

  - ### trackCommandBufferResource

    public final void trackCommandBufferResource(@SharedPtr @SharedPtr Resource resource)
    Takes a CommandBuffer ref on the Resource that will be released when the command buffer has finished execution.

    CommandBuffer ref allows a Resource to be returned to ResourceCache for reuse while the CommandBuffer is still executing on the GPU. This is most commonly used for GPU-only Resources.

    Parameters:
      `resource` - the resource to move

  - ### begin

    protected abstract void begin()

  - ### submit

    protected abstract boolean submit(QueueManager queueManager)

  - ### checkFinishedAndReset

    protected abstract boolean checkFinishedAndReset()

  - ### waitUntilFinished

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

  - ### callFinishedCallbacks

    protected final void callFinishedCallbacks(boolean success)

  - ### releaseResources

    protected final void releaseResources()