Package icyllis.arc3d.engine

Class Caps

java.lang.Object
icyllis.arc3d.engine.Caps
Direct Known Subclasses:
GLCaps, VulkanCaps
public abstract class Caps extends Object
Represents the capabilities of a 3D API Context.

Capabilities are used to test if something is capable or not. In other words, these are optional and there are alternatives, required features are not listed here. For historical reasons, there are still some capability methods, but only return constants (become required).

  • Field Details

    • MAX_COLOR_TARGETS

      public static final int MAX_COLOR_TARGETS
      Most implementations support 4 or 8 simultaneous color targets.
      See Also:

    • MAX_VERTEX_ATTRIBUTES

      public static final int MAX_VERTEX_ATTRIBUTES
      Max allowed number of vertex attribute locations. Most implementations support 16 or 32 attributes, and our engine uses 'int' as enable mask type, then this is 32, see VertexInputLayout.
      See Also:

    • MAX_VERTEX_BINDINGS

      public static final int MAX_VERTEX_BINDINGS
      See Also:

    • mShaderCaps

      protected final ShaderCaps mShaderCaps

    • mAnisotropySupport

      protected boolean mAnisotropySupport

    • mGpuTracingSupport

      protected boolean mGpuTracingSupport

    • mConservativeRasterSupport

      protected boolean mConservativeRasterSupport

    • mTransferPixelsToRowBytesSupport

      protected boolean mTransferPixelsToRowBytesSupport

    • mMustSyncGpuDuringDiscard

      protected boolean mMustSyncGpuDuringDiscard

    • mTextureBarrierSupport

      protected boolean mTextureBarrierSupport

    • mDepthClipNegativeOneToOne

      protected boolean mDepthClipNegativeOneToOne

    • mClampToBorderSupport

      protected boolean mClampToBorderSupport

    • mDynamicStateArrayGeometryProcessorTextureSupport

      protected boolean mDynamicStateArrayGeometryProcessorTextureSupport

    • mBlendEquationSupport

      protected Caps.BlendEquationSupport mBlendEquationSupport

    • mMapBufferFlags

      protected int mMapBufferFlags

    • mMaxRenderTargetSize

      protected int mMaxRenderTargetSize

    • mMaxPreferredRenderTargetSize

      protected int mMaxPreferredRenderTargetSize

    • mMaxVertexAttributes

      protected int mMaxVertexAttributes

    • mMaxVertexBindings

      protected int mMaxVertexBindings

    • mMaxTextureSize

      protected int mMaxTextureSize

    • mInternalMultisampleCount

      protected int mInternalMultisampleCount

    • mMaxPushConstantsSize

      protected int mMaxPushConstantsSize

    • mMaxColorAttachments

      protected int mMaxColorAttachments

    • mMinUniformBufferOffsetAlignment

      protected int mMinUniformBufferOffsetAlignment

    • mMinStorageBufferOffsetAlignment

      protected int mMinStorageBufferOffsetAlignment

    • mDriverBugWorkarounds

      protected final DriverBugWorkarounds mDriverBugWorkarounds

  • Constructor Details

  • Method Details

    • shaderCaps

      public final ShaderCaps shaderCaps()
      Returns:
      the set of capabilities for shaders

    • npotTextureTileSupport

      public final boolean npotTextureTileSupport()
      Non-power-of-two texture tile.

    • mipmapSupport

      public final boolean mipmapSupport()
      To avoid as-yet-unnecessary complexity we don't allow any partial support of MIP Maps (e.g. only for POT textures)

    • hasAnisotropySupport

      public final boolean hasAnisotropySupport()
      Anisotropic filtering (AF).

    • gpuTracingSupport

      public final boolean gpuTracingSupport()

    • oversizedStencilSupport

      public final boolean oversizedStencilSupport()
      Allows mixed size FBO attachments.

    • textureBarrierSupport

      public final boolean textureBarrierSupport()

    • sampleLocationsSupport

      public final boolean sampleLocationsSupport()

    • drawInstancedSupport

      public final boolean drawInstancedSupport()

    • conservativeRasterSupport

      public final boolean conservativeRasterSupport()

    • wireframeSupport

      public final boolean wireframeSupport()

    • msaaResolvesAutomatically

      public final boolean msaaResolvesAutomatically()
      This flag indicates that we never have to resolve MSAA. In practice, it means that we have an MSAA-render-to-texture extension: Any render target we create internally will use the extension, and any wrapped render target is the client's responsibility.

    • preferDiscardableMSAAAttachment

      public final boolean preferDiscardableMSAAAttachment()
      If true then when doing MSAA draws, we will prefer to discard the msaa attachment on load and stores. The use of this feature for specific draws depends on the render target having a resolve attachment, and if we need to load previous data the resolve attachment must be usable as an input attachment/texture. Otherwise, we will just write out and store the msaa attachment like normal.

      This flag is similar to enabling gl render to texture for msaa rendering.

    • halfFloatVertexAttributeSupport

      public final boolean halfFloatVertexAttributeSupport()

    • usePrimitiveRestart

      public final boolean usePrimitiveRestart()
      Primitive restart functionality is core in ES 3.0, but using it will cause slowdowns on some systems. This cap is only set if primitive restart will improve performance.

    • preferClientSideDynamicBuffers

      public final boolean preferClientSideDynamicBuffers()

    • preferFullscreenClears

      public final boolean preferFullscreenClears()
      On tilers, an initial fullscreen clear is an OPTIMIZATION. It allows the hardware to initialize each tile with a constant value rather than loading each pixel from memory.

    • discardStencilValuesAfterRenderPass

      public final boolean discardStencilValuesAfterRenderPass()
      Should we discard stencil values after a render pass? (Tilers get better performance if we always load stencil buffers with a "clear" op, and then discard the content when finished.)

    • twoSidedStencilRefsAndMasksMustMatch

      public final boolean twoSidedStencilRefsAndMasksMustMatch()
      D3D does not allow the refs or masks to differ on a two-sided stencil draw.

    • preferVRAMUseOverFlushes

      public final boolean preferVRAMUseOverFlushes()

    • avoidStencilBuffers

      public final boolean avoidStencilBuffers()

    • avoidWritePixelsFastPath

      public final boolean avoidWritePixelsFastPath()

    • requiresManualFBBarrierAfterTessellatedStencilDraw

      public final boolean requiresManualFBBarrierAfterTessellatedStencilDraw()

    • nativeDrawIndexedIndirectIsBroken

      public final boolean nativeDrawIndexedIndirectIsBroken()

    • blendEquationSupport

      public final Caps.BlendEquationSupport blendEquationSupport()

    • advancedBlendEquationSupport

      public final boolean advancedBlendEquationSupport()

    • advancedCoherentBlendEquationSupport

      public final boolean advancedCoherentBlendEquationSupport()

    • shouldCollapseSrcOverToSrcWhenAble

      public final boolean shouldCollapseSrcOverToSrcWhenAble()
      On some GPUs it is a performance win to disable blending instead of doing src-over with a src alpha equal to 1. To disable blending we collapse src-over to src and the backends will handle the disabling of blending.

    • mustSyncGpuDuringDiscard

      public final boolean mustSyncGpuDuringDiscard()
      When discarding the DirectContext do we need to sync the GPU before we start discarding resources.

    • supportsTextureBarrier

      public final boolean supportsTextureBarrier()

    • reducedShaderMode

      public final boolean reducedShaderMode()

    • reuseScratchTextures

      public final boolean reuseScratchTextures()
      Scratch textures not being reused means that those scratch textures that we upload to (i.e., don't have a render target) will not be recycled in the texture cache. This is to prevent ghosting by drivers (in particular for deferred architectures).

    • reuseScratchBuffers

      public final boolean reuseScratchBuffers()

    • minUniformBufferOffsetAlignment

      public final int minUniformBufferOffsetAlignment()
      Returns:
      minimum required alignment, in bytes, for the offset member of the BufferViewInfo structure for uniform buffers

    • minStorageBufferOffsetAlignment

      public final int minStorageBufferOffsetAlignment()
      Returns:
      minimum required alignment, in bytes, for the offset member of the BufferViewInfo structure for shader storage buffers

    • maxVertexAttributes

      public final int maxVertexAttributes()
      Maximum number of attribute values (i.e. locations) per vertex input. Matrix types and double types can take up multiple consecutive locations.

    • maxVertexBindings

      public final int maxVertexBindings()
      Maximum number of vertex binding points (i.e. vertex buffers) per vertex input. The binding passed to bindVertexBuffer must be in [0,maxVertexBindings).

    • maxRenderTargetSize

      public final int maxRenderTargetSize()

    • maxPreferredRenderTargetSize

      public final int maxPreferredRenderTargetSize()
      This is the largest render target size that can be used without incurring extra performance cost. It is usually the max RT size, unless larger render targets are known to be slower.

    • maxTextureSize

      public final int maxTextureSize()
      Maximum 2D/1D texture image dimension.

    • maxPushConstantsSize

      public final int maxPushConstantsSize()

    • maxColorAttachments

      public final int maxColorAttachments()
      Max number of color attachments in a render pass. This is ranged from 4 (typically on mobile) to 8 (typically on desktop).

    • transferBufferAlignment

      public final int transferBufferAlignment()

    • isFormatTexturable

      public abstract boolean isFormatTexturable(BackendFormat format)
      Can a texture be made with the BackendFormat, and then be bound and sampled in a shader. It must be a color format, you cannot pass a stencil format here.

      For OpenGL: Formats that deprecated in core profile are not supported; Compressed formats from extensions are uncertain; Others are always supported.

    • getMaxRenderTargetSampleCount

      public abstract int getMaxRenderTargetSampleCount(BackendFormat format)
      Returns the maximum supported sample count for a format. 0 means the format is not renderable 1 means the format is renderable but doesn't support MSAA.

    • getInternalMultisampleCount

      public final int getInternalMultisampleCount(BackendFormat format)
      Returns the number of samples to use when performing draws to the given config with internal MSAA. If 0, we should not attempt to use internal multisampling.

    • isFormatRenderable

      public abstract boolean isFormatRenderable(int colorType, BackendFormat format, int sampleCount)

    • isFormatRenderable

      public abstract boolean isFormatRenderable(BackendFormat format, int sampleCount)

    • getRenderTargetSampleCount

      public abstract int getRenderTargetSampleCount(int sampleCount, BackendFormat format)
      Find a sample count greater than or equal to the requested count which is supported for a render target of the given format or 0 if no such sample count is supported. If the requested sample count is 1 then 1 will be returned if non-MSAA rendering is supported, otherwise 0.
      Parameters:
      sampleCount - requested samples

    • getSupportedWriteColorType

      public abstract long getSupportedWriteColorType(int dstColorType, ImageDesc dstDesc, int srcColorType)
      Given a dst pixel config and a src color type what color type must the caller coax the data into in order to use writePixels().

      Low 32bits - colorType ((int) value). High 32bits - transferOffsetAlignment (value >>> 32). If the write is occurring using transferPixelsTo() then this provides the minimum alignment of the offset into the transfer buffer.

    • getSupportedReadColorType

      public final long getSupportedReadColorType(int srcColorType, BackendFormat srcFormat, int dstColorType)
      Given a src surface's color type and its backend format as well as a color type the caller would like read into, this provides a legal color type that the caller may pass to readPixels(). The returned color type may differ from the passed dstColorType, in which case the caller must convert the read pixel data (see ConvertPixels). When converting to dstColorType the swizzle in the returned struct should be applied. The caller must check the returned color type for UNKNOWN.

      Low 32bits - colorType ((int) value). High 32bits - transferOffsetAlignment (value >>> 32). If the write is occurring using transferPixelsTo() then this provides the minimum alignment of the offset into the transfer buffer.

    • onSupportedReadColorType

      protected abstract long onSupportedReadColorType(int srcColorType, BackendFormat srcFormat, int dstColorType)

    • writePixelsRowBytesSupport

      public final boolean writePixelsRowBytesSupport()
      Does writePixels() support a src buffer where the row bytes is not equal to bpp * w?

    • transferPixelsToRowBytesSupport

      public final boolean transferPixelsToRowBytesSupport()
      Does transferPixelsTo() support a src buffer where the row bytes is not equal to bpp * w?

    • readPixelsRowBytesSupport

      public final boolean readPixelsRowBytesSupport()
      Does readPixels() support a dst buffer where the row bytes is not equal to bpp * w?

    • transferFromSurfaceToBufferSupport

      public final boolean transferFromSurfaceToBufferSupport()

    • transferFromBufferToTextureSupport

      public final boolean transferFromBufferToTextureSupport()

    • mustClearUploadedBufferData

      public final boolean mustClearUploadedBufferData()
      True in environments that will issue errors if memory uploaded to buffers is not initialized (even if not read by draw calls).

    • shouldInitializeTextures

      public final boolean shouldInitializeTextures()
      For some environments, there is a performance or safety concern to not initializing textures. For example, with WebGL and Firefox, there is a large performance hit to not doing it.

    • fenceSyncSupport

      public final boolean fenceSyncSupport()
      Supports using Fence.

    • semaphoreSupport

      public final boolean semaphoreSupport()
      Supports using Semaphore.

    • crossContextTextureSupport

      public final boolean crossContextTextureSupport()

    • dynamicStateArrayGeometryProcessorTextureSupport

      public final boolean dynamicStateArrayGeometryProcessorTextureSupport()

    • performPartialClearsAsDraws

      public final boolean performPartialClearsAsDraws()

    • performColorClearsAsDraws

      public final boolean performColorClearsAsDraws()

    • avoidLargeIndexBufferDraws

      public final boolean avoidLargeIndexBufferDraws()

    • performStencilClearsAsDraws

      public final boolean performStencilClearsAsDraws()

    • clampToBorderSupport

      public final boolean clampToBorderSupport()
      The CLAMP_TO_BORDER wrap mode for texture coordinates was added to desktop GL in 1.3, and GLES 3.2, but is also available in extensions. Vulkan and Metal always have support.

    • depthClipNegativeOneToOne

      public final boolean depthClipNegativeOneToOne()
      Whether clip space's depth is ranged from negative one to one (true) or zero to one (false).

    • validateSurfaceParams

      public final boolean validateSurfaceParams(int width, int height, BackendFormat format, int sampleCount, int surfaceFlags)
      If a texture or render target can be created with these params.

    • validateAttachmentParams

      public final boolean validateAttachmentParams(int width, int height, BackendFormat format, int sampleCount)
      If an attachment can be created with these params.

    • isFormatCompatible

      public final boolean isFormatCompatible(int colorType, BackendFormat format)

    • onFormatCompatible

      protected abstract boolean onFormatCompatible(int colorType, BackendFormat format)

    • getDefaultColorImageDesc

      public @Nullable ImageDesc getDefaultColorImageDesc(int imageType, int colorType, int width, int height, int depthOrArraySize, int imageFlags)
      Parameters:
      imageType -
      colorType -
      width -
      height -
      depthOrArraySize -
      imageFlags -
      Returns:
      See Also:

    • getDefaultColorImageDesc

      public @Nullable ImageDesc getDefaultColorImageDesc(int imageType, int colorType, int width, int height, int depthOrArraySize, int mipLevelCount, int sampleCount, int imageFlags)
      Parameters:
      imageType -
      colorType -
      width -
      height -
      depthOrArraySize -
      mipLevelCount -
      sampleCount -
      imageFlags -
      Returns:
      See Also:

    • getDefaultDepthStencilImageDesc

      public @Nullable ImageDesc getDefaultDepthStencilImageDesc(int depthBits, int stencilBits, int width, int height, int sampleCount, int imageFlags)

    • getImageDescForSampledCopy

      public @Nullable ImageDesc getImageDescForSampledCopy(ImageDesc src, int width, int height, int depthOrArraySize, int imageFlags)

    • getDefaultBackendFormat

      public final @Nullable BackendFormat getDefaultBackendFormat(int colorType, boolean renderable)
      These are used when creating a new texture internally.

    • onGetDefaultBackendFormat

      protected abstract @Nullable BackendFormat onGetDefaultBackendFormat(int colorType)

    • getCompressedBackendFormat

      public abstract @Nullable BackendFormat getCompressedBackendFormat(int compressionType)

    • makeGraphicsPipelineKey

      public abstract @NonNull PipelineKey makeGraphicsPipelineKey(PipelineKey old, PipelineDesc pipelineDesc, RenderPassDesc renderPassDesc)

    • getReadSwizzle

      public final short getReadSwizzle(ImageDesc desc, int colorType)

    • onGetReadSwizzle

      protected abstract short onGetReadSwizzle(ImageDesc desc, int colorType)

    • getWriteSwizzle

      public abstract short getWriteSwizzle(ImageDesc desc, int colorType)

    • computeImageKey

      public abstract IResourceKey computeImageKey(ImageDesc desc, IResourceKey recycle)

    • workarounds

      public final DriverBugWorkarounds workarounds()

    • finishInitialization

      protected final void finishInitialization(ContextOptions options)

    • onApplyOptionsOverrides

      protected void onApplyOptionsOverrides(ContextOptions options)