Quick search

Table Of Contents

Context instructions

The context instructions represent non graphics elements such as:

  • Matrix manipulations (PushMatrix, PopMatrix, Rotate, Translate, Scale, MatrixInstruction)
  • Color manipulations (Color)
  • Texture bindings (BindTexture)

Changed in version 1.0.8: The LineWidth instruction has been removed. It wasn’t working before and we actually have no working implementation. We need to do more experimentation to get it right. Check the bug #207 for more information.

class kivy.graphics.context_instructions.Color

Bases: kivy.graphics.instructions.ContextInstruction

Instruction to set the color state for any vertices being drawn after it.

This represents a color between 0 and 1, but is applied as a multiplier to the texture of any vertex instructions following it in a canvas. If no texture is set, the vertex instruction takes the precise color of the Color instruction.

For instance, if a Rectangle has a texture with uniform color (0.5, 0.5, 0.5, 1.0) and the preceding Color has rgba=(1, 0.5, 2, 1), the actual visible color will be (0.5, 0.25, 1.0, 1.0) since the Color instruction is applied as a multiplier to every rgba component. In this case, a Color component outside the 0-1 range gives a visible result as the intensity of the blue component is doubled.

To declare a Color in Python, you can do:

from kivy.graphics import Color

# create red v
c = Color(1, 0, 0)
# create blue color
c = Color(0, 1, 0)
# create blue color with 50% alpha
c = Color(0, 1, 0, .5)

# using hsv mode
c = Color(0, 1, 1, mode='hsv')
# using hsv mode + alpha
c = Color(0, 1, 1, .2, mode='hsv')

You can also set color components that are available as properties by passing them as keyword arguments:

c = Color(b=0.5)  # sets the blue component only

In kv lang you can set the color properties directly:

<Rule>:
    canvas:
        # red color
        Color:
            rgb: 1, 0, 0
        # blue color
        Color:
            rgb: 0, 1, 0
        # blue color with 50% alpha
        Color:
            rgba: 0, 1, 0, .5

        # using hsv mode
        Color:
            hsv: 0, 1, 1
        # using hsv mode + alpha
        Color:
            hsv: 0, 1, 1
            a: .5
a

Alpha component, between 0 and 1.

b

Blue component, between 0 and 1.

g

Green component, between 0 and 1.

h

Hue component, between 0 and 1.

hsv

HSV color, list of 3 values in 0-1 range, alpha will be 1.

r

Red component, between 0 and 1.

rgb

RGB color, list of 3 values in 0-1 range. The alpha will be 1.

rgba

RGBA color, list of 4 values in 0-1 range.

s

Saturation component, between 0 and 1.

v

Value component, between 0 and 1.

class kivy.graphics.context_instructions.BindTexture

Bases: kivy.graphics.instructions.ContextInstruction

BindTexture Graphic instruction. The BindTexture Instruction will bind a texture and enable GL_TEXTURE_2D for subsequent drawing.

Parameters:
texture: Texture

Specifies the texture to bind to the given index.

source

Set/get the source (filename) to load for the texture.

class kivy.graphics.context_instructions.PushMatrix

Bases: kivy.graphics.instructions.ContextInstruction

Push the matrix onto the context’s matrix stack.

stack

Name of the matrix stack to use. Can be ‘modelview_mat’, ‘projection_mat’ or ‘frag_modelview_mat’.

New in version 1.6.0.

class kivy.graphics.context_instructions.PopMatrix

Bases: kivy.graphics.instructions.ContextInstruction

Pop the matrix from the context’s matrix stack onto the model view.

stack

Name of the matrix stack to use. Can be ‘modelview_mat’, ‘projection_mat’ or ‘frag_modelview_mat’.

New in version 1.6.0.

class kivy.graphics.context_instructions.Rotate

Bases: kivy.graphics.context_instructions.Transform

Rotate the coordinate space by applying a rotation transformation on the modelview matrix. You can set the properties of the instructions afterwards with e.g.

rot.angle = 90
rot.axis = (0, 0, 1)
angle

Property for getting/setting the angle of the rotation.

axis

Property for getting/setting the axis of the rotation.

The format of the axis is (x, y, z).

origin

Origin of the rotation.

New in version 1.7.0.

The format of the origin can be either (x, y) or (x, y, z).

set()

Set the angle and axis of rotation.

>>> rotationobject.set(90, 0, 0, 1)

Deprecated since version 1.7.0: The set() method doesn’t use the new origin property.

class kivy.graphics.context_instructions.Scale

Bases: kivy.graphics.context_instructions.Transform

Instruction to create a non uniform scale transformation.

Create using one or three arguments:

Scale(s)         # scale all three axes the same
Scale(x, y, z)   # scale the axes independently

Deprecated since version 1.6.0: Deprecated single scale property in favor of x, y, z, xyz axis independent scaled factors.

origin

Origin of the scale.

New in version 1.9.0.

The format of the origin can be either (x, y) or (x, y, z).

scale

Property for getting/setting the scale.

Deprecated since version 1.6.0: Deprecated in favor of per axis scale properties x,y,z, xyz, etc.

x

Property for getting/setting the scale on the X axis.

Changed in version 1.6.0.

xyz

3 tuple scale vector in 3D in x, y, and z axis.

Changed in version 1.6.0.

y

Property for getting/setting the scale on the Y axis.

Changed in version 1.6.0.

z

Property for getting/setting the scale on Z axis.

Changed in version 1.6.0.

class kivy.graphics.context_instructions.Translate

Bases: kivy.graphics.context_instructions.Transform

Instruction to create a translation of the model view coordinate space.

Construct by either:

Translate(x, y)         # translate in just the two axes
Translate(x, y, z)      # translate in all three axes
x

Property for getting/setting the translation on the X axis.

xy

2 tuple with translation vector in 2D for x and y axis.

xyz

3 tuple translation vector in 3D in x, y, and z axis.

y

Property for getting/setting the translation on the Y axis.

z

Property for getting/setting the translation on the Z axis.

class kivy.graphics.context_instructions.MatrixInstruction

Bases: kivy.graphics.instructions.ContextInstruction

Base class for Matrix Instruction on the canvas.

matrix

Matrix property. Matrix from the transformation module. Setting the matrix using this property when a change is made is important because it will notify the context about the update.

stack

Name of the matrix stack to use. Can be ‘modelview_mat’, ‘projection_mat’ or ‘frag_modelview_mat’.

New in version 1.6.0.