开源图形库Thor Vector Graphics：Paint类, Result、 CompositeMethod、 BlendMethod 枚举类型

0. 简介

• 开源图形库Thor Vector Graphics的Paint类是一个用于绘制图形的API类，提供了各种功能来控制绘制对象的外观和行为。
• 所属头文件：thorvg.h

1. 成员函数与使用方法

• Result rotate(float degree) noexcept：设置对象的旋转角度。
  • 使用方法：传入旋转的角度值，以度为单位。
  • 注意事项：旋转角度是顺时针方向的，以水平轴为基准。
• Result scale(float factor) noexcept：设置对象的缩放比例。
  • 使用方法：传入缩放因子，1 表示原大小，大于 1 表示放大，小于 1 表示缩小。
  • 注意事项：默认缩放因子为 1。
• Result translate(float x, float y) noexcept：设置对象在二维空间中的平移。
  • 使用方法：传入水平和垂直方向的平移值。
  • 注意事项：坐标系的原点在画布的左上角。
• Result transform(const Matrix& m) noexcept：设置对象的仿射变换矩阵。
  • 使用方法：传入 3x3 的仿射变换矩阵。
  • 注意事项：用于自定义对象的复杂变换。
• Matrix transform() noexcept：获取对象的仿射变换矩阵。
  • 使用方法：调用该函数即可获取对象的当前变换矩阵。
  • 注意事项：如果没有应用任何变换，则返回单位矩阵。
• Result opacity(uint8_t o) noexcept：设置对象的不透明度。
  • 使用方法：传入不透明度值，范围在 0 到 255 之间，0 表示完全透明，255 表示完全不透明。
  • 注意事项：改变不透明度可能需要多次渲染过程。
• Result composite(std::unique_ptr<Paint> target, CompositeMethod method) noexcept：设置对象的合成目标对象和合成方法。
  • 使用方法：传入目标对象的指针和合成方法。
  • 注意事项：目标对象的所有变换和属性将被应用于当前对象。
• Result blend(BlendMethod method) const noexcept：设置对象的混合方法。
  • 使用方法：传入混合方法。
  • 注意事项：这是一个实验性的 API。
• Result bounds(float* x, float* y, float* w, float* h, bool transformed = false) const noexcept：获取对象的轴对齐边界框。
  • 使用方法：传入指向 float 变量的指针，用于接收边界框的坐标和尺寸。
  • 注意事项：如果设置了 transformed 参数为 true，则会考虑对象的变换。
• Paint* duplicate() const noexcept：复制对象。
  • 使用方法：调用该函数创建并返回一个新的对象，其属性与原对象相同。
  • 注意事项：如果复制失败，则返回 nullptr。
• uint8_t opacity() const noexcept：获取对象的不透明度值。
  • 使用方法：调用该函数即可获取当前对象的不透明度值。
• CompositeMethod composite(const Paint** target) const noexcept：获取对象的合成目标对象和合成方法。
  • 使用方法：传入指向指针的指针，用于接收目标对象的指针。
  • 注意事项：返回合成方法。
• BlendMethod blend() const noexcept：获取对象的混合方法。
  • 使用方法：调用该函数即可获取当前对象的混合方法。
  • 注意事项：这是一个实验性的 API。
• uint32_t identifier() const noexcept：返回对象的唯一标识符。
  • 使用方法：调用该函数即可获取当前对象的类型标识符。
  • 注意事项：可用于检查对象的具体实例类型。

1.1 Result枚举类型

Result 枚举类型用于表示 API 的执行结果。

• Success：表示请求正确执行的返回值。即在正常情况下，API 调用成功完成了其预期的任务。
• InvalidArguments：表示在调用 API 时提供的参数有问题，例如传递了空路径或空指针等无效参数。这通常意味着调用者需要修正提供给 API 的参数。
• InsufficientCondition：表示请求无法处理的情况。例如，尝试查询一个不存在的对象的属性，或者在某种不满足条件的情况下执行请求。这可能需要调用者在尝试再次请求之前采取额外的步骤或检查。
• FailedAllocation：表示内存分配失败的情况。这可能发生在动态内存分配时，无法分配足够的内存以满足请求。这通常需要调用者处理内存分配失败的情况，可能需要释放其他资源或减少内存需求。
• MemoryCorruption：表示内存损坏的情况。这可能发生在指针释放或类型转换等内存操作时发生错误的情况。这需要调用者检查内存操作的正确性，并确保没有发生内存损坏。
• NonSupport：表示选择了不支持的选项。即在执行请求时，选择了当前环境不支持的选项或功能。这可能需要调用者选择其他选项或执行其他操作。
• Unknown：表示所有其他情况。这是一个通用的返回值，用于表示无法归类到其他特定情况的情况。这可能需要调用者进一步检查和处理特定情况。

1.2 CompositeMethod枚举类型

CompositeMethod枚举用于指示两个对象（源对象和目标对象）在合成过程中所使用的方法。

• None：表示没有应用任何合成。即在合成过程中不对源对象和目标对象进行任何操作，直接渲染源对象。
• ClipPath：表示取源对象和目标对象的交集，只渲染交集部分的源对象像素。
• AlphaMask：表示使用目标对象的像素作为alpha值进行alpha蒙版。
• InvAlphaMask：表示使用目标对象像素的补集作为alpha值进行alpha蒙版。
• LumaMask：表示使用目标对象像素的灰度值（0.2125R + 0.7154G + 0.0721*B）进行alpha蒙版。
• InvLumaMask：表示使用目标对象像素的补集的灰度值进行alpha蒙版。
• AddMask：表示使用目标对象的alpha值组合目标和源对象的像素。（T * TA）+（S *（255 - TA））
• SubtractMask：表示在考虑目标对象和源对象的目标alpha的情况下，从目标颜色中减去源颜色。（T * TA）-（S *（255 - TA））
• IntersectMask：表示通过取目标alpha和源alpha的最小值，并将其与目标颜色相乘来计算结果。（T * min(TA, SA)）
• DifferenceMask：表示计算目标颜色与源颜色的绝对差值，乘以目标alpha的补集。（abs(T - S *（255 - TA）））

1.3 BlendMethod枚举类型

BlendMethod枚举表示了用于混合绘制对象的方法。

• Normal：执行标准的alpha混合。如果源像素的alpha值等于255，则执行S混合；否则执行 (Sa * S) + (255 - Sa) * D。
• Add：简单地将两个图层的像素值相加。
• Screen：对两个图层的像素值进行取反、相乘，然后再次取反。
• Multiply：将顶层图层中每个像素的RGB通道值（0 到 255）与底层图层相应像素的值相乘。
• Overlay：结合了Multiply和Screen混合模式的效果。
• Difference：将顶层图层减去底层图层，或者相反，以始终得到非负值。
• Exclusion：结果是顶层和底层像素的乘积的两倍减去它们的和。
• SrcOver：用顶层图层替换底层图层。
• Darken：创建一个像素，保留顶部和底部图层像素的最小分量。
• Lighten：与Darken相反，保留顶部和底部图层像素的最大分量。
• ColorDodge：将底层图层除以倒置的顶层图层。
• ColorBurn：将倒置的底层图层除以顶层图层，然后再取反。
• HardLight：与Overlay相同，但颜色角色相反。
• SoftLight：与Overlay相同，但应用纯黑或纯白不会产生纯黑或纯白。