Vulkan.Extensions.VK_NV_inherited_viewport_scissor

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

Extension and Version Dependencies

• Requires Vulkan 1.0

Contact

• David Zhao Akeley @akeley98%0A<<Here describe the issue or question you have about the VK_NV_inherited_viewport_scissor extension> >

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

• Extending CommandBufferInheritanceInfo:

  • CommandBufferInheritanceViewportScissorInfoNV

• Extending PhysicalDeviceFeatures2, DeviceCreateInfo:

  • PhysicalDeviceInheritedViewportScissorFeaturesNV

New Enum Constants

• NV_INHERITED_VIEWPORT_SCISSOR_EXTENSION_NAME

• NV_INHERITED_VIEWPORT_SCISSOR_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV
  • STRUCTURE_TYPE_PHYSICAL_DEVICE_INHERITED_VIEWPORT_SCISSOR_FEATURES_NV

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.

Documentation

data PhysicalDeviceInheritedViewportScissorFeaturesNV

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

Constructors

PhysicalDeviceInheritedViewportScissorFeaturesNV

Fields

• inheritedViewportScissor2D :: Bool

  inheritedViewportScissor2D indicates whether secondary command buffers can inherit most of the dynamic state affected by DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, DYNAMIC_STATE_VIEWPORT or DYNAMIC_STATE_SCISSOR, from a primary command buffer.

Instances

Eq PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

(==) :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> Bool

(/=) :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> Bool

Show PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

showsPrec :: Int -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> ShowS

show :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> String

showList :: [PhysicalDeviceInheritedViewportScissorFeaturesNV] -> ShowS

Storable PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

sizeOf :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> Int

alignment :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> Int

peekElemOff :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> Int -> IO PhysicalDeviceInheritedViewportScissorFeaturesNV

pokeElemOff :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> Int -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO ()

peekByteOff :: Ptr b -> Int -> IO PhysicalDeviceInheritedViewportScissorFeaturesNV

pokeByteOff :: Ptr b -> Int -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO ()

peek :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO PhysicalDeviceInheritedViewportScissorFeaturesNV

poke :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO ()

FromCStruct PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

peekCStruct :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO PhysicalDeviceInheritedViewportScissorFeaturesNV

ToCStruct PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

withCStruct :: PhysicalDeviceInheritedViewportScissorFeaturesNV -> (Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO b) -> IO b

pokeCStruct :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO b -> IO b

withZeroCStruct :: (Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO b) -> IO b

pokeZeroCStruct :: Ptr PhysicalDeviceInheritedViewportScissorFeaturesNV -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PhysicalDeviceInheritedViewportScissorFeaturesNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

zero :: PhysicalDeviceInheritedViewportScissorFeaturesNV

data CommandBufferInheritanceViewportScissorInfoNV

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:

• DYNAMIC_STATE_SCISSOR
• DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

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

• DYNAMIC_STATE_VIEWPORT
• DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT

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 that defines 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 inherited viewport scissor feature is not enabled, viewportScissor2D must be FALSE

• If the multiple viewports 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)

• sType must be STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV

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

Show CommandBufferInheritanceViewportScissorInfoNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

showsPrec :: Int -> CommandBufferInheritanceViewportScissorInfoNV -> ShowS

show :: CommandBufferInheritanceViewportScissorInfoNV -> String

showList :: [CommandBufferInheritanceViewportScissorInfoNV] -> ShowS

FromCStruct CommandBufferInheritanceViewportScissorInfoNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

peekCStruct :: Ptr CommandBufferInheritanceViewportScissorInfoNV -> IO CommandBufferInheritanceViewportScissorInfoNV

ToCStruct CommandBufferInheritanceViewportScissorInfoNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

withCStruct :: CommandBufferInheritanceViewportScissorInfoNV -> (Ptr CommandBufferInheritanceViewportScissorInfoNV -> IO b) -> IO b

pokeCStruct :: Ptr CommandBufferInheritanceViewportScissorInfoNV -> CommandBufferInheritanceViewportScissorInfoNV -> IO b -> IO b

withZeroCStruct :: (Ptr CommandBufferInheritanceViewportScissorInfoNV -> IO b) -> IO b

pokeZeroCStruct :: Ptr CommandBufferInheritanceViewportScissorInfoNV -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero CommandBufferInheritanceViewportScissorInfoNV

Defined in Vulkan.Extensions.VK_NV_inherited_viewport_scissor

Methods

zero :: CommandBufferInheritanceViewportScissorInfoNV

type NV_INHERITED_VIEWPORT_SCISSOR_SPEC_VERSION = 1

pattern NV_INHERITED_VIEWPORT_SCISSOR_SPEC_VERSION :: forall a. Integral a => a

type NV_INHERITED_VIEWPORT_SCISSOR_EXTENSION_NAME = "VK_NV_inherited_viewport_scissor"

pattern NV_INHERITED_VIEWPORT_SCISSOR_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a