SFML 3.1.0
Loading...
Searching...
No Matches
Public Attributes | Related Symbols | List of all members
sf::StencilMode Class Reference
Graphics module

Stencil modes for drawing. More...

`#include <SFML/Graphics/StencilMode.hpp>`

## Public Attributes

StencilComparison | stencilComparison {StencilComparison::Always}
| The comparison we're performing the stencil test with.
StencilUpdateOperation | stencilUpdateOperation
| The update operation to perform if the stencil test passes.
StencilValue | stencilReference {0}
| The reference value we're performing the stencil test with.
StencilValue | stencilMask {~0u}
| The mask to apply to both the reference value and the value in the stencil buffer.
bool | stencilOnly {}
| Whether we should update the color buffer in addition to the stencil buffer.

## Related Symbols

(Note that these are not member symbols.)
bool | operator== (const StencilMode &left, const StencilMode &right)
| Overload of the operator==.
bool | operator!= (const StencilMode &left, const StencilMode &right)
| Overload of the operator!=.

## Detailed Description

Stencil modes for drawing.

sf::StencilMode is a class that controls stencil testing.

In addition to drawing to the visible portion of a render target, there is the possibility to "draw" to a so-called stencil buffer. The stencil buffer is a special non-visible buffer that can contain a single value per pixel that is drawn. This can be thought of as a fifth value in addition to red, green, blue and alpha values. The maximum value that can be represented depends on what is supported by the system. Typically support for a 8-bit stencil buffer should always be available. This will also have to be requested when creating a render target via the sf::ContextSettings that is passed during creation. Stencil testing will not work if there is no stencil buffer available in the target that is being drawn to.

Initially, just like with the visible color buffer, the stencil value of each pixel is set to an undefined value. Calling sf::RenderTarget::clear will set each pixel's stencil value to 0. sf::RenderTarget::clear can be called at any time to reset the stencil values back to 0.

When drawing an object, before each pixel of the color buffer is updated with its new color value, the stencil test is performed. During this test 2 values are compared with each other: the reference value that is passed via sf::StencilMode and the value that is currently in the stencil buffer. The arithmetic comparison that is performed on the 2 values can also be controlled via sf::StencilMode. Depending on whether the test passes i.e. the comparison yields true, the color buffer is updated with its new RGBA value and if set in sf::StencilMode the stencil buffer is updated accordingly. The new stencil value will be used during stencil testing the next time the pixel is drawn to.

The class is composed of 5 components, each of which has its own public member variable:

- Stencil Comparison (stencilComparison)
- Stencil Update Operation (stencilUpdateOperation)
- Stencil Reference Value (stencilReference)
- Stencil Mask Value (stencilMask)
- Stencil Only Update (stencilOnly)

The stencil comparison specifies the comparison that is performed between the reference value of the currently active sf::StencilMode and the value that is currently in the stencil buffer. This comparison determines whether the stencil test passes or fails.

The stencil update operation specifies how the stencil buffer is updated if the stencil test passes. If the stencil test fails, neither the color or stencil buffers will be modified. If incrementing or decrementing the stencil value, the new value will be clamped to the range from 0 to the maximum representable value given the bit width of the stencil buffer e.g. 255 if an 8-bit stencil buffer is being used.

The reference value is used both during the comparison with the current stencil buffer value and as the new value to be written when the operation is set to Replace.

The mask value is used to mask the bits of both the reference value and the value in the stencil buffer during the comparison and when updating. The mask can be used to e.g. segment the stencil value bits into separate regions that are used for different purposes.

In certain situations, it might make sense to only write to the stencil buffer and not the color buffer during a draw. The written stencil buffer value can then be used in subsequent draws as a masking region.

In SFML, a stencil mode can be specified every time you draw a sf::Drawable object to a render target. It is part of the sf::RenderStates compound that is passed to the member function sf::RenderTarget::draw().

Usage example:

// Make sure we create a RenderTarget with a stencil buffer by specifying it via the context settings
sf::RenderWindow window(sf::VideoMode({250, 200}), "Stencil Window", sf::Style::Default, sf::ContextSettings{0, 8});
...
// Left circle
sf::CircleShape left(100.f);
left.setFillColor(sf::Color::Green);
left.setPosition({0, 0});
// Middle circle
sf::CircleShape middle(100.f);
middle.setFillColor(sf::Color::Yellow);
middle.setPosition({25, 0});
// Right circle
sf::CircleShape right(100.f);
right.setFillColor(sf::Color::Red);
right.setPosition({50, 0});
...
// Clear the stencil buffer to 0 at the start of every frame
window.clear(sf::Color::Black, 0);
...
// Draw the middle circle in a stencil-only pass and write the value 1
// to the stencil buffer for every pixel the circle would have affected
window.draw(middle, sf::StencilMode{sf::StencilComparison::Always, sf::StencilUpdateOperation::Replace, 1, 0xFF, true});
// Draw the left and right circles
// Only allow rendering to pixels whose stencil value is not
// equal to 1 i.e. weren't written when drawing the middle circle
window.draw(left, sf::StencilMode{sf::StencilComparison::NotEqual, sf::StencilUpdateOperation::Keep, 1, 0xFF, false});
window.draw(right, sf::StencilMode{sf::StencilComparison::NotEqual, sf::StencilUpdateOperation::Keep, 1, 0xFF, false});
sf::Color::Red
static const Color Red
Red predefined color.
Definition Color.hpp:84
sf::Color::Black
static const Color Black
Black predefined color.
Definition Color.hpp:82
sf::Color::Green
static const Color Green
Green predefined color.
Definition Color.hpp:85
sf::Color::Yellow
static const Color Yellow
Yellow predefined color.
Definition Color.hpp:87
sf::RenderTarget::draw
void draw(const Drawable &drawable, const RenderStates &states=RenderStates::Default)
Draw a drawable object to the render target.
sf::RenderWindow
Window that can serve as a target for 2D drawing.
Definition RenderWindow.hpp:55
sf::VideoMode
VideoMode defines a video mode (size, bpp).
Definition VideoMode.hpp:44
sf::Style::Default
@ Default
Default window style.
Definition WindowEnums.hpp:49
sf::StencilComparison::NotEqual
@ NotEqual
The stencil test passes if the new value is strictly unequal to the value in the stencil buffer.
Definition StencilMode.hpp:50
sf::StencilComparison::Always
@ Always
The stencil test always passes.
Definition StencilMode.hpp:51
sf::StencilUpdateOperation::Keep
@ Keep
If the stencil test passes, the value in the stencil buffer is not modified.
Definition StencilMode.hpp:62
sf::StencilUpdateOperation::Replace
@ Replace
If the stencil test passes, the value in the stencil buffer is set to the new value.
Definition StencilMode.hpp:64
sf::ContextSettings
Structure defining the settings of the OpenGL context attached to a window.
Definition ContextSettings.hpp:39

See also
  sf::RenderStates, sf::RenderTarget

Definition at line 106 of file StencilMode.hpp.

## Friends And Related Symbol Documentation

## ◆ operator!=()

bool operator!= | ( | const StencilMode & | left,
|  | const StencilMode & | right )

related

Overload of the operator!=.

Parameters

  left | Left operand
  right | Right operand

Returns
  true if stencil modes are different, false if they are equal

## ◆ operator==()

bool operator== | ( | const StencilMode & | left,
|  | const StencilMode & | right )

related

Overload of the operator==.

Parameters

  left | Left operand
  right | Right operand

Returns
  true if stencil modes are equal, false if they are different

## Member Data Documentation

## ◆ stencilComparison

StencilComparison sf::StencilMode::stencilComparison {StencilComparison::Always}

The comparison we're performing the stencil test with.

Definition at line 108 of file StencilMode.hpp.

## ◆ stencilMask

StencilValue sf::StencilMode::stencilMask {~0u}

The mask to apply to both the reference value and the value in the stencil buffer.

Definition at line 112 of file StencilMode.hpp.

## ◆ stencilOnly

bool sf::StencilMode::stencilOnly {}

Whether we should update the color buffer in addition to the stencil buffer.

Definition at line 113 of file StencilMode.hpp.

## ◆ stencilReference

StencilValue sf::StencilMode::stencilReference {0}

The reference value we're performing the stencil test with.

Definition at line 111 of file StencilMode.hpp.

## ◆ stencilUpdateOperation

StencilUpdateOperation sf::StencilMode::stencilUpdateOperation

Initial value:
{
StencilUpdateOperation::Keep}

The update operation to perform if the stencil test passes.

Definition at line 109 of file StencilMode.hpp.

The documentation for this class was generated from the following file:

- StencilMode.hpp