The '''Write Mask''' is the part of the [[Rendering Pipeline Overview|rendering pipeline]] that allows or prevents color, depth, or stencil components from being written to the current framebuffer.

The '''Write Mask''' is the part of the [[Rendering Pipeline Overview|rendering pipeline]] that allows or prevents color, depth, or stencil components from being written to the current framebuffer.

−

The [[Fragment Shader]] can output one or more color values, as well as a depth value. The stencil state also causes the emitting of a stencil value. After blending, logic ops, and depth/stencil tests, the fragment values can be written to a sample in the framebuffer. The masking state can prevent certain components from being written.

+

[[Fragment]]s can contain a number of color values, a depth value, and a stencil value. All but the stencil can be generated by a [[Fragment Shader]]. After various testing operations, the fragment's values can be written to a sample in the current [[Framebuffer]]. Write masking state can prevent certain components of data from being written.

−

Note that masking state affects ''all'' functions that modify the framebuffer. This includes:

+

Masking state affects these operations that modify the current [[Framebuffer]]:

{{note|This does not apply to operations that affect images that just so ''happen'' to be part of the current framebuffer. For example, if you use [[Image Load Store]] to modify an image's data, the write mask will not affect that write even if that image is also part of the current [[Framebuffer Object]] (of course, trying to write to the same image in two ways also yields undefined behavior). The write mask only applies to write operations that go through to the current [[Framebuffer]].}}

+

+

Even though the mask only applies to writes to a framebuffer, the mask state is ''not'' [[Framebuffer]] state. So it is not part of a [[Framebuffer Object]] or the [[Default Framebuffer]]. Binding a new framebuffer will not affect the mask.

== Color Mask ==

== Color Mask ==

Line 13:

Line 17:

The color(s) output from the fragment shader can be masked. Each individual color component, R, G, B, and A, has a separate mask. So it is possible to prevent certain color components from being written.

The color(s) output from the fragment shader can be masked. Each individual color component, R, G, B, and A, has a separate mask. So it is possible to prevent certain color components from being written.

−

Each separate color buffer, as defined by the {{apifunc|glDrawBuffers}} function, has a separate mask. The mask state is not framebuffer state, so it is not bound to the [[Framebuffer Object]] or the [[Default Framebuffer]].

+

Each separate color buffer, as defined by the {{apifunc|glDrawBuffers}} function, has a separate mask.

To set the mask for a particular draw buffer, use the glColorMaski function:

To set the mask for a particular draw buffer, use the glColorMaski function:

The {{param|buf}} parameter specifies which of the color buffers to set the mask for. This can be any value on the range [0, {{enum|GL_MAX_DRAW_BUFFERS}}). The other values are set to {{enum|GL_TRUE}} to enable writing that component and {{enum|GL_FALSE}} to disable writing it.

The {{param|buf}} parameter specifies which of the color buffers to set the mask for. This can be any value on the range [0, {{enum|GL_MAX_DRAW_BUFFERS}}). The other values are set to {{enum|GL_TRUE}} to enable writing that component and {{enum|GL_FALSE}} to disable writing it.

Line 33:

Line 37:

== Stencil Mask ==

== Stencil Mask ==

−

Stencil write masking works slightly different. The stencil buffer works in terms of a bitfield (usually with 8-bits). Therefore instead of taking a boolean value, the stencil mask is an integer:

+

Stencil write masking works slightly differently, in two ways. First, the [[Stencil Buffer]] is always an unsigned integer (of some bitdepth), so the mask here is an actual bitfield, rather than simply being on/off.

+

+

The other difference is that the [[Stencil Test]] can be different for the [[Triangle Facing|two sides of triangles]]. Therefore, the stencil write mask can be set for either side, or both at once.

The {{param|face}} determines which stencil bitmask facing is being set. It can be {{enum|GL_FRONT}}, {{enum|GL_BACK}}, or {{enum|GL_FRONT_AND_BACK}} to set the bitmask for both sides at once. The bits set in {{param|mask}} are the only stencil bits that will be affected by any subsequent rendering commands.

−

void {{apifunc|glStencilMask}}(GLuint {{param|mask}});

+

The {{apifunc|glStencilMask}} function can be used as shorthand for {{enum|GL_FRONT_AND_BACK}}.

−

The bits that are set in {{param|mask}} are the bits that will be written.

The Write Mask is the part of the rendering pipeline that allows or prevents color, depth, or stencil components from being written to the current framebuffer.

Fragments can contain a number of color values, a depth value, and a stencil value. All but the stencil can be generated by a Fragment Shader. After various testing operations, the fragment's values can be written to a sample in the current Framebuffer. Write masking state can prevent certain components of data from being written.

Masking state affects these operations that modify the current Framebuffer:

Note: This does not apply to operations that affect images that just so happen to be part of the current framebuffer. For example, if you use Image Load Store to modify an image's data, the write mask will not affect that write even if that image is also part of the current Framebuffer Object (of course, trying to write to the same image in two ways also yields undefined behavior). The write mask only applies to write operations that go through to the current Framebuffer.

Color Mask

The color(s) output from the fragment shader can be masked. Each individual color component, R, G, B, and A, has a separate mask. So it is possible to prevent certain color components from being written.

Each separate color buffer, as defined by the glDrawBuffers​ function, has a separate mask.

To set the mask for a particular draw buffer, use the glColorMaski function:

The buf​ parameter specifies which of the color buffers to set the mask for. This can be any value on the range [0, GL_MAX_DRAW_BUFFERS). The other values are set to GL_TRUE to enable writing that component and GL_FALSE to disable writing it.

The function glColorMask​ can be used to set the mask for all draw buffers. This is useful for quickly re-enabling write masks on all output buffers.

Depth Mask

The depth buffer write can be masked, thus preventing the depth buffer from being updated. This useful for implementing transparency. Masking is controlled by this function:

Stencil Mask

Stencil write masking works slightly differently, in two ways. First, the Stencil Buffer is always an unsigned integer (of some bitdepth), so the mask here is an actual bitfield, rather than simply being on/off.

The other difference is that the Stencil Test can be different for the two sides of triangles. Therefore, the stencil write mask can be set for either side, or both at once.

The face​ determines which stencil bitmask facing is being set. It can be GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK to set the bitmask for both sides at once. The bits set in mask​ are the only stencil bits that will be affected by any subsequent rendering commands.

The glStencilMask​ function can be used as shorthand for GL_FRONT_AND_BACK.