VKCMDSETVIEWPORT(3)

NAME
vkCmdSetViewport - Set the viewport on a command buffer.

C SPECIFICATION

    void vkCmdSetViewport(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    firstViewport,
        uint32_t                                    viewportCount,
        const VkViewport*                           pViewports);

PARAMETERS

commandBuffer
    The command buffer into which to insert the command.

viewportCount
    The number of viewport rectangles to set.

pViewports
    A pointer to an array of structures describing the viewports.

DESCRIPTION

vkCmdSetViewport sets the dynamic viewport state for the command buffer specified in commandBuffer. viewportCount is the number of viewports to update and pViewports is a pointer to an array of VkViewport structures describing the new viewport state. The definition of VkViewport is:

    typedef struct VkViewport {
        float    x;
        float    y;
        float    width;
        float    height;
        float    minDepth;
        float    maxDepth;
    } VkViewport;

The x and y members of VkViewport specifies the upper left corner of the viewport rectangle, in pixels. The width and height parameters specify the size of the rectangle, and are also expressed in pixels. The minDepth and maxDepth members specify the depth range for the viewport.

The viewports numbered zero through viewportCount are updated and any remaining viewports become undefined.

The graphics pipeline bound to commandBuffer must have the VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled. When a pipeline that does not have VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled is first bound, the origins and extents of the viewports are taken from the pipeline and attempts to change them using vkCmdSetViewport results in undefined behavior. When a pipeline does have VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled is first bound, the current values of the viewport rectangle origins and extents become undefined and must be set using a call to vkCmdSetViewport.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • pViewports must be a pointer to an array of viewportCount valid VkViewport structures

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics operations

    • viewportCount must be greater than 0

    • firstViewport must be less than VkPhysicalDeviceLimits::maxViewports

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

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Both | GRAPHICS

SEE ALSO

vkCreateGraphicsPipelines, VkPipelineDynamicStateCreateInfo

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.