绘图画布

254次阅读

共计 2305 个字符，预计需要花费 6 分钟才能阅读完成。

这个接口从 IWorldInstance 派生，为画布插件添加了特定的 API。

参见“生成图像”的示例，了解如何通过编程方式为画布生成图像。

绘图 API 中使用的坐标系统与动作中的相同。更多信息请参阅画布对象文档。

在一些绘图 API 中，有一些接受颜色的参数。这些用一个数组表示，可以是三个组件，例如[r, g, b]，在这种情况下，alpha 被视为不透明的，或者是四个组件，例如[r, g, b, a]，以指定 alpha。每个组件是一个归一化的浮点值，范围在 0 - 1 之间。

例如，[1, 0, 0]表示不透明的红色，而 [0, 0, 1, 0.5] 表示 50% 透明度的蓝色。

请参阅实例事件，了解标准实例事件对象属性。

fillRect(x, y, width, height, color1, color2, direction)

用线性渐变填充画布上的矩形区域。direction 必须是 "horizontal" 或 "vertical"。
fillEllipse(x, y, radiusX, radiusY, color, isSmooth = true)

用给定的颜色填充椭圆区域。位置是椭圆的中心，半径参数确定椭圆的形状（将两者设置为相同的值可以绘制一个圆）。默认情况下，绘制区域的边缘是平滑的；要实现像素化样式，请将 isSmooth 设置为 false。
outlineEllipse(x, y, radiusX, radiusY, color, thickness, isSmooth = true)

用给定的颜色和线条粗细绘制椭圆轮廓。位置是椭圆的中心，半径参数确定椭圆的形状（将两者设置为相同的值可以绘制一个圆）。绘制轮廓时，thickness 参数表示线宽。默认情况下，绘制区域的边缘是平滑的；要实现像素化样式，请将 isSmooth 设置为 false。
line(x1, y1, x2, y2, color, thickness, lineCap = "butt")

用给定的颜色和线条粗细在两点之间绘制实线或虚线。虚线变体还接受一个参数来设置划线的长度。lineCap 必须是 "butt"（在线的起始和结束位置正好结束线）或 "square"（使线的末端稍微超出起始和结束位置）。
fillPoly(polyPoints, color, isConvex = false)

用给定的颜色填充多边形区域。多边形由一个包含两个元素数组的坐标数组指定，例如 [[x1, y1], [x2, y2], …]。对于线变体，thickness 和 lineCap 参数与 line() 和 lineDashed()方法中使用的相同。

至少提供三个点以形成多边形，并且可能是凸形或凹形。然而，凹多边形在内部被转换为多个凸多边形。由于几何计算中的浮点精度问题，此过程有时会失败并导致呈现错误。如果已知形状为凸形，请为 isConvex 参数传递 true，这将绕过内部转换；但是，如果多边形实际上是凹形的，则不会正确呈现。

注意：不支持自相交多边形，使用 fillPoly()和 linePoly()时无法正确绘制。
setDrawBlend(blendMode)

设置用于在画布上进行绘制操作的混合模式。这与将画布本身绘制到布局所用的混合不同。混合模式用字符串指定，必须是 "normal"、"additive"、"copy"、"destination-over"、"source-in"、"destination-in"、"source-out"、"destination-out"、"source-atop" 或 "destination-atop" 之一。
async pasteInstances(instancesArr, includeEffects = true)

在当前位置绘制与画布重叠的一系列实例，作为 IWorldInstance 的数组给出。默认情况下，对象会像现在这样完全呈现，考虑到添加到它们的任何效果；将 includeEffects 设置为 false，以便在禁用所有对象效果的情况下进行绘制。请注意，实际绘制是在 tick 结束时进行的，因此可以等待此方法以确保粘贴已完成。

如果对象在粘贴后立即销毁而未完成等待，则不会进行绘制，因为它会在绘制之前被销毁。
setFixedResolutionMode(fixedWidth, fixedHeight)

切换固定和自动分辨率模式。有关更多信息，请参阅画布对象文档。
surfaceDeviceWidth
surfaceDeviceHeight

getSurfaceDeviceSize()

只读值，表示画布呈现表面的设备像素大小。该方法同时返回两个值。
pixelScale

只读值，表示画布上单个像素的对象坐标大小。有关坐标系统的更多信息，请参阅画布对象文档的相关部分。
async getImagePixelData()

异步获取 GPU 上画布像素状态的快照，并将其读取回 CPU。解析为表示像素数据的 ImageData。请注意，这使用了未预乘的 alpha，而在 GPU 上的表面是预乘的，所以技术上这是有损的。
loadImagePixelData(imageData, premultiplyAlpha = false)

将 ImageData 中的像素数据加载到画布呈现表面。ImageData 的大小必须等于 surfaceDeviceWidth 和 surfaceDeviceHeight。如果将可选参数 premultiplyAlpha 设置为 true，则像素数据将预乘 alpha（乘以 A 组件）。如果像素数据已经预乘，可以将其禁用，这也更快，因为可以跳过预乘步骤。