vkCmdSetViewportShadingRatePaletteNV(3)

# vkCmdSetViewportShadingRatePaletteNV(3) Manual Page

## Name

vkCmdSetViewportShadingRatePaletteNV - Set shading rate image palettes dynamically for a command buffer

## C Specification

To dynamically set the per-viewport shading rate image palettes, call:

    // Provided by VK_NV_shading_rate_image
    void vkCmdSetViewportShadingRatePaletteNV(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    firstViewport,
        uint32_t                                    viewportCount,
        const VkShadingRatePaletteNV*               pShadingRatePalettes);

## Parameters

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

- `firstViewport` is the index of the first viewport whose shading rate palette is updated by the command.

- `viewportCount` is the number of viewports whose shading rate palettes are updated by the command.

- `pShadingRatePalettes` is a pointer to an array of VkShadingRatePaletteNV structures defining the palette for each viewport.

## Description

This command sets the per-viewport shading rate image palettes for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV set in VkPipelineDynamicStateCreateInfo::`pDynamicStates`. Otherwise, this state is specified by the VkPipelineViewportShadingRateImageStateCreateInfoNV::`pShadingRatePalettes` values used to create the currently active pipeline.

Valid Usage

- VUID-vkCmdSetViewportShadingRatePaletteNV-None-02064
  The `shadingRateImage` feature must be enabled

- VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02067
  The sum of `firstViewport` and `viewportCount` must be between `1` and `VkPhysicalDeviceLimits`::`maxViewports`, inclusive

- VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02068
  If the `multiViewport` feature is not enabled, `firstViewport` must be `0`

- VUID-vkCmdSetViewportShadingRatePaletteNV-viewportCount-02069
  If the `multiViewport` feature is not enabled, `viewportCount` must be `1`

Valid Usage (Implicit)

- VUID-vkCmdSetViewportShadingRatePaletteNV-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdSetViewportShadingRatePaletteNV-pShadingRatePalettes-parameter
  `pShadingRatePalettes` must be a valid pointer to an array of `viewportCount` valid VkShadingRatePaletteNV structures

- VUID-vkCmdSetViewportShadingRatePaletteNV-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdSetViewportShadingRatePaletteNV-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support VK_QUEUE_GRAPHICS_BIT operations

- VUID-vkCmdSetViewportShadingRatePaletteNV-videocoding
  This command must only be called outside of a video coding scope

- VUID-vkCmdSetViewportShadingRatePaletteNV-viewportCount-arraylength
  `viewportCount` must be greater than `0`

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Both | Outside | VK_QUEUE_GRAPHICS_BIT | State

Conditional Rendering

vkCmdSetViewportShadingRatePaletteNV is not affected by conditional rendering

## See Also

VK_NV_shading_rate_image, VkCommandBuffer, VkShadingRatePaletteNV

## Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0