stencil: add a python property to change the func_op of the StencilUse. Plus add the documentation for it. refs #790

kivy/graphics/stencil_instructions.pyx

@@ -101,6 +101,23 @@ from instructions cimport Instruction
 cdef int _stencil_level = 0
 cdef int _stencil_in_push = 0
 
+
+cdef dict _gl_stencil_op = {
+    'never': GL_NEVER, 'less': GL_LESS, 'equal': GL_EQUAL,
+    'lequal': GL_LEQUAL, 'greater': GL_GREATER, 'notequal': GL_NOTEQUAL,
+    'gequal': GL_GEQUAL, 'always': GL_ALWAYS }
+
+
+cdef inline int _stencil_op_to_gl(x):
+    '''Return the GL numeric value from a stencil operator
+    '''
+    x = x.lower()
+    try:
+        return _gl_stencil_op[x]
+    except KeyError:
+        raise Exception('Unknow <%s> stencil op' % x)
+
+
 cdef class StencilPush(Instruction):
     '''Push the stencil stack. See module documentation for more information.
     '''
@@ -149,7 +166,11 @@ cdef class StencilUse(Instruction):
     '''
     def __init__(self, **kwargs):
         super(StencilUse, self).__init__(**kwargs)
-        self._op = kwargs.get('op') or GL_EQUAL
+        if 'op' in kwargs:
+            self._op = _stencil_op_to_gl(kwargs['op'])
+        else:
+            self._op = GL_EQUAL
+
     cdef void apply(self):
         global _stencil_in_push
         _stencil_in_push = 0
@@ -157,6 +178,27 @@ cdef class StencilUse(Instruction):
         glStencilFunc(self._op, _stencil_level, 0xff)
         glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP)
 
+    property func_op:
+        '''Determine the stencil operation to use for glStencilFunc(). Can be
+        one of 'never', 'less', 'equal', 'lequal', 'greater', 'notequal',
+        'gequal', 'always'.
+
+        By default, the operator is set to 'equal'.
+
+        .. versionadded:: 1.5.0
+        '''
+
+        def __get__(self):
+            index = _gl_stencil_op.values().index(self._op)
+            return _gl_stencil_op.keys()[index]
+
+        def __set__(self, x):
+            cdef int op = _stencil_op_to_gl(x)
+            if op != self._op:
+                self._op = op
+                self.flag_update()
+
+
 cdef class StencilUnUse(Instruction):
     '''Use current stencil buffer to unset the mask.
     '''