Controlling the Viewport

The viewport transformation is determined by the selected viewport’s width and height in pixels, px and py, respectively, and its center (ox, oy) (also in pixels), as well as its depth range min and max determining a depth range scale value pz and a depth range bias value oz (defined below). The vertex’s framebuffer coordinates (xf, yf, zf) are given by

xf = (px / 2) xd + ox
yf = (py / 2) yd + oy
zf = pz × zd + oz

Multiple viewports are available, numbered zero up to VkPhysicalDeviceLimits::maxViewports minus one. The number of viewports used by a pipeline is controlled by the viewportCount member of the VkPipelineViewportStateCreateInfo structure used in pipeline creation.

xf and yf have limited precision, where the number of fractional bits retained is specified by VkPhysicalDeviceLimits::subPixelPrecisionBits.

The VkPipelineViewportStateCreateInfo structure is defined as:

AFX_DEFINE_STRUCT(afxPipelineViewportConfig)
{
    afxNat vpCnt; /// is the number of viewports used by the pipeline.
    afxViewport const vp[]; /// is an array of structures, defining the viewport transforms.
    afxNat scisCnt; /// is the number of scissors and must match the number of viewports.
    afxRect const scis[]; /// is an array of structures defining the rectangular bounds of the
 scissor for the corresponding viewport.
};

To dynamically set the viewport count and viewports, call:

void AfxCmdSetViewportWithCount
(
    afxDrawScript dscr, /// is the command buffer into which the command will be recorded.
    afxNat cnt, /// specifies the viewport count.
    afxViewport const vp[] /// specifies the viewports to use for drawing.
);

This command sets the viewport count and viewports state for subsequent drawing commands when the graphics pipeline is created with VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the corresponding VkPipelineViewportStateCreateInfo::viewportCount and pViewports values used to create the currently active pipeline.

To dynamically set the scissor count and scissor rectangular bounds, call:

void AfxCmdSetScissorWithCount
(
    afxDrawScript dscr, /// is the command buffer into which the command will be recorded.
    afxNat cnt, /// specifies the scissor count.
    afxRect const scis[] /// specifies the scissors to use for drawing.
);

This command sets the scissor count and scissor rectangular bounds state for subsequent drawing commands when the graphics pipeline is created with VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the corresponding VkPipelineViewportStateCreateInfo::scissorCount and pScissors values used to create the currently active pipeline.

A pre-rasterization shader stage can direct each primitive to one of several viewports. The destination viewport for a primitive is selected by the last active pre-rasterization shader stage that has an output variable decorated with ViewportIndex. The viewport transform uses the viewport corresponding to the value assigned to ViewportIndex, and taken from an implementationdependent vertex of each primitive. If ViewportIndex is outside the range zero to viewportCount minus one for a primitive, or if the last active pre-rasterization shader stage did not assign a value to ViewportIndex for all vertices of a primitive due to flow control, the values resulting from the viewport transformation of the vertices of such primitives are undefined. If the last prerasterization shader stage does not have an output decorated with ViewportIndex, the viewport numbered zero is used by the viewport transformation.

A single vertex can be used in more than one individual primitive, in primitives such as TRIANGLE_STRIP. In this case, the viewport transformation is applied separately for each primitive.

To dynamically set the viewport transformation parameters, call:

void AfxCmdSetViewports
(
    afxDrawScript dscr, /// is the command buffer into which the command will be recorded.
    afxNat first, /// is the index of the first viewport whose parameters are updated by the command.
    afxNat cnt, /// is the number of viewports whose parameters are updated by the command.
    afxViewport const vp[] /// is an array ofstructures specifying viewport parameters.
);

This command sets the viewport transformation parameters state for subsequent drawing commands when the graphics pipeline is created with VK_DYNAMIC_STATE_VIEWPORT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineViewportStateCreateInfo::pViewports values used to create the currently active pipeline.

The viewport parameters taken from element i of pViewports replace the current state for the viewport index firstViewport + i, for i in [0, viewportCount).

Both afxPipelineViewportConfig and AfxCmdSetViewports use afxViewport to set the viewport
transformation parameters.

The afxViewport structure is defined as:

AFX_DEFINE_STRUCT(afxViewport)
{
    afxV2d origin; /// [ x, y ] are the viewport's upper left corner (x,y).
    afxV2d extent; /// [ w, h ] are the viewport's width and height, respectively.
    afxV2d depth; /// [ min, max ] are the depth range for the viewport.
};

Note

Despite their names, depth min can be less than, equal to, or greater than depth max.

The framebuffer depth coordinate zf may be represented using either a fixed-point or floating-point representation. However, a floating-point representation must be used if the depth/stencil attachment has a floating-point depth component. If an m-bit fixed-point representation is used, we assume that it represents each value (k / (2^m – 1)), where k ∈ { 0, 1, …, 2^m – 1 }, as k (e.g. 1.0 is represented in binary as a string of all ones).

The viewport parameters shown in the above equations are found from these values as

ox = x + width / 2
oy = y + height / 2
oz = minDepth
px = width
py = height
pz = maxDepth - minDepth

The application can specify a negative term for height, which has the effect of negating the y coordinate in clip space before performing the transform. When using a negative height, the application should also adjust the y value to point to the lower left corner of the viewport instead of the upper left corner. Using the negative height allows the application to avoid having to negate the y component of the Position output from the last pre-rasterization shader stage.

The width and height of the implementation-dependent maximum viewport dimensions must be greater than or equal to the width and height of the largest image which can be created and attached to a framebuffer.

The floating-point viewport bounds are represented with an implementation-dependent precision.