# VkImageStencilUsageCreateInfo(3) Manual Page

## Name

VkImageStencilUsageCreateInfo - Specify separate usage flags for the stencil aspect of a depth-stencil image

Loading… please wait.

## C Specification

The `VkImageStencilUsageCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_2
    typedef struct VkImageStencilUsageCreateInfo {
        VkStructureType      sType;
        const void*          pNext;
        VkImageUsageFlags    stencilUsage;
    } VkImageStencilUsageCreateInfo;

or the equivalent

    // Provided by VK_EXT_separate_stencil_usage
    typedef VkImageStencilUsageCreateInfo VkImageStencilUsageCreateInfoEXT;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `stencilUsage` is a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.

## Description

If the `pNext` chain of VkImageCreateInfo includes a `VkImageStencilUsageCreateInfo` structure, then that structure includes the usage flags specific to the stencil aspect of the image for an image with a depth-stencil format.

This structure specifies image usages which only apply to the stencil aspect of a depth/stencil format image. When this structure is included in the `pNext` chain of VkImageCreateInfo, the stencil aspect of the image must only be used as specified by `stencilUsage`. When this structure is not included in the `pNext` chain of VkImageCreateInfo, the stencil aspect of an image must only be used as specified by VkImageCreateInfo::`usage`. Use of other aspects of an image are unaffected by this structure.

This structure can also be included in the `pNext` chain of VkPhysicalDeviceImageFormatInfo2 to query additional capabilities specific to image creation parameter combinations including a separate set of usage flags for the stencil aspect of the image using vkGetPhysicalDeviceImageFormatProperties2. When this structure is not included in the `pNext` chain of `VkPhysicalDeviceImageFormatInfo2` then the implicit value of `stencilUsage` matches that of `VkPhysicalDeviceImageFormatInfo2`::`usage`.

Valid Usage

- VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539
  If `stencilUsage` includes `VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT`, it must not include bits other than `VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT` or `VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT`

Valid Usage (Implicit)

- VUID-VkImageStencilUsageCreateInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO`

- VUID-VkImageStencilUsageCreateInfo-stencilUsage-parameter
  `stencilUsage` must be a valid combination of VkImageUsageFlagBits values

- VUID-VkImageStencilUsageCreateInfo-stencilUsage-requiredbitmask
  `stencilUsage` must not be `0`

## See Also

VK_EXT_separate_stencil_usage, VK_VERSION_1_2, VkImageUsageFlags, VkStructureType

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0