顶点指令¶

该模块包含了所有用于绘制简单顶点对象的类。

更新属性¶

图形指令类（例如：Triangle.points、Mesh.indices 等）的列表属性并非 Kivy 属性，而是 Python 属性。因此，只有当列表对象本身被更改时，图形才会更新，而修改列表中的值则不会触发更新。

例如在 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])

以及在kv中：

<MyWidget>:
    text: 'Update'
    on_press:
        self.triangle.points[3] = 400

尽管按下按钮会改变三角形的坐标，但图形不会更新，因为列表本身没有发生变化。同样，任何仅修改列表元素的语法也不会触发更新，例如 self.triangle.points[0:2] = [10,10] 或 self.triangle.points.insert(10) 等。要在更改后强制更新，必须改变列表变量本身，在这种情况下可以通过以下方式实现：

<MyWidget>:
    text: 'Update'
    on_press:
        self.triangle.points[3] = 400
        self.triangle.points = self.triangle.points

class kivy.graphics.vertex_instructions.Bezier(**kwargs)¶

基类：VertexInstruction

在 1.0.8 版本加入.

参数:

points：列表: 格式为(x1, y1, x2, y2...)的点列表
segments：整数，默认值为180: 定义绘制曲线所需的线段数量。线段越多，绘制效果越平滑。
loop：布尔值，默认为 False: 将贝塞尔曲线设置为连接最后一个点与第一个点。
dash_length：整数: 线段长度（若为虚线），默认为1。
dash_offset：整数: 线段终点与下一线段起点之间的距离，默认为0。更改此值可使其呈现虚线效果。

dash_length¶: 用于获取/设置曲线中虚线段长度的属性。

dash_offset¶: 用于获取/设置曲线中虚线之间偏移量的属性。

points¶: 用于获取/设置三角形点的属性。

警告

这将始终根据新的点列表重建整个图形，可能会非常消耗CPU资源。

segments¶: 用于获取/设置曲线段数的属性。

class kivy.graphics.vertex_instructions.BorderImage(**kwargs)¶

基类：Rectangle

CSS3边框图像的概念。

参数:

border：列表

边框信息，格式为（底部，右侧，顶部，左侧）。每个值以像素为单位。

auto_scale：字符串

在 1.9.1 版本加入.

在 1.9.2 版本发生变更: 这原本是一个布尔值，现已改为字符串状态。

可为以下值之一：'off'、'both'、'x_only'、'y_only'、'y_full_x_lower'、'x_full_y_lower'、'both_lower'。

Autoscale 控制 9-slice 的行为。

默认情况下，边框值会被精确保留，这意味着如果对象的总尺寸小于边框值，你将会遇到一些“渲染错误”，此时纹理看起来会内外颠倒。这也使得无法实现一个比其源纹理尺寸更大的圆角按钮。auto_scale 的各种选项将允许你实现这两种渲染类型的混合效果。

'off'：默认值，行为与之前 auto_scale 为 False 时的 BorderImage 相同。

'both'：根据BorderImage的大小同时缩放x和y维度的边框，这会禁用BorderImage，使其渲染效果与普通Image相同。

'x_only'：Y 维度保持默认行为，而 X 维度则根据 BorderImage 的宽度进行缩放。

'y_only'：X 维度作为默认值，Y 则根据 BorderImage 的高度进行缩放。

'y_full_x_lower'：Y 的缩放方式与 'y_only' 相同，仅当缩放后的尺寸小于提供的边框时，Y 才进行缩放。

'x_full_y_lower'：X 的缩放方式与 'x_only' 相同，Y 仅在缩放后的大小小于提供的边框时才进行缩放。

'both_lower'：这是1.9.1版本中auto_scale为True时的行为。如果BorderImage小于源图像，则X和Y两个维度都将被缩放。

如果BorderImage的尺寸（水平或垂直方向）小于其边框之和，且此属性设置为True，则边框将被重新缩放以适应较小的尺寸。

auto_scale¶: 用于设置当BorderImage过小时是否自动缩放边角的属性。

border¶: 用于获取/设置类边框的属性。

display_border¶: 用于获取/设置边框显示尺寸的属性。

class kivy.graphics.vertex_instructions.Ellipse(*args, **kwargs)¶

基类：Rectangle

参数:

segments：整数，默认值根据角度之间的范围计算得出。: 定义绘制椭圆所需的线段数量。线段越多，椭圆绘制得越平滑，但您也可以利用此属性创建具有3条或更多边的多边形。
angle_start：浮点数，默认值为 0.0: 指定圆盘部分的起始角度，单位为度。
angle_end：浮点数，默认值为 360.0: 指定圆盘部分的结束角度，单位为度。

在 1.0.7 版本发生变更: 添加了angle_start和angle_end。

在 2.2.0 版本发生变更: 默认的线段数量不再是180，现在会根据角度范围进行计算，因为这是一种更高效的方法。

angle_end¶: 椭圆结束角度（以度为单位），默认为360。

angle_start¶: 椭圆起始角度，单位为度，默认值为0。

segments¶: 用于获取/设置椭圆段数的属性。如果段数较多，椭圆绘制将更加平滑，但您也可以利用此属性创建具有3条或更多边的多边形。小于3的值将不会被表示，段数将自动计算。

在 2.2.0 版本发生变更: 允许的最小段数为3。小于此值的设置将被忽略，段数将自动计算。

exception kivy.graphics.vertex_instructions.GraphicException¶

基类：Exception

当图形错误被触发时引发的异常。

class kivy.graphics.vertex_instructions.Line(**kwargs)¶

基类：VertexInstruction

绘制一条线可以轻松完成:

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

该线条有3种内部绘制模式，您应了解这些模式以获得最佳效果：

如果 width 为 1.0 且 force_custom_drawing_method 为 False，则将使用 OpenGL 中的标准 GL_LINE 绘制方式。此时，dash_length、dash_offset 和 dashes 属性将生效，而用于线帽和连接处的属性在此处没有意义。
如果 width 大于 1.0 或 force_custom_drawing_method 为 True，则将使用基于三角剖分的自定义绘制方法。在此模式下，dash_length、dash_offset 和 dashes 不起作用。此外，如果当前颜色的 alpha 值小于 1.0，则会在内部使用模板来绘制线条。

参数:

points：列表: 格式为(x1, y1, x2, y2...)的点列表
dash_length：整数: 线段长度（若为虚线），默认为1。
dash_offset：整数: 段与下一段开始之间的偏移量，默认为0。更改此值可使其呈现虚线效果。
dashes：整数列表: [ON长度，偏移量，ON长度，偏移量，...]的列表。例如，[2,4,1,6,8,2] 会创建一条线，其中第一个虚线段长度为2，然后偏移4，接着虚线段长度为1，再偏移6，依此类推。默认为 []。更改此属性会使线条变为虚线，并覆盖 dash_length 和 dash_offset。
width：浮点数: 线条宽度，默认为1.0。
cap: str，默认值为 'round': 更多信息请参阅 cap。
joint：字符串类型，默认为 'round': 更多信息请参阅 joint。
cap_precision：整数，默认值为10: 更多信息请参阅 cap_precision。
joint_precision：整数，默认值为10: 更多信息请参阅 joint_precision 和 cap_precision。
joint_precision：整数，默认值为10: 更多信息请参阅 joint_precision。
close：布尔值，默认为 False: 如果为 True，线条将被闭合。
circle：列表: 如果设置了该属性，points 将被设置为构建一个圆形。更多信息请参阅 circle。
ellipse：列表: 如果设置了该属性，points 将被设置为构建一个椭圆。更多信息请参阅 ellipse。
rectangle：列表: 如果设置，points 将被设置为构建一个矩形。更多信息请参阅 rectangle。
bezier：列表: 如果设置，points 将被设置为构建贝塞尔曲线。更多信息请参阅 bezier。
bezier_precision：整数，默认值为180: 贝塞尔曲线绘制的精度。
force_custom_drawing_method：布尔值，默认为 False: 如果使用自定义绘制方法，则不应再依赖 width 是否等于 1.0。

在 1.0.8 版本发生变更: dash_offset 和 dash_length 已被添加。

在 1.4.1 版本发生变更: 已添加 width、cap、joint、cap_precision、joint_precision、close、ellipse、rectangle 属性。

在 1.4.1 版本发生变更: bezier、bezier_precision 已被添加。

在 1.11.0 版本发生变更: dashes 已被添加。

在 2.3.0 版本发生变更: force_custom_drawing_method 已被添加。

bezier¶

使用此属性来构建贝塞尔曲线，无需计算 points。您只能设置此属性，不能获取它。

参数必须是一个包含2n个元素的元组，其中n为点的数量。

用法：：

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

在 1.4.2 版本加入.

备注

贝塞尔线的计算在点数较少时开销不大，但复杂度是二次方的，因此包含大量点的线条构建成本可能非常高，请谨慎使用！

bezier_precision¶: 两个线段之间绘制贝塞尔曲线的迭代次数，默认为180。bezier_precision 必须至少为1。

在 1.4.2 版本加入.

cap¶: 确定线条的端点样式，默认为“round”。可选值为“none”、“square”或“round”。

在 1.4.1 版本加入.

cap_precision¶: 绘制“圆”形端帽的迭代次数，默认为10。cap_precision 必须至少为1。

在 1.4.1 版本加入.

circle¶

使用此属性来构建圆形，无需计算 points。

参数必须是一个元组，格式为 (center_x, center_y, radius, angle_start, angle_end, segments)。

center_x 和 center_y 表示圆的中心。
radius 表示圆的半径。
（可选）angle_start 和 angle_end 以度为单位。默认值为 0 和 360。
（可选）segments 是椭圆的精度。默认值根据 angle 的范围计算得出。

请注意，是否要:attr:`close`（闭合）这个圆形，完全由您自己决定。

例如，要构建一个简单的椭圆，在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))

在 1.4.1 版本加入.

在 2.2.0 版本发生变更: 现在你可以通过该属性获取生成的圆形。

close¶: 如果为 True，则线条将根据 close_mode 属性将两端连接起来，从而闭合线条。

在 1.4.1 版本加入.

close_mode¶

定义线条端点如何连接。默认为 "straight-line"。

备注

不同关闭模式的支持取决于绘制形状的方式。

可用模式：

``"直线"``（所有绘制形状）：端点将由一条直线闭合。
``"center-connected"``（ellipse 特有）：两端将通过一条穿过椭圆中心的线闭合。

在 2.2.0 版本加入.

dash_length¶: 用于获取/设置曲线中虚线长度的属性。

在 1.0.8 版本加入.

dash_offset¶: 用于获取/设置曲线中虚线之间偏移量的属性。

在 1.0.8 版本加入.

dashes¶

用于获取/设置 dashes 的属性。

[ON长度，偏移量，ON长度，偏移量，...]的列表。例如，[2,4,1,6,8,2] 将创建一条线，其中第一个破折号长度为2，然后偏移量为4，接着破折号长度为1，再偏移量为6，以此类推。

在 1.11.0 版本加入.

ellipse¶

使用此属性来构建椭圆，无需计算 points。

参数必须是一个包含 (x, y, width, height, angle_start, angle_end, segments) 的元组。

x 和 y 表示椭圆左下角的位置。
width 和 height 表示椭圆的大小。
（可选）angle_start 和 angle_end 以度为单位。默认值为 0 和 360。
（可选）segments 是椭圆的精度。默认值根据 angle 的范围计算得出。您可以使用此属性创建具有 3 条或更多边的多边形。小于 3 的值将不会被表示，且段数将自动计算。

请注意，是否调用 close 由您决定。如果您选择关闭图形，请使用 close_mode 来定义图形的闭合方式，即通过 ``"straight-line"``（直线连接）或 ``"center-connected"``（中心连接）来闭合。

例如，要构建一个简单的椭圆，在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))

在 1.4.1 版本加入.

在 2.2.0 版本发生变更: 现在你可以通过该属性获取生成的椭圆。

允许的最小段数为3。小于此值的设置将被忽略，段数将自动计算。

force_custom_drawing_method¶: 如果为 True，无论宽度如何，线条都将使用自定义绘制方法绘制。

在 2.3.0 版本加入.

joint¶: 确定线条的连接方式，默认为'round'。可选值为'none'、'round'、'bevel'、'miter'。

在 1.4.1 版本加入.

joint_precision¶: 绘制“圆角”关节的迭代次数，默认为10。joint_precision 必须至少为1。

在 1.4.1 版本加入.

points¶: 用于获取/设置线条点的属性。

警告

这将始终根据新的点列表重建整个图形，这可能会非常消耗CPU资源。

rectangle¶

使用此属性来构建一个矩形，无需计算 points。

参数必须是一个 (x, y, width, height) 的元组。

x 和 y 表示矩形的左下角位置。
width 和 height 表示尺寸。

线条会自动闭合。

用法：：

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

在 1.4.1 版本加入.

在 2.2.0 版本发生变更: 现在你可以通过该属性获取生成的矩形。

rounded_rectangle¶

使用此属性来构建一个矩形，无需计算 points。

参数必须是以下形式之一的元组：

(x, y, width, height, corner_radius)
(x, y, width, height, corner_radius, resolution)
(x, y, width, height, corner_radius1, corner_radius2, corner_radius3, corner_radius4)
(x, y, width, height, corner_radius1, corner_radius2, corner_radius3, corner_radius4, resolution)
x 和 y 表示矩形的左下角位置。
width 和 height 表示尺寸。
corner_radius 指定用于圆角的半径，按顺时针方向依次为：左上、右上、右下、左下。
resolution 是用于在每个角绘制圆弧的线段数量（默认为45）。

线条会自动闭合。

用法：：

Line(rounded_rectangle=(0, 0, 200, 200, 10, 20, 30, 40, 100))

在 1.9.0 版本加入.

在 2.2.0 版本发生变更: resolution 的默认值从 30 改为 45。

现在您可以通过该属性获得圆角矩形。

corner_radius 的顺序已更改，以匹配 RoundedRectangle 的 radius 属性（顺时针方向）。在之前的版本中，顺序为左下、右下、右上、左上。现在两者均为顺时针：左上、右上、右下、左下。若要保持角半径顺序不变而无需手动调整顺序，可以使用 Python 内置方法 reversed 或 [::-1] 来反转角半径的顺序。

width¶: 确定线条的宽度，默认为1.0。

在 1.4.1 版本加入.

class kivy.graphics.vertex_instructions.Mesh(**kwargs)¶

基类：VertexInstruction

在OpenGL ES 2.0及我们的图形实现中，索引数量不能超过65535个。

顶点列表描述如下:

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

如果你想绘制一个三角形，添加3个顶点。然后你可以按照以下方式创建一个索引列表：

indices = [0, 1, 2]

在 1.1.0 版本加入.

参数:

vertices：可迭代对象

顶点列表，格式为(x1, y1, u1, v1, x2, y2, u2, v2...)。

indices：可迭代对象

格式为 (i1, i2, i3...) 的索引列表。

mode：字符串

vbo 的模式。更多信息请参阅 mode。默认为 'points'。

fmt：列表

默认情况下，顶点的格式由2D坐标（x, y）和2D纹理坐标（u, v）描述。列表中的每个元素应为元组或列表，形式如下：

(variable_name, size, type)

这将允许将顶点数据映射到GLSL指令。

[(b'v_pos', 2, 'float'), (b'v_tc', 2, 'float'),]

允许使用

attribute vec2 v_pos; attribute vec2 v_tc;

在GLSL的顶点着色器中。

在 1.8.1 版本发生变更: 之前，vertices 和 indices 总是会被转换为列表，现在，只有在它们未实现缓冲区接口时才会被转换为列表。因此，例如 numpy 数组、python 数组等可以直接使用，而无需创建任何额外的副本。然而，缓冲区不能是只读的（即使它们未被修改，由于 cython 的限制），并且必须在内存中是连续的。

备注

当传入一个memoryview或实现了缓冲区接口的实例时，vertices`应为浮点数缓冲区（Python数组中的'f'代码），而`indices`应为无符号短整型缓冲区（Python数组中的'H'`代码）。其他格式的数组仍需要在内部进行转换，从而抵消任何潜在的性能提升。

indices¶: 用于指定绘制网格时顶点顺序的顶点索引。

mode¶: 用于绘制顶点/索引的VBO模式。可以是'points'、'line_strip'、'line_loop'、'lines'、'triangles'、'triangle_strip'或'triangle_fan'之一。

vertices¶: 用于构建网格的x、y、u、v坐标列表。目前，Mesh指令不允许您更改顶点的格式，这意味着它仅包含x、y加上一个纹理坐标。

class kivy.graphics.vertex_instructions.Point(**kwargs)¶

基类：VertexInstruction

宽度/高度为 pointsize 的 2 倍。

参数:

points：列表: 格式为 (x1, y1, x2, y2...) 的点列表，其中每对坐标指定一个新点的中心。
pointsize：浮点数，默认值为 1。: 点的大小，从中心到边缘测量。因此，值为1.0意味着实际大小将是2.0 x 2.0。

警告

从1.0.7版本开始，顶点指令的顶点数量限制为65535个（准确来说是顶点索引数）。列表中的2个条目（x, y）会被转换为4个顶点。因此，在Point()类内部的限制为2^15-2。

add_point(self, float x, float y)¶

向当前 points 列表中添加一个点。

如果你打算添加多个点，建议使用此方法，而不是重新分配一个新的 points 列表。重新分配新的 points 列表会重新计算并将整个缓冲区重新上传到 GPU。如果使用 add_point，则只会上传更改的部分。

points¶: 用于获取/设置点列表中中心点的属性。每对坐标指定一个新点的中心。

pointsize¶: 用于获取/设置点大小的属性。该大小是从中心到边缘测量的，因此值为1.0时，实际大小将为2.0 x 2.0。

class kivy.graphics.vertex_instructions.Quad(**kwargs)¶

基类：VertexInstruction

参数:

points：列表: 格式为(x1, y1, x2, y2, x3, y3, x4, y4)的点列表。

points¶: 用于获取/设置四边形点的属性。

class kivy.graphics.vertex_instructions.Rectangle(**kwargs)¶

基类：VertexInstruction

参数:

pos：列表: 矩形的位置，格式为 (x, y)。
size：列表: 矩形的大小，格式为（宽度，高度）。

points¶: 用于获取绘制顶点所用点的属性。

在 2.3.0 版本加入.

pos¶: 用于获取/设置矩形位置的属性。

size¶: 用于获取/设置矩形尺寸的属性。

class kivy.graphics.vertex_instructions.RoundedRectangle(**kwargs)¶

基类：Rectangle

在 1.9.1 版本加入.

参数:

segments：整数，默认为 10: 定义绘制圆角所需的线段数量。线段越多，绘制效果越平滑。
radius：列表，默认值为 [(10.0, 10.0), (10.0, 10.0), (10.0, 10.0), (10.0, 10.0)]: 指定用于圆角的半径，按顺时针方向依次为：左上、右上、右下、左下。列表中的元素可以是数字，也可以是包含两个数字的元组，以分别指定不同的x、y尺寸。一个值将定义所有角半径为该值。四个值将分别定义每个角的半径。超过四个值将被截断为四个。如果少于四个值，则第一个值将用于所有角。

radius¶: 圆角矩形的圆角半径，默认为 [10,]。

segments¶: 用于获取/设置每个角的分段数的属性。

class kivy.graphics.vertex_instructions.SmoothLine(**kwargs)¶

基类：Line

结果。它有一些缺点：

如果线条自身交叉，使用透明度绘制线条可能无法达到预期效果。
:不支持 cap、joint 和 dash 属性。
它使用带有预乘Alpha的自定义纹理。
宽度小于1像素的线条不受支持：它们看起来会是一样的。

警告

这是一项未完成的工作，处于实验阶段，并可能遭遇崩溃。

在 1.9.0 版本加入.

overdraw_width¶: 确定线条的过度绘制宽度，默认为1.2。

premultiplied_texture(self)¶

class kivy.graphics.vertex_instructions.Triangle(**kwargs)¶

基类：VertexInstruction

参数:

points：列表: 格式为(x1, y1, x2, y2, x3, y3)的点列表。

points¶: 用于获取/设置三角形点的属性。

« 变换

输入管理 »

Version

Quick search

目录

顶点指令¶

更新属性¶