HORIZON HASKELLDocslts/ghc-9.14.x3e2d5682026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 3e2d568 · 2026-10-11

Modulevulkan-3.27GHC2021

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

Ratification Status

Not ratified

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2

or

Vulkan Version 1.1

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 reusable 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

No cross-references are available

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.

  • 4 types
  • Packagevulkan-3.27
  • Exports6
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_NV_inherited_viewport_scissor.hs
datadata 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. If the application wishes to use a Device with any features described by PhysicalDeviceInheritedViewportScissorFeaturesNV, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

See Also

VK_NV_inherited_viewport_scissor, Bool32, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata 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:

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.

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.

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)

Structure Chaining

Extends the structure

See Also

VK_NV_inherited_viewport_scissor, Bool32, StructureType, Viewport

Constructors

Instances4Show, FromCStruct, ToCStruct, Zero