vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Description

Name

VK_NV_inherited_viewport_scissor - device extension

VK_NV_inherited_viewport_scissor

Name String
VK_NV_inherited_viewport_scissor
Extension Type
Device extension
Registered Extension Number
279
Revision
1
Ratification Status
Not ratified
Extension and Version Dependencies
VK_KHR_get_physical_device_properties2
Contact

Other Extension Metadata

Last Modified Date
2021-02-04
Contributors
  • David Zhao Akeley, NVIDIA
  • Jeff Bolz, NVIDIA
  • Piers Daniell, NVIDIA
  • Christoph Kubisch, NVIDIA

Description

This extension adds the ability for a secondary command buffer to inherit the dynamic viewport and scissor state from a primary command buffer, or a previous secondary command buffer executed within the same cmdExecuteCommands call. It addresses a frequent scenario in applications that deal with window resizing and want to improve utilization of re-usable secondary command buffers. The functionality is provided through CommandBufferInheritanceViewportScissorInfoNV. Viewport inheritance is effectively limited to the 2D rectangle; secondary command buffers must re-specify the inherited depth range values.

New Structures

New Enum Constants

Issues

  1. Why are viewport depth values configured in the CommandBufferInheritanceViewportScissorInfoNV struct, rather than by a vkCmd…​ function?

DISCUSSION:

We considered both adding a new vkCmdSetViewportDepthNV function, and modifying cmdSetViewport to ignore the x, y, width, and height values when called with a secondary command buffer that activates this extension.

The primary design considerations for this extension are debuggability and easy integration into existing applications. The main issue with adding a new vkCmdSetViewportDepthNV function is reducing ease-of-integration. A new function pointer will have to be loaded, but more importantly, a new function would require changes to be supported in graphics debuggers; this would delay widespread adoption of the extension.

The proposal to modify cmdSetViewport would avoid these issues. However, we expect that the intent of applications using this extension is to have the viewport values used for drawing exactly match the inherited values; thus, it would be better for debuggability if no function for modifying the viewport depth alone is provided. By specifying viewport depth values when starting secondary command buffer recording, and requiring the specified depth values to match the inherited depth values, we allow for validation layers that flag depth changes as errors.

This design also better matches the hardware model. In fact, there is no need to re-execute a depth-setting command. The graphics device retains the viewport depth state; it is the CPU-side state of CommandBuffer that must be re-initialized.

  1. Why are viewport depth values specified as a partial Viewport struct, rather than a leaner depth-only struct?

DISCUSSION:

We considered adding a new VkViewportDepthNV struct containing only minDepth and maxDepth. However, as application developers would need to maintain both a VK_NV_inherited_viewport_scissor code path and a fallback code path (at least in the short term), we ultimately chose to continue using the existing Viewport structure. Doing so would allow application developers to reuse the same Viewport array for both code paths, rather than constructing separate VkViewportDepthNV and Viewport arrays for each code path.

Version History

  • Revision 1, 2020-02-04 (David Zhao Akeley)

    • Internal revisions

See Also

CommandBufferInheritanceViewportScissorInfoNV, PhysicalDeviceInheritedViewportScissorFeaturesNV

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

data PhysicalDeviceInheritedViewportScissorFeaturesNV Source #

VkPhysicalDeviceInheritedViewportScissorFeaturesNV - Structure describing the viewport scissor inheritance behavior for an implementation

Members

This structure describes the following feature:

Description

If the PhysicalDeviceInheritedViewportScissorFeaturesNV structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceInheritedViewportScissorFeaturesNV can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_NV_inherited_viewport_scissor, Bool32, StructureType

Instances

Instances details
Storable PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Show PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Eq PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

FromCStruct PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

ToCStruct PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Zero PhysicalDeviceInheritedViewportScissorFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

data CommandBufferInheritanceViewportScissorInfoNV Source #

VkCommandBufferInheritanceViewportScissorInfoNV - Structure specifying command buffer inheritance information

Description

If the pNext chain of CommandBufferInheritanceInfo includes a CommandBufferInheritanceViewportScissorInfoNV structure, then that structure controls whether a command buffer can inherit the following state from other command buffers:

as well as the following state, with restrictions on inherited depth values and viewport count:

If viewportScissor2D is FALSE, then the command buffer does not inherit the listed dynamic state, and should set this state itself. If this structure is not present, the behavior is as if viewportScissor2D is FALSE.

If viewportScissor2D is TRUE, then the listed dynamic state is inherited, and the command buffer must not set this state, except that the viewport and scissor count may be set by binding a graphics pipeline that does not specify this state as dynamic.

Note

Due to this restriction, applications should ensure either all or none of the graphics pipelines bound in this secondary command buffer use dynamic viewport/scissor counts.

When the command buffer is executed as part of a the execution of a cmdExecuteCommands command, the inherited state (if enabled) is determined by the following procedure, performed separately for each dynamic state, and separately for each value for dynamic state that consists of multiple values (e.g. multiple viewports).

  • With i being the index of the executed command buffer in the pCommandBuffers array of cmdExecuteCommands, if i > 0 and any secondary command buffer from index 0 to i-1 modifies the state, the inherited state is provisionally set to the final value set by the last such secondary command buffer. Binding a graphics pipeline defining the state statically is equivalent to setting the state to an undefined value.
  • Otherwise, the tentatative inherited state is that of the primary command buffer at the point the cmdExecuteCommands command was recorded; if the state is undefined, then so is the provisional inherited state.
  • If the provisional inherited state is an undefined value, then the state is not inherited.
  • If the provisional inherited state is a viewport, with n being its viewport index, then if n ≥ viewportDepthCount, or if either Viewport::minDepth or Viewport::maxDepth are not equal to the respective values of the nth element of pViewportDepths, then the state is not inherited.
  • If the provisional inherited state passes both checks, then it becomes the actual inherited state.

Note

There is no support for inheriting dynamic state from a secondary command buffer executed as part of a different cmdExecuteCommands command.

Valid Usage

  • If the multiViewport feature is not enabled and viewportScissor2D is TRUE, then viewportDepthCount must be 1
  • If viewportScissor2D is TRUE, then viewportDepthCount must be greater than 0
  • If viewportScissor2D is TRUE, then pViewportDepths must be a valid pointer to an array of viewportDepthCount valid Viewport structures, except any requirements on x, y, width, and height do not apply
  • If viewportScissor2D is TRUE, then the command buffer must be recorded with the COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

Valid Usage (Implicit)

See Also

VK_NV_inherited_viewport_scissor, Bool32, StructureType, Viewport

Constructors

CommandBufferInheritanceViewportScissorInfoNV 

Fields

  • viewportScissor2D :: Bool

    viewportScissor2D specifies whether the listed dynamic state is inherited.

  • viewportDepthCount :: Word32

    viewportDepthCount specifies the maximum number of viewports to inherit. When viewportScissor2D is FALSE, the behavior is as if this value is zero.

  • viewportDepths :: Viewport

    pViewportDepths is a pointer to a Viewport structure specifying the expected depth range for each inherited viewport.

Instances

Instances details
Show CommandBufferInheritanceViewportScissorInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

FromCStruct CommandBufferInheritanceViewportScissorInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

ToCStruct CommandBufferInheritanceViewportScissorInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Zero CommandBufferInheritanceViewportScissorInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

type NV_INHERITED_VIEWPORT_SCISSOR_EXTENSION_NAME = "VK_NV_inherited_viewport_scissor" Source #