Vulkan.Extensions.VK_NV_clip_space_w_scaling

Name

VK_NV_clip_space_w_scaling - device extension

VK_NV_clip_space_w_scaling

Name String

VK_NV_clip_space_w_scaling

Extension Type

Device extension

Registered Extension Number

88

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0

Contact

• Eric Werness https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_NV_clip_space_w_scaling:%20&body=@ewerness-nv%20

Other Extension Metadata

Last Modified Date

2017-02-15

Contributors

• Eric Werness, NVIDIA
• Kedarnath Thangudu, NVIDIA

Description

Virtual Reality (VR) applications often involve a post-processing step to apply a “barrel” distortion to the rendered image to correct the “pincushion” distortion introduced by the optics in a VR device. The barrel distorted image has lower resolution along the edges compared to the center. Since the original image is rendered at high resolution, which is uniform across the complete image, a lot of pixels towards the edges do not make it to the final post-processed image.

This extension provides a mechanism to render VR scenes at a non-uniform resolution, in particular a resolution that falls linearly from the center towards the edges. This is achieved by scaling the w coordinate of the vertices in the clip space before perspective divide. The clip space w coordinate of the vertices can be offset as of a function of x and y coordinates as follows:

w' = w + Ax + By

In the intended use case for viewport position scaling, an application should use a set of four viewports, one for each of the four quadrants of a Cartesian coordinate system. Each viewport is set to the dimension of the image, but is scissored to the quadrant it represents. The application should specify A and B coefficients of the w-scaling equation above, that have the same value, but different signs, for each of the viewports. The signs of A and B should match the signs of x and y for the quadrant that they represent such that the value of w' will always be greater than or equal to the original w value for the entire image. Since the offset to w, (Ax + By), is always positive, and increases with the absolute values of x and y, the effective resolution will fall off linearly from the center of the image to its edges.

New Commands

• cmdSetViewportWScalingNV

New Structures

• ViewportWScalingNV

• Extending PipelineViewportStateCreateInfo:

  • PipelineViewportWScalingStateCreateInfoNV

New Enum Constants

• NV_CLIP_SPACE_W_SCALING_EXTENSION_NAME

• NV_CLIP_SPACE_W_SCALING_SPEC_VERSION

• Extending DynamicState:

  • DYNAMIC_STATE_VIEWPORT_W_SCALING_NV

• Extending StructureType:

  • STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV

Issues

1) Is the pipeline struct name too long?

RESOLVED: It fits with the naming convention.

2) Separate W scaling section or fold into coordinate transformations?

RESOLVED: Leaving it as its own section for now.

Examples

VkViewport viewports[4];
VkRect2D scissors[4];
VkViewportWScalingNV scalings[4];

for (int i = 0; i < 4; i++) {
    int x = (i & 2) ? 0 : currentWindowWidth / 2;
    int y = (i & 1) ? 0 : currentWindowHeight / 2;

    viewports[i].x = 0;
    viewports[i].y = 0;
    viewports[i].width = currentWindowWidth;
    viewports[i].height = currentWindowHeight;
    viewports[i].minDepth = 0.0f;
    viewports[i].maxDepth = 1.0f;

    scissors[i].offset.x = x;
    scissors[i].offset.y = y;
    scissors[i].extent.width = currentWindowWidth/2;
    scissors[i].extent.height = currentWindowHeight/2;

    const float factor = 0.15;
    scalings[i].xcoeff = ((i & 2) ? -1.0 : 1.0) * factor;
    scalings[i].ycoeff = ((i & 1) ? -1.0 : 1.0) * factor;
}

VkPipelineViewportWScalingStateCreateInfoNV vpWScalingStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV };

vpWScalingStateInfo.viewportWScalingEnable = VK_TRUE;
vpWScalingStateInfo.viewportCount = 4;
vpWScalingStateInfo.pViewportWScalings = &scalings[0];

VkPipelineViewportStateCreateInfo vpStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO };
vpStateInfo.viewportCount = 4;
vpStateInfo.pViewports = &viewports[0];
vpStateInfo.scissorCount = 4;
vpStateInfo.pScissors = &scissors[0];
vpStateInfo.pNext = &vpWScalingStateInfo;

Example shader to read from a w-scaled texture:

// Vertex Shader
// Draw a triangle that covers the whole screen
const vec4 positions[3] = vec4[3](vec4(-1, -1, 0, 1),
                                  vec4( 3, -1, 0, 1),
                                  vec4(-1,  3, 0, 1));
out vec2 uv;
void main()
{
    vec4 pos = positions[ gl_VertexID ];
    gl_Position = pos;
    uv = pos.xy;
}

// Fragment Shader
uniform sampler2D tex;
uniform float xcoeff;
uniform float ycoeff;
out vec4 Color;
in vec2 uv;

void main()
{
    // Handle uv as if upper right quadrant
    vec2 uvabs = abs(uv);

    // unscale: transform w-scaled image into an unscaled image
    //   scale: transform unscaled image int a w-scaled image
    float unscale = 1.0 / (1 + xcoeff * uvabs.x + xcoeff * uvabs.y);
    //float scale = 1.0 / (1 - xcoeff * uvabs.x - xcoeff * uvabs.y);

    vec2 P = vec2(unscale * uvabs.x, unscale * uvabs.y);

    // Go back to the right quadrant
    P *= sign(uv);

    Color = texture(tex, P * 0.5 + 0.5);
}

Version History

• Revision 1, 2017-02-15 (Eric Werness)

  • Internal revisions

See Also

PipelineViewportWScalingStateCreateInfoNV, ViewportWScalingNV, cmdSetViewportWScalingNV

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

cmdSetViewportWScalingNV

Arguments

:: forall io. MonadIO io

=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> ("firstViewport" ::: Word32)

firstViewport is the index of the first viewport whose parameters are updated by the command.

-> ("viewportWScalings" ::: Vector ViewportWScalingNV)

pViewportWScalings is a pointer to an array of ViewportWScalingNV structures specifying viewport parameters.

-> io ()

vkCmdSetViewportWScalingNV - Set the viewport W scaling on a command buffer

Description

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

Valid Usage

• The sum of firstViewport and viewportCount must be between 1 and PhysicalDeviceLimits::maxViewports, inclusive

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pViewportWScalings must be a valid pointer to an array of viewportCount ViewportWScalingNV structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support graphics operations
• viewportCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels	Render Pass Scope	Supported Queue Types
Primary Secondary	Both	Graphics

See Also

CommandBuffer, ViewportWScalingNV

data ViewportWScalingNV

VkViewportWScalingNV - Structure specifying a viewport

See Also

PipelineViewportWScalingStateCreateInfoNV, cmdSetViewportWScalingNV

Constructors

ViewportWScalingNV

Fields

• xcoeff :: Float

  xcoeff and ycoeff are the viewport’s W scaling factor for x and y respectively.

• ycoeff :: Float

Instances

Eq ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

(==) :: ViewportWScalingNV -> ViewportWScalingNV -> Bool

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

Show ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

showsPrec :: Int -> ViewportWScalingNV -> ShowS

show :: ViewportWScalingNV -> String

showList :: [ViewportWScalingNV] -> ShowS

Storable ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

sizeOf :: ViewportWScalingNV -> Int

alignment :: ViewportWScalingNV -> Int

peekElemOff :: Ptr ViewportWScalingNV -> Int -> IO ViewportWScalingNV

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

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

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

peek :: Ptr ViewportWScalingNV -> IO ViewportWScalingNV

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

FromCStruct ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

peekCStruct :: Ptr ViewportWScalingNV -> IO ViewportWScalingNV

ToCStruct ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

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

pokeCStruct :: Ptr ViewportWScalingNV -> ViewportWScalingNV -> IO b -> IO b

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

pokeZeroCStruct :: Ptr ViewportWScalingNV -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ViewportWScalingNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

zero :: ViewportWScalingNV

data PipelineViewportWScalingStateCreateInfoNV

VkPipelineViewportWScalingStateCreateInfoNV - Structure specifying parameters of a newly created pipeline viewport W scaling state

Valid Usage (Implicit)

See Also

Bool32, StructureType, ViewportWScalingNV

Constructors

PipelineViewportWScalingStateCreateInfoNV

Fields

• viewportWScalingEnable :: Bool

  viewportWScalingEnable controls whether viewport W scaling is enabled.

• viewportCount :: Word32

  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.

  viewportCount must be greater than 0

• viewportWScalings :: Vector ViewportWScalingNV

  pViewportWScalings is a pointer to an array of ViewportWScalingNV structures defining the W scaling parameters for the corresponding viewports. If the viewport W scaling state is dynamic, this member is ignored.

Instances

Show PipelineViewportWScalingStateCreateInfoNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

showsPrec :: Int -> PipelineViewportWScalingStateCreateInfoNV -> ShowS

show :: PipelineViewportWScalingStateCreateInfoNV -> String

showList :: [PipelineViewportWScalingStateCreateInfoNV] -> ShowS

FromCStruct PipelineViewportWScalingStateCreateInfoNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

peekCStruct :: Ptr PipelineViewportWScalingStateCreateInfoNV -> IO PipelineViewportWScalingStateCreateInfoNV

ToCStruct PipelineViewportWScalingStateCreateInfoNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

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

pokeCStruct :: Ptr PipelineViewportWScalingStateCreateInfoNV -> PipelineViewportWScalingStateCreateInfoNV -> IO b -> IO b

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

pokeZeroCStruct :: Ptr PipelineViewportWScalingStateCreateInfoNV -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PipelineViewportWScalingStateCreateInfoNV

Defined in Vulkan.Extensions.VK_NV_clip_space_w_scaling

Methods

zero :: PipelineViewportWScalingStateCreateInfoNV

type NV_CLIP_SPACE_W_SCALING_SPEC_VERSION = 1

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

type NV_CLIP_SPACE_W_SCALING_EXTENSION_NAME = "VK_NV_clip_space_w_scaling"

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