Added support for stencil testing.

include/SFML/Graphics.hpp

@@ -48,6 +48,7 @@
 #include <SFML/Graphics/Shader.hpp>
 #include <SFML/Graphics/Shape.hpp>
 #include <SFML/Graphics/Sprite.hpp>
+#include <SFML/Graphics/StencilMode.hpp>
 #include <SFML/Graphics/Text.hpp>
 #include <SFML/Graphics/Texture.hpp>
 #include <SFML/Graphics/Transform.hpp>

include/SFML/Graphics/RenderStates.hpp

@@ -31,6 +31,7 @@
 #include <SFML/Graphics/Export.hpp>
 #include <SFML/Graphics/BlendMode.hpp>
 #include <SFML/Graphics/Transform.hpp>
+#include <SFML/Graphics/StencilMode.hpp>
 
 
 namespace sf
@@ -53,6 +54,7 @@ public:
     /// to using sf::RenderStates::Default.
     /// The default set defines:
     /// \li the BlendAlpha blend mode
+    /// \li the default StencilMode (no stencil)
     /// \li the identity transform
     /// \li a null texture
     /// \li a null shader
@@ -68,6 +70,14 @@ public:
     ////////////////////////////////////////////////////////////
     RenderStates(const BlendMode& theBlendMode);
 
+    ////////////////////////////////////////////////////////////
+    /// \brief Construct a default set of render states with a custom stencil mode
+    ///
+    /// \param theStencilMode Stencil mode to use
+    ///
+    ////////////////////////////////////////////////////////////
+    RenderStates(const StencilMode& theStencilMode);
+
     ////////////////////////////////////////////////////////////
     /// \brief Construct a default set of render states with a custom transform
     ///
@@ -93,7 +103,7 @@ public:
     RenderStates(const Shader* theShader);
 
     ////////////////////////////////////////////////////////////
-    /// \brief Construct a set of render states with all its attributes
+    /// \brief Construct a set of render states with most of its attributes
     ///
     /// \param theBlendMode Blend mode to use
     /// \param theTransform Transform to use
@@ -104,6 +114,19 @@ public:
     RenderStates(const BlendMode& theBlendMode, const Transform& theTransform,
                  const Texture* theTexture, const Shader* theShader);
 
+    ////////////////////////////////////////////////////////////
+    /// \brief Construct a set of render states with all its attributes
+    ///
+    /// \param theBlendMode       Blend mode to use
+    /// \param theStencilMode     Stencil mode to use
+    /// \param theTransform       Transform to use
+    /// \param theTexture         Texture to use
+    /// \param theShader          Shader to use
+    ///
+    ////////////////////////////////////////////////////////////
+    RenderStates(const BlendMode& theBlendMode, const StencilMode& theStencilMode, 
+                 const Transform& theTransform, const Texture* theTexture, const Shader* theShader);
+
     ////////////////////////////////////////////////////////////
     // Static member data
     ////////////////////////////////////////////////////////////
@@ -112,10 +135,11 @@ public:
     ////////////////////////////////////////////////////////////
     // Member data
     ////////////////////////////////////////////////////////////
-    BlendMode      blendMode; ///< Blending mode
-    Transform      transform; ///< Transform
-    const Texture* texture;   ///< Texture
-    const Shader*  shader;    ///< Shader
+    BlendMode       blendMode;       ///< Blending mode
+    StencilMode     stencilMode;     ///< Stencil mode
+    Transform       transform;       ///< Transform
+    const Texture*  texture;         ///< Texture
+    const Shader*   shader;          ///< Shader
 };
 
 } // namespace sf

include/SFML/Graphics/RenderTarget.hpp

@@ -38,6 +38,7 @@
 #include <SFML/Graphics/PrimitiveType.hpp>
 #include <SFML/Graphics/Vertex.hpp>
 #include <SFML/System/NonCopyable.hpp>
+#include <SFML/Graphics/StencilMode.hpp>
 
 
 namespace sf
@@ -70,6 +71,29 @@ public:
     ////////////////////////////////////////////////////////////
     void clear(const Color& color = Color(0, 0, 0, 255));
 
+    ////////////////////////////////////////////////////////////
+    /// \brief Clear the stencil buffer to a specific value
+    ///
+    /// The specified value is truncated to the bit width of
+    /// the current stencil buffer.
+    ///
+    /// \param value Stencil value to clear to
+    ///
+    ////////////////////////////////////////////////////////////
+    void clear(unsigned int value);
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Clear the entire target with a single color and stencil value
+    ///
+    /// The specified stencil value is truncated to the bit
+    /// width of the current stencil buffer.
+    ///
+    /// \param color Fill color to use to clear the render target
+    /// \param value Stencil value to clear to
+    ///
+    ////////////////////////////////////////////////////////////
+    void clear(const Color& color, unsigned int value);
+
     ////////////////////////////////////////////////////////////
     /// \brief Change the current active view
     ///
@@ -399,6 +423,14 @@ private:
     ////////////////////////////////////////////////////////////
     void applyBlendMode(const BlendMode& mode);
 
+    ////////////////////////////////////////////////////////////
+    /// \brief Apply a new stencil mode
+    ///
+    /// \param mode Stencil mode to apply
+    ///
+    ////////////////////////////////////////////////////////////
+    void applyStencilMode(const StencilMode& mode);
+
     ////////////////////////////////////////////////////////////
     /// \brief Apply a new transform
     ///
@@ -458,14 +490,16 @@ private:
     {
         enum {VertexCacheSize = 4};
 
-        bool      enable;         ///< Is the cache enabled?
-        bool      glStatesSet;    ///< Are our internal GL states set yet?
-        bool      viewChanged;    ///< Has the current view changed since last draw?
-        BlendMode lastBlendMode;  ///< Cached blending mode
-        Uint64    lastTextureId;  ///< Cached texture
-        bool      texCoordsArrayEnabled; ///< Is GL_TEXTURE_COORD_ARRAY client state enabled?
-        bool      useVertexCache; ///< Did we previously use the vertex cache?
-        Vertex    vertexCache[VertexCacheSize]; ///< Pre-transformed vertices cache
+        bool        enable;                       ///< Is the cache enabled?
+        bool        glStatesSet;                  ///< Are our internal GL states set yet?
+        bool        viewChanged;                  ///< Has the current view changed since last draw?
+        bool        stencilEnabled;               ///< Is stencil testing enabled?
+        BlendMode   lastBlendMode;                ///< Cached blending mode
+        StencilMode lastStencilMode;              ///< Cached stencil
+        Uint64      lastTextureId;                ///< Cached texture
+        bool        texCoordsArrayEnabled;        ///< Is GL_TEXTURE_COORD_ARRAY client state enabled?
+        bool        useVertexCache;               ///< Did we previously use the vertex cache?
+        Vertex      vertexCache[VertexCacheSize]; ///< Pre-transformed vertices cache
     };
 
     ////////////////////////////////////////////////////////////

include/SFML/Graphics/StencilMode.hpp

@@ -0,0 +1,210 @@
+////////////////////////////////////////////////////////////
+//
+// SFML - Simple and Fast Multimedia Library
+// Copyright (C) 2007-2018 Laurent Gomila (laurent@sfml-dev.org)
+//
+// This software is provided 'as-is', without any express or implied warranty.
+// In no event will the authors be held liable for any damages arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it freely,
+// subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented;
+//    you must not claim that you wrote the original software.
+//    If you use this software in a product, an acknowledgment
+//    in the product documentation would be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such,
+//    and must not be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source distribution.
+//
+////////////////////////////////////////////////////////////
+
+#ifndef SFML_STENCILMODE_HPP
+#define SFML_STENCILMODE_HPP
+
+////////////////////////////////////////////////////////////
+// Headers
+////////////////////////////////////////////////////////////
+#include <SFML/Graphics/Export.hpp>
+
+
+namespace sf
+{
+
+////////////////////////////////////////////////////////////
+/// \brief Stencil modes for drawing
+///
+////////////////////////////////////////////////////////////
+struct SFML_GRAPHICS_API StencilMode
+{
+    ////////////////////////////////////////////////////////
+    /// \brief Enumeration of the stencil test comparisons that can be performed
+    ///
+    /// The comparisons are mapped directly to their OpenGL equivalents,
+    /// specified by glStencilFunc().
+    ////////////////////////////////////////////////////////
+    enum Comparison
+    {
+        Never,        ///< The stencil test never passes
+        Less,         ///< The stencil test passes if the new value is less than the value in the stencil buffer
+        LessEqual,    ///< The stencil test passes if the new value is less than or equal to the value in the stencil buffer
+        Greater,      ///< The stencil test passes if the new value is greater than the value in the stencil buffer
+        GreaterEqual, ///< The stencil test passes if the new value is greater than or equal to the value in the stencil buffer
+        Equal,        ///< The stencil test passes if the new value is strictly equal to the value in the stencil buffer
+        NotEqual,     ///< The stencil test passes if the new value is strictly inequal to the value in the stencil buffer
+        Always        ///< The stencil test always passes
+    };
+
+    ////////////////////////////////////////////////////////
+    /// \brief Enumeration of the stencil buffer update operations
+    ///
+    /// The update operations are mapped directly to their OpenGL equivalents,
+    /// specified by glStencilOp().
+    ////////////////////////////////////////////////////////
+    enum UpdateOperation
+    {
+        Keep,      ///< If the stencil test passes, the value in the stencil buffer is not modified
+        Zero,      ///< If the stencil test passes, the value in the stencil buffer is set to zero
+        Replace,   ///< If the stencil test passes, the value in the stencil buffer is set to the new value
+        Increment, ///< If the stencil test passes, the value in the stencil buffer is incremented and if required clamped
+        Decrement, ///< If the stencil test passes, the value in the stencil buffer is decremented and if required clamped
+        Invert,    ///< If the stencil test passes, the value in the stencil buffer is bitwise inverted
+    };
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Default constructor
+    ///
+    /// Constructs a stencil mode that disables stencil testing
+    ///
+    ////////////////////////////////////////////////////////////
+    StencilMode();
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Construct a stencil mode given the function, operation and reference value.
+    ///
+    /// \param stencilFunction  Specifies the kind of test to perform against the value in the stencil buffer
+    /// \param stencilOperation Specifies how the stencil buffer is updated if the test passes
+    /// \param stencilReference Specifies the reference value to perform the stencil test with and to write into stencil buffer if the operation is Replace and the test passes
+    /// \param stencilMask      Specifies the mask value to apply to both the reference value and the value in the stencil buffer when comparing and updating
+    /// \param stencilOnly      True to update only the stencil buffer, false to update both stencil and color buffers
+    ///
+    ////////////////////////////////////////////////////////////
+    StencilMode(Comparison stencilFunction, UpdateOperation stencilOperation, unsigned int stencilReference, unsigned int stencilMask, bool stencilOnly);
+
+    ////////////////////////////////////////////////////////////
+    // Member Data
+    ////////////////////////////////////////////////////////////
+    Comparison      stencilComparison;      ///< The comparison we're performing the stencil test with
+    UpdateOperation stencilUpdateOperation; ///< The update operation to perform if the stencil test passes
+    unsigned int    stencilReference;       ///< The reference value we're performing the stencil test with
+    unsigned int    stencilMask;            ///< 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
+};
+
+////////////////////////////////////////////////////////////
+/// \relates StencilMode
+/// \brief Overload of the == operator
+///
+/// \param left  Left operand
+/// \param right Right operand
+///
+/// \return True if stencil modes are equal, false if they are different
+///
+////////////////////////////////////////////////////////////
+SFML_GRAPHICS_API bool operator ==(const StencilMode& left, const StencilMode& right);
+
+////////////////////////////////////////////////////////////
+/// \relates StencilMode
+/// \brief Overload of the != operator
+///
+/// \param left  Left operand
+/// \param right Right operand
+///
+/// \return True if stencil modes are different, false if they are equal
+///
+////////////////////////////////////////////////////////////
+SFML_GRAPHICS_API bool operator !=(const StencilMode& left, const StencilMode& right);
+
+} // namespace sf
+
+
+#endif // SFML_STENCILMODE_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::StencilMode
+/// \ingroup graphics
+///
+/// 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 4 components, each of which has its
+/// own public member variable:
+/// \li Stencil Comparison (@ref stencilComparison)
+/// \li Stencil Update Operation (@ref stencilUpdateOperation)
+/// \li Stencil Reference Value (@ref stencilReference)
+/// \li Stencil Mask Value (@ref stencilMask)
+/// \li Stencil Only Update (@ref 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().
+///
+/// \see sf::RenderStates, sf::RenderTarget
+///
+////////////////////////////////////////////////////////////

src/SFML/Graphics/CMakeLists.txt

@@ -36,6 +36,8 @@ set(SRC
     ${INCROOT}/RenderWindow.hpp
     ${SRCROOT}/Shader.cpp
     ${INCROOT}/Shader.hpp
+    ${SRCROOT}/StencilMode.cpp
+    ${INCROOT}/StencilMode.hpp
     ${SRCROOT}/Texture.cpp
     ${INCROOT}/Texture.hpp
     ${SRCROOT}/TextureSaver.cpp

src/SFML/Graphics/RenderStates.cpp

@@ -34,44 +34,62 @@ namespace sf
 ////////////////////////////////////////////////////////////
 // We cannot use the default constructor here, because it accesses BlendAlpha, which is also global (and dynamically
 // initialized). Initialization order of global objects in different translation units is not defined.
-const RenderStates RenderStates::Default(BlendMode(
-    BlendMode::SrcAlpha, BlendMode::OneMinusSrcAlpha, BlendMode::Add,
-    BlendMode::One, BlendMode::OneMinusSrcAlpha, BlendMode::Add));
+// For similar reasons we need to provide the default stencil mode, and thus all other settings along with it
+const RenderStates RenderStates::Default(
+    BlendMode(BlendMode::SrcAlpha, BlendMode::OneMinusSrcAlpha, BlendMode::Add, BlendMode::One, BlendMode::OneMinusSrcAlpha, BlendMode::Add),
+    StencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+    Transform(),
+    NULL,
+    NULL);
 
 
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates() :
-blendMode(BlendAlpha),
-transform(),
-texture  (NULL),
-shader   (NULL)
+blendMode  (BlendAlpha),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+transform  (),
+texture    (NULL),
+shader     (NULL)
 {
 }
 
 
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates(const Transform& theTransform) :
-blendMode(BlendAlpha),
-transform(theTransform),
-texture  (NULL),
-shader   (NULL)
+blendMode  (BlendAlpha),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+transform  (theTransform),
+texture    (NULL),
+shader     (NULL)
 {
 }
 
 
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates(const BlendMode& theBlendMode) :
-blendMode(theBlendMode),
-transform(),
-texture  (NULL),
-shader   (NULL)
+blendMode  (theBlendMode),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+transform  (),
+texture    (NULL),
+shader     (NULL)
 {
 }
 
 
+////////////////////////////////////////////////////////////
+RenderStates::RenderStates(const StencilMode& theStencilMode) :
+blendMode  (BlendAlpha),
+stencilMode(theStencilMode),
+transform  (),
+texture    (NULL),
+shader     (NULL)
+{}
+
+
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates(const Texture* theTexture) :
 blendMode(BlendAlpha),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
 transform(),
 texture  (theTexture),
 shader   (NULL)
@@ -81,10 +99,11 @@ shader   (NULL)
 
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates(const Shader* theShader) :
-blendMode(BlendAlpha),
-transform(),
-texture  (NULL),
-shader   (theShader)
+blendMode  (BlendAlpha),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+transform  (),
+texture    (NULL),
+shader     (theShader)
 {
 }
 
@@ -92,11 +111,23 @@ shader   (theShader)
 ////////////////////////////////////////////////////////////
 RenderStates::RenderStates(const BlendMode& theBlendMode, const Transform& theTransform,
                            const Texture* theTexture, const Shader* theShader) :
-blendMode(theBlendMode),
-transform(theTransform),
-texture  (theTexture),
-shader   (theShader)
+blendMode  (theBlendMode),
+stencilMode(StencilMode::Always, StencilMode::Keep, 0, ~0, false),
+transform  (theTransform),
+texture    (theTexture),
+shader     (theShader)
 {
 }
 
+
+////////////////////////////////////////////////////////////
+RenderStates::RenderStates(const BlendMode& theBlendMode, const StencilMode& theStencilMode,
+                           const Transform& theTransform, const Texture* theTexture, const Shader* theShader) :
+blendMode  (theBlendMode),
+stencilMode(theStencilMode),
+transform  (theTransform),
+texture    (theTexture),
+shader     (theShader)
+{}
+
 } // namespace sf

src/SFML/Graphics/RenderTarget.cpp

@@ -104,7 +104,6 @@ namespace
         return GL_ZERO;
     }
 
-
     // Convert an sf::BlendMode::BlendEquation constant to the corresponding OpenGL constant.
     sf::Uint32 equationToGlConstant(sf::BlendMode::Equation blendEquation)
     {
@@ -119,6 +118,44 @@ namespace
         assert(false);
         return GLEXT_GL_FUNC_ADD;
     }
+
+    // Convert an UpdateOperation constant to the corresponding OpenGL constant.
+    sf::Uint32 stencilOperationToGlConstant(sf::StencilMode::UpdateOperation operation)
+    {
+        switch (operation)
+        {
+            case sf::StencilMode::Keep:      return GL_KEEP;
+            case sf::StencilMode::Zero:      return GL_ZERO;
+            case sf::StencilMode::Replace:   return GL_REPLACE;
+            case sf::StencilMode::Increment: return GL_INCR;
+            case sf::StencilMode::Decrement: return GL_INCR;
+            case sf::StencilMode::Invert:    return GL_INVERT;
+        }
+
+        sf::err() << "Invalid value for sf::StencilMode::UpdateOperation! Fallback to sf::StencilMode::Keep." << std::endl;
+        assert(false);
+        return GL_KEEP;
+    }
+
+    // Convert a Comparison constant to the corresponding OpenGL constant.
+    sf::Uint32 stencilFunctionToGlConstant(sf::StencilMode::Comparison comparison)
+    {
+        switch (comparison)
+        {
+            case sf::StencilMode::Never:        return GL_NEVER;
+            case sf::StencilMode::Less:         return GL_EQUAL;
+            case sf::StencilMode::LessEqual:    return GL_LEQUAL;
+            case sf::StencilMode::Greater:      return GL_GREATER;
+            case sf::StencilMode::GreaterEqual: return GL_GEQUAL;
+            case sf::StencilMode::Equal:        return GL_EQUAL;
+            case sf::StencilMode::NotEqual:     return GL_NOTEQUAL;
+            case sf::StencilMode::Always:       return GL_ALWAYS;
+        }
+
+        sf::err() << "Invalid value for sf::StencilMode::Comparison! Fallback to sf::StencilMode::Always." << std::endl;
+        assert(false);
+        return GL_ALWAYS;
+    }
 }
 
 
@@ -155,6 +192,35 @@ void RenderTarget::clear(const Color& color)
 }
 
 
+////////////////////////////////////////////////////////////
+void RenderTarget::clear(unsigned int value)
+{
+    if (isActive(m_id) || setActive(true))
+    {
+        // Unbind texture to fix RenderTexture preventing clear
+        applyTexture(NULL);
+
+        glCheck(glClearStencil(value));
+        glCheck(glClear(GL_STENCIL_BUFFER_BIT));
+    }
+}
+
+
+////////////////////////////////////////////////////////////
+void RenderTarget::clear(const Color& color, unsigned int value)
+{
+    if (isActive(m_id) || setActive(true))
+    {
+        // Unbind texture to fix RenderTexture preventing clear
+        applyTexture(NULL);
+
+        glCheck(glClearColor(color.r / 255.f, color.g / 255.f, color.b / 255.f, color.a / 255.f));
+        glCheck(glClearStencil(value));
+        glCheck(glClear(GL_COLOR_BUFFER_BIT | GL_STENCIL_BUFFER_BIT));
+    }
+}
+
+
 ////////////////////////////////////////////////////////////
 void RenderTarget::setView(const View& view)
 {
@@ -506,6 +572,7 @@ void RenderTarget::resetGLStates()
         // Define the default OpenGL states
         glCheck(glDisable(GL_CULL_FACE));
         glCheck(glDisable(GL_LIGHTING));
+        glCheck(glDisable(GL_STENCIL_TEST));
         glCheck(glDisable(GL_DEPTH_TEST));
         glCheck(glDisable(GL_ALPHA_TEST));
         glCheck(glEnable(GL_TEXTURE_2D));
@@ -515,10 +582,13 @@ void RenderTarget::resetGLStates()
         glCheck(glEnableClientState(GL_VERTEX_ARRAY));
         glCheck(glEnableClientState(GL_COLOR_ARRAY));
         glCheck(glEnableClientState(GL_TEXTURE_COORD_ARRAY));
+        glCheck(glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE));
+        m_cache.stencilEnabled = false;
         m_cache.glStatesSet = true;
 
         // Apply the default SFML states
         applyBlendMode(BlendAlpha);
+        applyStencilMode(StencilMode());
         applyTexture(NULL);
         if (shaderAvailable)
             applyShader(NULL);
@@ -621,6 +691,36 @@ void RenderTarget::applyBlendMode(const BlendMode& mode)
 }
 
 
+////////////////////////////////////////////////////////////
+void RenderTarget::applyStencilMode(const StencilMode& mode)
+{
+    // Fast path if we have a default (disabled) stencil mode
+    if (mode == StencilMode())
+    {
+        if (m_cache.stencilEnabled)
+        {
+            glCheck(glDisable(GL_STENCIL_TEST));
+            glCheck(glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE));
+
+            m_cache.stencilEnabled = false;
+        }
+    }
+    else
+    {
+        // Apply the stencil mode
+        if (!m_cache.stencilEnabled)
+            glCheck(glEnable(GL_STENCIL_TEST));
+
+        glCheck(glStencilOp(GL_KEEP, stencilOperationToGlConstant(mode.stencilUpdateOperation), stencilOperationToGlConstant(mode.stencilUpdateOperation)));
+        glCheck(glStencilFunc(stencilFunctionToGlConstant(mode.stencilComparison), mode.stencilReference, mode.stencilMask));
+
+        m_cache.stencilEnabled = true;
+    }
+
+    m_cache.lastStencilMode = mode;
+}
+
+
 ////////////////////////////////////////////////////////////
 void RenderTarget::applyTransform(const Transform& transform)
 {
@@ -675,6 +775,14 @@ void RenderTarget::setupDraw(bool useVertexCache, const RenderStates& states)
     if (!m_cache.enable || (states.blendMode != m_cache.lastBlendMode))
         applyBlendMode(states.blendMode);
 
+    // Apply the stencil mode
+    if (!m_cache.enable || (states.stencilMode != m_cache.lastStencilMode))
+        applyStencilMode(states.stencilMode);
+
+    // Mask the color buffer off if necessary
+    if (states.stencilMode.stencilOnly)
+        glCheck(glColorMask(GL_FALSE, GL_FALSE, GL_FALSE, GL_FALSE));
+
     // Apply the texture
     if (!m_cache.enable || (states.texture && states.texture->m_fboAttachment))
     {
@@ -724,6 +832,10 @@ void RenderTarget::cleanupDraw(const RenderStates& states)
     if (states.texture && states.texture->m_fboAttachment)
         applyTexture(NULL);
 
+    // Mask the color buffer back on if necessary
+    if (states.stencilMode.stencilOnly)
+        glCheck(glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE));
+
     // Re-enable the cache at the end of the draw if it was disabled
     m_cache.enable = true;
 }

src/SFML/Graphics/StencilMode.cpp

@@ -0,0 +1,75 @@
+////////////////////////////////////////////////////////////
+//
+// SFML - Simple and Fast Multimedia Library
+// Copyright (C) 2007-2015 Laurent Gomila (laurent@sfml-dev.org)
+//
+// This software is provided 'as-is', without any express or implied warranty.
+// In no event will the authors be held liable for any damages arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it freely,
+// subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented;
+//    you must not claim that you wrote the original software.
+//    If you use this software in a product, an acknowledgment
+//    in the product documentation would be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such,
+//    and must not be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source distribution.
+//
+////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////
+// Headers
+////////////////////////////////////////////////////////////
+#include <SFML/Graphics/StencilMode.hpp>
+
+
+namespace sf
+{
+////////////////////////////////////////////////////////////
+StencilMode::StencilMode() :
+stencilComparison     (StencilMode::Always),
+stencilUpdateOperation(StencilMode::Keep),
+stencilReference      (0),
+stencilMask           (~0),
+stencilOnly           (false)
+{
+
+}
+
+
+////////////////////////////////////////////////////////////
+StencilMode::StencilMode(Comparison stencilComparison, UpdateOperation stencilUpdateOperation,
+                         unsigned int stencilReference, unsigned int stencilMask, bool stencilOnly) :
+stencilComparison     (stencilComparison),
+stencilUpdateOperation(stencilUpdateOperation),
+stencilReference      (stencilReference),
+stencilMask           (stencilMask),
+stencilOnly           (stencilOnly)
+{
+
+}
+
+
+////////////////////////////////////////////////////////////
+bool operator ==(const StencilMode& left, const StencilMode& right)
+{
+    return (left.stencilUpdateOperation == right.stencilUpdateOperation) &&
+           (left.stencilComparison      == right.stencilComparison)      &&
+           (left.stencilReference       == right.stencilReference)       &&
+           (left.stencilMask            == right.stencilMask)            &&
+           (left.stencilOnly            == right.stencilOnly);
+}
+
+
+////////////////////////////////////////////////////////////
+bool operator !=(const StencilMode& left, const StencilMode& right)
+{
+    return !(left == right);
+}
+
+} // namespace sf