Table Of Contents
Vertex Instructions¶
This module includes all the classes for drawing simple vertex objects.
Note
The list attributes of the graphics instruction classes (e.g. Triangle.points, Mesh.indices etc.) are not Kivy properties, but Python properties. As a consequence, the graphics will only be updated when the list object itself is changed, but not when list values are modified.
For example in python:
class MyWidget(Button):
triangle = ObjectProperty(None)
def __init__(self, **kwargs):
super(MyWidget, self).__init__(**kwargs)
with self.canvas:
self.triangle = Triangle(points=[0,0, 100,100, 200,0])
and in kv:
<MyWidget>:
text: 'Update'
on_press:
self.triangle.points[3] = 400
Although when the button is pressed the triangle coordinates will be changed, the graphics will not be updated because the list itself is not changed. Similarly, no updates will occur if syntax e.g self.triangle.points[0:2] = [10,10] or self.triangle.points.insert(10) etc. is used. To force an update after a change, the list variable itself must be changed, which in this case can be achieved with:
<MyWidget>:
text: 'Update'
on_press:
self.triangle.points[3] = 400
self.triangle.points = self.triangle.points
- class kivy.graphics.vertex_instructions.Triangle¶
Bases: kivy.graphics.instructions.VertexInstruction
A 2d triangle.
Parameters: - points: list
List of points 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 quad.
- 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 a 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 and angle_end.
Parameters: - segments: int, defaults to 180
Define how many segments are needed for drawing the ellipse. The drawing will be smoother if you have many segments.
- angle_start: int, defaults to 0
Specifies the starting angle, in degrees, of the disk portion.
- angle_end: int, defaults to 360
Specifies the ending angle, in degrees, of the disk portion.
- angle_end¶
End angle of the ellipse in degrees, defaults to 360.
- angle_start¶
Start angle of the ellipse in degrees, defaults 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:
- 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.
- 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.
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, defaults to ‘round’
See cap for more information.
- joint: str, defaults to ‘round’
See joint for more information.
- cap_precision: int, defaults to 10
See cap_precision for more information
- joint_precision: int, defaults to 10
See joint_precision for more information
- close: bool, defaults 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, defaults 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, defaults to 180. The bezier_precision must be at least 1.
New in version 1.4.2.
- cap¶
Determine the cap of the line, defaults 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, defaults 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, defaults 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, defaults 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, defaults 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, defaults to 1.
Size of the point (1. means 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 entries 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 to the current points list.
If you intend to add multiple points, prefer to use this method instead of reassigning a new points list. Assigning a new points list will recalculate and reupload the whole buffer into the 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 for vertices is currently fixed but 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 triangle, add 3 vertices. You can then make an indices list as follows:
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. Defaults to ‘points’.
- indices¶
Vertex indices used to specify the order when drawing the mesh.
- mode¶
VBO Mode used for drawing vertices/indices. Can be one of ‘points’, ‘line_strip’, ‘line_loop’, ‘lines’, ‘triangle_strip’ or ‘triangle_fan’.
- vertices¶
List of x, y, u, v coordinates used to construct the Mesh. Right now, the Mesh instruction doesn’t allow you to change the format of the vertices, which means it’s only x, y + one texture coordinate.
- class kivy.graphics.vertex_instructions.GraphicException¶
Bases: exceptions.Exception
Exception raised when a graphics 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, defaults to 180
Define how many segments are needed for drawing the ellipse. The drawing will be smoother if you have many segments.
- loop: bool, defaults to False
Set the bezier curve to join last point to first.
- dash_length: int
Length of a segment (if dashed), defaults to 1.
- dash_offset: int
Distance between the end of a segment and the start of the next one, defaults to 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 the points of the triangle.
Warning
This will always reconstruct the whole graphic from the new points list. It can be very CPU expensive.
- segments¶
Property for getting/setting the number of segments of the curve.