Version

Quick search

Table Of Contents

Stencil instructions

New in version 1.0.4.

Changed in version 1.3.0: The stencil operation has been updated to resolve some issues that appeared when nested. You must now have a StencilUnUse and repeat the same operation as you did after StencilPush.

Stencil instructions permit you to draw and use the current drawing as a mask. They don’t give as much control as pure OpenGL, but you can still do fancy things!

The stencil buffer can be controlled using these 3 instructions:

  • StencilPush: push a new stencil layer. Any drawing that happens after this will be used as a mask.

  • StencilUse : now draw the next instructions and use the stencil for masking them.

  • StencilUnUse : stop using the stencil i.e. remove the mask and draw normally.

  • StencilPop : pop the current stencil layer.

You should always respect this scheme:

StencilPush

# PHASE 1: put any drawing instructions to use as a mask here.

StencilUse

# PHASE 2: all the drawing here will be automatically clipped by the
# mask created in PHASE 1.

StencilUnUse

# PHASE 3: put the same drawing instruction here as you did in PHASE 1

StencilPop

# PHASE 4: the stencil is now removed from the stack and unloaded.

Limitations

  • Drawing in PHASE 1 and PHASE 3 must not collide or you will get unexpected results

  • The stencil is activated as soon as you perform a StencilPush

  • The stencil is deactivated as soon as you’ve correctly popped all the stencil layers

  • You must not play with stencils yourself between a StencilPush / StencilPop

  • You can push another stencil after a StencilUse / before the StencilPop

  • You can push up to 128 layers of stencils (8 for kivy < 1.3.0)

Example of stencil usage

Here is an example, in kv style:

StencilPush

# create a rectangular mask with a pos of (100, 100) and a (100, 100) size.
Rectangle:
    pos: 100, 100
    size: 100, 100

StencilUse

# we want to show a big green rectangle, however, the previous stencil
# mask will crop us :)
Color:
    rgb: 0, 1, 0
Rectangle:
    size: 900, 900

StencilUnUse

# you must redraw the stencil mask to remove it
Rectangle:
    pos: 100, 100
    size: 100, 100

StencilPop
class kivy.graphics.stencil_instructions.StencilPop

Bases: kivy.graphics.instructions.Instruction

Pop the stencil stack. See the module documentation for more information.

class kivy.graphics.stencil_instructions.StencilPush(**kwargs)

Bases: kivy.graphics.instructions.Instruction

information.

clear_stencil

clear_stencil allow to disable stencil clearing in the StencilPush phase. This option essentially disables the invocation of the functions cgl.glClearStencil(0) and cgl.glClear(GL_STENCIL_BUFFER_BIT).

If True, the stencil will be cleaned in the StencilPush phase, if False, it will not be cleaned.

Note

It is highly recommended to set clear_stencil=False for improved performance and reduced GPU usage (especially if there are hundreds of instructions). However, if any side effects (such as artifacts or inaccurate behavior of StencilPush) occur, it is advisable to re-enable the clearing instructions with clear_stencil=True.

New in version 2.3.0.

class kivy.graphics.stencil_instructions.StencilUnUse

Bases: kivy.graphics.instructions.Instruction

Use current stencil buffer to unset the mask.

class kivy.graphics.stencil_instructions.StencilUse(**kwargs)

Bases: kivy.graphics.instructions.Instruction

more information.

func_op

Determine the stencil operation to use for glStencilFunc(). Can be one of ‘never’, ‘less’, ‘equal’, ‘lequal’, ‘greater’, ‘notequal’, ‘gequal’ or ‘always’.

By default, the operator is set to ‘equal’.

New in version 1.5.0.

« Shader SVG »