Vertex Instructions

This module include all the classes for drawing simple vertex object.

class kivy.graphics.vertex_instructions.Triangle

Bases: kivy.graphics.instructions.VertexInstruction

A 2d triangle.

Parameters :
points: list

List of point in the format (x1, y1, x2, y2, x3, y3)

points

Property for getting/settings points of the triangle

class kivy.graphics.vertex_instructions.Quad

Bases: kivy.graphics.instructions.VertexInstruction

A 2d quad.

Parameters :
points: list

List of point in the format (x1, y1, x2, y2, x3, y3, x4, y4)

points

Property for getting/settings points of the quads

class kivy.graphics.vertex_instructions.Rectangle

Bases: kivy.graphics.instructions.VertexInstruction

A 2d rectangle.

Parameters :
pos: list

Position of the rectangle, in the format (x, y)

size: list

Size of the rectangle, in the format (width, height)

pos

Property for getting/settings the position of the rectangle

size

Property for getting/settings the size of the rectangle

class kivy.graphics.vertex_instructions.BorderImage

Bases: kivy.graphics.vertex_instructions.Rectangle

A 2d border image. The behavior of the border image is similar to the concept of CSS3 border-image.

Parameters :
border: list

Border information in the format (top, right, bottom, left). Each value is in pixels.

border

Property for getting/setting the border of the class

class kivy.graphics.vertex_instructions.Ellipse

Bases: kivy.graphics.vertex_instructions.Rectangle

A 2D ellipse.

New in version 1.0.7: added angle_start + angle_end

Parameters :
segments: int, default to 180

Define how much segment is needed for drawing the ellipse. The drawing will be smoother if you have lot of segment.

angle_start: int default to 0

Specifies the starting angle, in degrees, of the disk portion

angle_end: int default to 360

Specifies the ending angle, in degrees, of the disk portion

angle_end

Angle end of the ellipse in degrees, default to 360

angle_start

Angle start of the ellipse in degrees, default to 0

segments

Property for getting/setting the number of segments of the ellipse

class kivy.graphics.vertex_instructions.Line

Bases: kivy.graphics.instructions.VertexInstruction

A 2d line.

Drawing a line can be done easily:

with self.canvas:
    Line(points=[100, 100, 200, 100, 100, 200], width=10)

Actually, the line have 3 internal drawing mode that you should know about if you want to get the best performance of it:

  1. If the width is 1.0, then we will use standard GL_LINE drawing from OpenGL. dash_length and dash_offset works, while properties for cap and joint have no sense for this.
  2. If the width is > 1.0, then we will use a custom drawing method, based on triangles. dash_length and dash_offset is not working on that mode. Additionally, if the current color have an alpha < 1.0, stencil will be used internally to draw the line.
_images/line-instruction.png
Parameters :
points: list

List of points in the format (x1, y1, x2, y2...)

dash_length: int

Length of a segment (if dashed), default 1

dash_offset: int

Offset between the end of a segments and the begining of the next one, default 0, changing this makes it dashed.

width: float

Width of the line, default 1.0

cap: str, default to ‘round’

See cap for more information.

joint: str, default to ‘round’

See joint for more information.

cap_precision: int, default to 10

See cap_precision for more information

joint_precision: int, default to 10

See joint_precision for more information

close: bool, default to False

If True, the line will be closed.

circle: list

If set, the points will be set to build a circle. Check circle for more information.

ellipse: list

If set, the points will be set to build an ellipse. Check ellipse for more information.

rectangle: list

If set, the points will be set to build a rectangle. Check rectangle for more information.

bezier: list

If set, the points will be set to build a bezier line. Check bezier for more information.

bezier_precision: int, default to 180

Precision of the Bezier drawing.

New in version 1.0.8: dash_offset and dash_length have been added

New in version 1.4.1: width, cap, joint, cap_precision, joint_precision, close, ellipse, rectangle have been added.

New in version 1.4.1: bezier, bezier_precision have been added.

bezier

Use this property to build a bezier line, without calculating the points. You can only set this property, not get it.

The argument must be a tuple of 2n elements, n being the number of points.

Usage:

Line(bezier=(x1, y1, x2, y2, x3, y3)

New in version 1.4.2.

Note

Bezier lines calculations are inexpensive for a low number of points, but complexity is quadratic, so lines with a lot of points can be very expensive to build, use with care!

bezier_precision

Number of iteration for drawing the bezier between 2 segments, default to 180. The bezier_precision must be at least 1.

New in version 1.4.2.

cap

Determine the cap of the line, default to ‘round’. Can be one of ‘none’, ‘square’ or ‘round’

New in version 1.4.1.

cap_precision

Number of iteration for drawing the “round” cap, default to 10. The cap_precision must be at least 1.

New in version 1.4.1.

circle

Use this property to build a circle, without calculate the points. You can only set this property, not get it.

The argument must be a tuple of (center_x, center_y, radius, angle_start, angle_end, segments):

  • center_x and center_y represent the center of the circle

  • radius represent the radius of the circle

  • (optional) angle_start and angle_end are in degree. The default

    value is 0 and 360.

  • (optional) segments is the precision of the ellipse. The default

    value is calculated from the range between angle.

Note that it’s up to you to close the circle or not.

For example, for building a simple ellipse, in python:

# simple circle
Line(circle=(150, 150, 50))

# only from 90 to 180 degrees
Line(circle=(150, 150, 50, 90, 180))

# only from 90 to 180 degrees, with few segments
Line(circle=(150, 150, 50, 90, 180, 20))

New in version 1.4.1.

close

If True, the line will be closed.

New in version 1.4.1.

dash_length

Property for getting/setting the length of the dashes in the curve

New in version 1.0.8.

dash_offset

Property for getting/setting the offset between the dashes in the curve

New in version 1.0.8.

ellipse

Use this property to build an ellipse, without calculate the points. You can only set this property, not get it.

The argument must be a tuple of (x, y, width, height, angle_start, angle_end, segments):

  • x and y represent the bottom left of the ellipse

  • width and height represent the size of the ellipse

  • (optional) angle_start and angle_end are in degree. The default

    value is 0 and 360.

  • (optional) segments is the precision of the ellipse. The default

    value is calculated from the range between angle.

Note that it’s up to you to close the ellipse or not.

For example, for building a simple ellipse, in python:

# simple ellipse
Line(ellipse=(0, 0, 150, 150))

# only from 90 to 180 degrees
Line(ellipse=(0, 0, 150, 150, 90, 180))

# only from 90 to 180 degrees, with few segments
Line(ellipse=(0, 0, 150, 150, 90, 180, 20))

New in version 1.4.1.

joint

Determine the join of the line, default to ‘round’. Can be one of ‘none’, ‘round’, ‘bevel’, ‘miter’.

New in version 1.4.1.

joint_precision

Number of iteration for drawing the “round” joint, default to 10. The joint_precision must be at least 1.

New in version 1.4.1.

points

Property for getting/settings points of the line

Warning

This will always reconstruct the whole graphics from the new points list. It can be very CPU expensive.

rectangle

Use this property to build a rectangle, without calculating the points. You can only set this property, not get it.

The argument must be a tuple of (x, y, width, height) angle_end, segments):

  • x and y represent the bottom-left position of the rectangle
  • width and height represent the size

The line is automatically closed.

Usage:

Line(rectangle=(0, 0, 200, 200))

New in version 1.4.1.

width

Determine the width of the line, default to 1.0.

New in version 1.4.1.

class kivy.graphics.vertex_instructions.Point

Bases: kivy.graphics.instructions.VertexInstruction

A 2d line.

Parameters :
points: list

List of points in the format (x1, y1, x2, y2...)

pointsize: float, default to 1.

Size of the point (1. mean the real size will be 2)

Warning

Starting from version 1.0.7, vertex instruction have a limit of 65535 vertices (indices of vertex to be accurate). 2 entry in the list (x + y) will be converted to 4 vertices. So the limit inside Point() class is 2^15-2.

add_point()

Add a point into the current points list.

If you intend to add multiple point, prefer to use this method, instead of reassign a new points list. Assigning a new points list will recalculate and reupload the whole buffer into GPU. If you use add_point, it will only upload the changes.

points

Property for getting/settings points of the triangle

pointsize

Property for getting/setting point size

class kivy.graphics.vertex_instructions.Mesh

Bases: kivy.graphics.instructions.VertexInstruction

A 2d mesh.

The format of vertices are actually fixed, this might change in a future release. Right now, each vertex is described with 2D coordinates (x, y) and a 2D texture coordinate (u, v).

In OpenGL ES 2.0 and in our graphics implementation, you cannot have more than 65535 indices.

A list of vertices is described as:

vertices = [x1, y1, u1, v1, x2, y2, u2, v2, ...]
            |            |  |            |
            +---- i1 ----+  +---- i2 ----+

If you want to draw a triangles, put 3 vertices, then you can make an indices list as:

indices = [0, 1, 2]

New in version 1.1.0.

Parameters :
vertices: list

List of vertices in the format (x1, y1, u1, v1, x2, y2, u2, v2...)

indices: list

List of indices in the format (i1, i2, i3...)

mode: str

Mode of the vbo. Check mode for more information. Default to ‘points’.

indices

Vertex indices used to know which order you wanna do for drawing the mesh.

mode

VBO Mode used for drawing vertices/indices. Can be one of: ‘points’, ‘line_strip’, ‘line_loop’, ‘lines’, ‘triangle_strip’, ‘triangle_fan’

vertices

List of x, y, u, v, ... used to construct the Mesh. Right now, the Mesh instruction doesn’t allow you to change the format of the vertices, mean it’s only x/y + one texture coordinate.

class kivy.graphics.vertex_instructions.GraphicException

Bases: exceptions.Exception

Exception fired when a graphic error is fired.

class kivy.graphics.vertex_instructions.Bezier

Bases: kivy.graphics.instructions.VertexInstruction

A 2d Bezier curve.

New in version 1.0.8.

Parameters :
points: list

List of points in the format (x1, y1, x2, y2...)

segments: int, default to 180

Define how much segment is needed for drawing the ellipse. The drawing will be smoother if you have lot of segment.

loop: bool, default to False

Set the bezier curve to join last point to first.

dash_length: int

length of a segment (if dashed), default 1

dash_offset: int

distance between the end of a segment and the start of the next one, default 0, changing this makes it dashed.

dash_length

Property for getting/stting the length of the dashes in the curve

dash_offset

Property for getting/setting the offset between the dashes in the curve

points

Property for getting/settings points of the triangle

Warning

This will always reconstruct the whole graphics from the new points list. It can be very CPU expensive.

segments

Property for getting/setting the number of segments of the curve