VKCMDSETSTENCILREFER(3)

NAME
vkCmdSetStencilReference - Set the stencil reference dynamic state.

C SPECIFICATION

    void vkCmdSetStencilReference(
        VkCommandBuffer                             commandBuffer,
        VkStencilFaceFlags                          faceMask,
        uint32_t                                    reference);

PARAMETERS

commandBuffer
    The command buffer into which to insert the command.

faceMask
    The face or faces to which the command is to apply.

reference
    The new value for the stencil reference dynamic state.

DESCRIPTION

vkCmdSetStencilReference sets the reference value used for stencil comparisons on the command buffer specified by commandBuffer. faceMask specifies the face or faces to which the new values are applied. It a bitmask comprised of members of the VkStencilFaceFlagBits enumeration, the definition of which is:

    typedef enum VkStencilFaceFlagBits {
        VK_STENCIL_FACE_FRONT_BIT = 0x00000001,
        VK_STENCIL_FACE_BACK_BIT = 0x00000002,
        VK_STENCIL_FRONT_AND_BACK = 0x00000003,
    } VkStencilFaceFlagBits;

The graphics pipeline bound to commandBuffer must have the VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled. When a pipeline that does not have VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled is first bound, the value if the stencil reference value is taken from the pipeline and attempts to change it using vkCmdSetStencilReference results in undefined behavior. When a pipeline does have VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled is bound, the current value of the stencil reference value becomes undefined and must be set using a call to vkCmdSetStencilReference.

If the stencil test is disabled in the current graphics pipeline, then the value of the stencil compare mask is ignored.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • faceMask must be a valid combination of VkStencilFaceFlagBits values

    • faceMask must not be 0

    • commandBuffer must be in the recording state

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

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, vkCmdSetStencilCompareMask, vkCmdSetStencilWriteMask, 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.