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

[[vertexpostproc-viewportwscaling]]
== Controlling Viewport W Scaling

If viewport *W* scaling is enabled, the *W* component of the clip coordinate
is modified by the provided coefficients from the corresponding viewport as
follows.

  {empty}:: [eq]#w~c~' = x~coeff~ x~c~ {plus} y~coeff~ y~c~ {plus} w~c~#

[open,refpage='VkPipelineViewportWScalingStateCreateInfoNV',desc='Structure specifying parameters of a newly created pipeline viewport W scaling state',type='structs']
--
The sname:VkPipelineViewportWScalingStateCreateInfoNV structure is defined
as:

include::{generated}/api/structs/VkPipelineViewportWScalingStateCreateInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:viewportWScalingEnable controls whether viewport *W* scaling is
    enabled.
  * pname:viewportCount is the number of viewports used by *W* scaling, and
    must: match the number of viewports in the pipeline if viewport *W*
    scaling is enabled.
  * pname:pViewportWScalings is a pointer to an array of
    sname:VkViewportWScalingNV structures defining the *W* scaling
    parameters for the corresponding viewports.
    If the viewport *W* scaling state is dynamic, this member is ignored.

include::{generated}/validity/structs/VkPipelineViewportWScalingStateCreateInfoNV.txt[]
--

The sname:VkPipelineViewportWScalingStateCreateInfoNV state is set by adding
this structure to the pname:pNext chain of a
sname:VkPipelineViewportStateCreateInfo structure and setting the graphics
pipeline state with flink:vkCreateGraphicsPipelines.

[open,refpage='vkCmdSetViewportWScalingNV',desc='Set the viewport W scaling dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the viewport *W* scaling
parameters, call:

include::{generated}/api/protos/vkCmdSetViewportWScalingNV.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:firstViewport is the index of the first viewport whose parameters
    are updated by the command.
  * pname:viewportCount is the number of viewports whose parameters are
    updated by the command.
  * pname:pViewportWScalings is a pointer to an array of
    slink:VkViewportWScalingNV structures specifying viewport parameters.

The viewport parameters taken from element [eq]#i# of
pname:pViewportWScalings replace the current state for the viewport index
[eq]#pname:firstViewport {plus} i#, for [eq]#i# in [eq]#[0,
pname:viewportCount)#.

This command sets the viewport *W* scaling for subsequent drawing commands
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:pViewportWScalings
values used to create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetViewportWScalingNV-firstViewport-01324]]
    The sum of pname:firstViewport and pname:viewportCount must: be between
    `1` and slink:VkPhysicalDeviceLimits::pname:maxViewports, inclusive
****

include::{generated}/validity/protos/vkCmdSetViewportWScalingNV.txt[]
--

Both slink:VkPipelineViewportWScalingStateCreateInfoNV and
flink:vkCmdSetViewportWScalingNV use sname:VkViewportWScalingNV to set the
viewport transformation parameters.

[open,refpage='VkViewportWScalingNV',desc='Structure specifying a viewport',type='structs']
--
The sname:VkViewportWScalingNV structure is defined as:

include::{generated}/api/structs/VkViewportWScalingNV.txt[]

  * pname:xcoeff and pname:ycoeff are the viewport's W scaling factor for x
    and y respectively.

include::{generated}/validity/structs/VkViewportWScalingNV.txt[]
--