// Copyright (c) 2020 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_NV_inherited_viewport_scissor.txt[]

=== 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
flink:vkCmdExecuteCommands 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
slink:VkCommandBufferInheritanceViewportScissorInfoNV.
Viewport inheritance is effectively limited to the 2D rectangle; secondary
command buffers must re-specify the inherited depth range values.

include::{generated}/interfaces/VK_NV_inherited_viewport_scissor.txt[]

=== Issues

(1) Why are viewport depth values configured in the
slink:VkCommandBufferInheritanceViewportScissorInfoNV struct, rather than by
a `vkCmd...` function?
--
*DISCUSSION*:

We considered both adding a new ftext:vkCmdSetViewportDepthNV function, and
modifying flink:vkCmdSetViewport to ignore the pname:x, pname:y,
pname:width, and pname: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 ftext: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 flink:vkCmdSetViewport 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 slink:VkCommandBuffer that must be re-initialized.
--

(2) Why are viewport depth values specified as a partial slink:VkViewport
struct, rather than a leaner depth-only struct?
--
*DISCUSSION*:

We considered adding a new stext:VkViewportDepthNV struct containing only
ptext:minDepth and ptext: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
slink:VkViewport structure.
Doing so would allow application developers to reuse the same
slink:VkViewport array for both code paths, rather than constructing
separate stext:VkViewportDepthNV and slink:VkViewport arrays for each code
path.
--

=== Version History

  * Revision 1, 2020-02-04 (David Zhao Akeley)
    - Internal revisions