// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

vkCmdSetDepthBias(3)
====================

Name
----
vkCmdSetDepthBias - Set the depth bias dynamic state.

C Specification
---------------

// refBegin vkCmdSetDepthBias Set the depth bias dynamic state.

The depth values of all fragments generated by the rasterization of a
polygon can: be offset by a single value that is computed for that polygon.
This behavior is controlled by the pname:depthBiasEnable,
pname:depthBiasConstantFactor, pname:depthBiasClamp, and
pname:depthBiasSlopeFactor members of
slink:VkPipelineRasterizationStateCreateInfo, or by the corresponding
parameters to the fname:vkCmdSetDepthBias command if depth bias state is
dynamic.

include::../protos/vkCmdSetDepthBias.txt[]


Parameters
----------

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:depthBiasConstantFactor is a scalar factor controlling the
    constant depth value added to each fragment.
  * pname:depthBiasClamp is the maximum (or minimum) depth bias of a
    fragment.
  * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
    slope in depth bias calculations.


Description
-----------

If pname:depthBiasEnable is ename:VK_FALSE, no depth bias is applied and the
fragment's depth values are unchanged.

pname:depthBiasSlopeFactor scales the maximum depth slope of the polygon,
and pname:depthBiasConstantFactor scales an implementation-dependent
constant that relates to the usable resolution of the depth buffer. The
resulting values are summed to produce the depth bias value which is then
clamped to a minimum or maximum value specified by pname:depthBiasClamp.
pname:depthBiasSlopeFactor, pname:depthBiasConstantFactor, and
pname:depthBiasClamp can: each be positive, negative, or zero.

The maximum depth slope latexmath:[$m$] of a triangle is

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{equation}
m = \sqrt{ \left({\partial z_f \over \partial x_f}\right)^2
 +  \left({\partial z_f \over  \partial y_f}\right)^2}
\end{equation}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where latexmath:[$(x_f, y_f, z_f)$] is a point on the triangle.
latexmath:[$m$] may: be approximated as

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{equation}
m = \max( \left |{\partial z_f \over \partial x_f} \right |,
\left |{\partial z_f \over \partial y_f} \right | ).
\end{equation}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The minimum resolvable difference latexmath:[$r$] is an
implementation-dependent parameter that depends on the depth buffer
representation. It is the smallest difference in framebuffer coordinate
latexmath:[$z$] values that is guaranteed to remain distinct throughout
polygon rasterization and in the depth buffer. All pairs of fragments
generated by the rasterization of two polygons with otherwise identical
vertices, but latexmath:[$z_f$] values that differ by $r$, will have
distinct depth values.

For fixed-point depth buffer representations, latexmath:[$r$] is constant
throughout the range of the entire depth buffer. For floating-point depth
buffers, there is no single minimum resolvable difference. In this case, the
minimum resolvable difference for a given polygon is dependent on the
maximum exponent, latexmath:[$e$], in the range of latexmath:[$z$] values
spanned by the primitive. If latexmath:[$n$] is the number of bits in the
floating-point mantissa, the minimum resolvable difference, latexmath:[$r$],
for the given primitive is defined as

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{equation}
r = 2^{e - n}
\end{equation}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

If no depth buffer is present, latexmath:[$r$] is undefined.

The bias value latexmath:[$o$] for a polygon is

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{equation}
o =
\begin{cases}
    m \times depthBiasSlopeFactor +
         r \times depthBiasConstantFactor  & depthBiasClamp = 0\ or\ NaN \\
    \min(m \times depthBiasSlopeFactor +
         r \times depthBiasConstantFactor,
         depthBiasClamp)                   & depthBiasClamp > 0  \\
    \max(m \times depthBiasSlopeFactor +
         r \times depthBiasConstantFactor,
         depthBiasClamp)                   & depthBiasClamp < 0  \\
\end{cases}
\end{equation}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

latexmath:[$m$] is computed as described above. If the depth buffer uses a
fixed-point representation, latexmath:[$m$] is a function of depth values in
the range latexmath:[$[0,1\]$], and latexmath:[$o$] is applied to depth
values in the same range.

For fixed-point depth buffers, fragment depth values are always limited to
the range latexmath:[$[0,1\]$] by clamping after depth bias addition is
performed. Fragment depth values are clamped even when the depth buffer uses
a floating-point representation.

include::../validity/protos/vkCmdSetDepthBias.txt[]


See Also
--------

slink:VkCommandBuffer


Document Notes
--------------

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdSetDepthBias

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

include::footer.txt[]