跳转到内容
月离文档

自定义UI与Drawbot

自定义UI与Drawbot

自定义UI使用Drawbot的复合绘图模型。Drawbot套件可用于：

  1. 基本的2D路径绘制：线条、矩形、圆弧、贝塞尔曲线
  2. 描边/填充/着色路径
  3. 图像绘制：将ARGB/BGRA缓冲区合成到表面上
  4. 推入/弹出表面状态
  5. 文本绘制，如果供应商支持（客户端应在实际绘制之前检查是否支持文本绘制）

绘图只能在PF_Event_DRAW期间进行（而不能在PF_Event_DRAG或PF_Event_DO_CLICK期间进行）。

要使用Drawbot，首先通过将PF_Context传递给新的套件调用PF_GetDrawingReference来获取绘图引用。

如果返回了非NULL的绘图引用，请使用它从DRAWBOT_DrawbotSuite中获取供应商和表面引用。

Drawbot套件包括DRAWBOT_DrawbotSuite、DRAWBOT_SupplierSuite、DRAWBOT_SurfaceSuite、DRAWBOT_PathSuite。

让你的自定义UI看起来不那么“自定义”

使用新的PF_EffectCustomUIOverlayThemeSuite来匹配主机应用程序的UI。你的用户会感谢你。

重绘

为了重绘窗格的特定区域，我们建议以下步骤：

  1. 从效果中调用PF_InvalidateRect（来自PF_AppSuite）。这将导致延迟显示重绘，并在下一个空闲时刻更新。此矩形与相关窗格的坐标相关。使用NULL矩形将更新整个窗格。
  2. 将event outflag设置为PF_EO_UPDATE_NOW，这将在当前事件返回时立即触发指定窗格的绘制事件。

如果效果需要同时更新多个窗口，则应设置PF_OutFlag_REFRESH_UI（来自PF_OutFlags），这将导致整个ECW、comp和图层窗口的重绘。

HiDPI和Retina显示支持

为了支持HiDPI和Retina显示，你可以使用两倍大小的离屏图像，然后使用Drawbot_SurfaceSuite中的Transform函数在绘制之前将图像缩小一半。

PF_EffectCustomUISuite

使效果能够获取绘图引用。这是使用Drawbot所需的第一个调用。

PF_EffectCustomUISuite1

函数用途
PF_GetDrawingReference获取绘图引用。
 PF_GetDrawingReference(
  const PF_ContextH  effect_contextH,
  DRAWBOT_DrawRef    *referenceP0);

Drawbot_DrawbotSuite

使用Drawbot引用，获取供应商和表面引用。

Drawbot_DrawbotSuite1

函数用途
GetSupplier获取供应商引用。
需要使用Drawbot_SupplierSuite。
 GetSupplier(
  DRAWBOT_DrawRef      in_drawbot_ref,
  DRAWBOT_SupplierRef  *out_supplierP);
GetSurface获取表面引用。
需要使用Drawbot_SurfaceSuite。
 GetSurface(
  DRAWBOT_DrawRef     in_drawbot_ref,
  DRAWBOT_SurfaceRef  *out_surfaceP);

Drawbot_SupplierSuite

用于创建和释放绘图工具、获取默认设置以及查询绘图能力的调用。

Drawbot_SupplierSuite1

函数用途
NewPen创建新画笔。使用Drawbot_SupplierSuite中的ReleaseObject释放此对象。
 NewPen(
  DRAWBOT_SupplierRef      in_supplier_ref,
  const DRAWBOT_ColorRGBA  *in_colorP,
  float                    in_size,
  DRAWBOT_PenRef           *out_penP);
NewBrush创建新画刷。使用Drawbot_SupplierSuite中的ReleaseObject释放此对象。
 NewBrush(
  DRAWBOT_SupplierRef      in_supplier_ref,
  const DRAWBOT_ColorRGBA  *in_colorP,
  DRAWBOT_BrushRef         *out_brushP);
SupportsText检查当前供应商是否支持文本。
 SupportsText(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_Boolean      *out_supports_textB);
GetDefaultFontSize获取默认字体大小。
 GetDefaultFontSize(
  DRAWBOT_SupplierRef  in_supplier_ref,
  float                *out_font_sizeF);
NewDefaultFont使用默认设置创建新字体。
你可以传递从GetDefaultFontSize获取的默认字体大小。
使用Drawbot_SupplierSuite中的ReleaseObject释放此对象。
 NewDefaultFont(
  DRAWBOT_SupplierRef  in_supplier_ref,
  float                in_font_sizeF,
  DRAWBOT_FontRef      *out_fontP);
NewImageFromBuffer从传递给in_dataP的缓冲区创建新图像。
使用Drawbot_SupplierSuite中的ReleaseObject释放此对象。
 NewImageFromBuffer(
  DRAWBOT_SupplierRef  in_supplier_ref,
  int                  in_width,
  int                  in_height,
  int                  in_row_bytes,
  DRAWBOT_PixelLayout  in_pl,
  const void           *in_dataP,
  DRAWBOT_ImageRef     *out_imageP);
DRAWBOT_PixelLayout可以是以下之一：
- kDRAWBOT_PixelLayout_24RGB
- kDRAWBOT_PixelLayout_24BGR
- kDRAWBOT_PixelLayout_32RGB
- ARGB（A被忽略）
- kDRAWBOT_PixelLayout_32BGR
- BGRA（A被忽略）
- kDRAWBOT_PixelLayout_32ARGB_Straight
- kDRAWBOT_PixelLayout_32ARGB_Premul
- kDRAWBOT_PixelLayout_32BGRA_Straight
- kDRAWBOT_PixelLayout_32BGRA_Premul
NewPath创建新路径。使用Drawbot_SupplierSuite中的ReleaseObject释放此对象。
 NewPath(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_PathRef      *out_pathP);
SupportsPixelLayoutBGRA给定的Drawbot实现可以支持多种通道顺序，但可能会优先选择其中一种。
使用以下四个回调来获取任何接受DRAWBOT_PixelLayout的API的首选通道顺序（例如NewImageFromBuffer）。
 SupportsPixelLayoutBGRA(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_Boolean      *out_supports_bgraPB);
PrefersPixelLayoutBGRA
PrefersPixelLayoutBGRA(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_Boolean      *out_prefers_bgraPB);
SupportsPixelLayoutARGB
SupportsPixelLayoutARGB(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_Boolean      *out_supports_argbPB);
PrefersPixelLayoutARGB
PrefersPixelLayoutARGB(
  DRAWBOT_SupplierRef  in_supplier_ref,
  DRAWBOT_Boolean      *out_prefers_argbPB);
RetainObject保留（增加引用计数）任何对象（画笔、画刷、路径等）。例如，当复制任何对象并且应保留复制的对象时，应使用此函数。
 RetainObject(
  DRAWBOT_ObjectRef  in_obj_ref);
ReleaseObject释放（减少引用计数）任何对象（画笔、画刷、路径等）。对于使用此套件中的NewXYZ()创建的任何对象，必须调用此函数。
不要在DRAWBOT_SupplierRef和DRAWBOT_SupplierRef上调用此函数，因为这些对象不是由插件创建的。
 ReleaseObject(
  DRAWBOT_ObjectRef  in_obj_ref);

Drawbot_SurfaceSuite

用于在表面上绘制以及查询和设置绘图设置的调用。

Drawbot_SurfaceSuite1

函数用途
PushStateStack将当前的表面状态推入堆栈。应该通过弹出操作来恢复旧状态。
如果你打算裁剪或变换表面，或者更改插值或抗锯齿策略，则需要恢复状态。
 PushStateStack(
  DRAWBOT_SurfaceRef  in_surface_ref);
PopStateStack弹出最后推入的表面状态。
 PopStateStack(
  DRAWBOT_SurfaceRef  in_surface_ref);
PaintRect在表面上用颜色绘制一个矩形。
 PaintRect(
  DRAWBOT_SurfaceRef       in_surface_ref,
  const DRAWBOT_ColorRGBA  *in_colorP,
  const DRAWBOT_RectF32    *in_rectPR);
FillPath使用画笔和填充类型填充路径。
 FillPath(
  DRAWBOT_SurfaceRef  in_surface_ref,
  DRAWBOT_BrushRef    in_brush_ref,
  DRAWBOT_PathRef     in_path_ref,
  DRAWBOT_FillType    in_fill_type);
DRAWBOT_FillType 是以下之一：
- kDRAWBOT_FillType_EvenOdd
- kDRAWBOT_FillType_Winding
StrokePath使用画笔描边路径。
 StrokePath(
  DRAWBOT_SurfaceRef  in_surface_ref,
  DRAWBOT_PenRef      in_pen_ref,
  DRAWBOT_PathRef     in_path_ref);
Clip裁剪表面。
 Clip(
  DRAWBOT_SurfaceRef    in_surface_ref,
  DRAWBOT_SupplierRef   in_supplier_ref,
  const DRAWBOT_Rect32  *in_rectPR);
GetClipBounds获取裁剪边界。
 GetClipBounds(
  DRAWBOT_SurfaceRef  in_surface_ref,
  DRAWBOT_Rect32      *out_rectPR);
IsWithinClipBounds检查矩形是否在裁剪边界内。
 IsWithinClipBounds(
  DRAWBOT_SurfaceRef    in_surface_ref,
  const DRAWBOT_Rect32  *in_rectPR,
  DRAWBOT_Boolean       *out_withinPB);
Transform变换最后的表面状态。
 Transform(
  DRAWBOT_SurfaceRef       in_surface_ref,
  const DRAWBOT_MatrixF32  *in_matrixP);
DrawString绘制字符串。
 DrawString(
  DRAWBOT_SurfaceRef       in_surface_ref,
  DRAWBOT_BrushRef         in_brush_ref,
  DRAWBOT_FontRef          in_font_ref,
  const DRAWBOT_UTF16Char  *in_stringP,
  const DRAWBOT_PointF32   *in_originP,
  DRAWBOT_TextAlignment    in_alignment_style,
  DRAWBOT_TextTruncation   in_truncation_style,
  float                    in_truncation_width);
DRAWBOT_TextAlignment 是以下之一：
- kDRAWBOT_TextAlignment_Left
- kDRAWBOT_TextAlignment_Center
- kDRAWBOT_TextAlignment_Right
DRAWBOT_TextTruncation 是以下之一：
- kDRAWBOT_TextTruncation_None
- kDRAWBOT_TextTruncation_End
- kDRAWBOT_TextTruncation_EndEllipsis
- kDRAWBOT_TextTruncation_PathEllipsis
DrawImage在表面上绘制使用 NewImageFromBuffer() 创建的图像。Alpha = [0.0f, 1.0f ]。
 DrawImage(
  DRAWBOT_SurfaceRef      in_surface_ref,
  DRAWBOT_ImageRef        in_image_ref,
  const DRAWBOT_PointF32  *in_originP,
  float                   in_alpha);
SetInterpolationPolicy
SetInterpolationPolicy(
  DRAWBOT_SurfaceRef           in_surface_ref,
  DRAWBOT_InterpolationPolicy  in_interp);
DRAWBOT_InterpolationPolicy 是以下之一：
- kDRAWBOT_InterpolationPolicy_None
- kDRAWBOT_InterpolationPolicy_Med
- kDRAWBOT_InterpolationPolicy_High
GetInterpolationPolicy
GetInterpolationPolicy(
  DRAWBOT_SurfaceRef           in_surface_ref,
  DRAWBOT_InterpolationPolicy  *out_interpP);
SetAntiAliasPolicy
SetAntiAliasPolicy(
  DRAWBOT_SurfaceRef       in_surface_ref,
  DRAWBOT_AntiAliasPolicy  in_policy);
DRAWBOT_AntiAliasPolicy 是以下之一：
- kDRAWBOT_AntiAliasPolicy_None
- kDRAWBOT_AntiAliasPolicy_Med
- kDRAWBOT_AntiAliasPolicy_High
GetAntiAliasPolicy
GetAntiAliasPolicy(
  DRAWBOT_SurfaceRef       in_surface_ref,
  DRAWBOT_AntiAliasPolicy  *out_policyP);
Flush刷新绘图。这并不总是需要，如果过度使用，可能会导致过多的重绘和闪烁。
 Flush(
  DRAWBOT_SurfaceRef  in_surface_ref);

Drawbot_PathSuite

用于绘制路径的调用。

Drawbot_PathSuite1

函数用途
MoveTo移动到某个点。
 MoveTo(
  DRAWBOT_PathRef  in_path_ref,
  float            in_x,
  float            in_y);
LineTo向路径添加一条线。
 LineTo(
  DRAWBOT_PathRef  in_path_ref,
  float            in_x,
  float            in_y);
BezierTo向路径添加一个三次贝塞尔曲线。
 BezierTo(
  DRAWBOT_PathRef         in_path_ref,
  const DRAWBOT_PointF32  *in_pt1P,
  const DRAWBOT_PointF32  *in_pt2P,
  const DRAWBOT_PointF32  *in_pt3P);
AddRect向路径添加一个矩形。
 AddRect(
  DRAWBOT_PathRef        in_path_ref,
  const DRAWBOT_RectF32  *in_rectPR);
AddArc向路径添加一个圆弧。零起始角度 == 3点钟方向。
扫掠方向为顺时针。角度的单位为度。
 AddArc(
  DRAWBOT_PathRef         in_path_ref,
  const DRAWBOT_PointF32  *in_centerP,
  float                   in_radius,
  float                   in_start_angle,
  float                   in_sweep);
Close关闭路径。
 Close(
  DRAWBOT_PathRef  in_path_ref);

PF_EffectCustomUIOverlayThemeSuite

此套件应用于在合成窗口和图层窗口上描边和填充路径和顶点。After Effects 在内部使用此套件，我们已将其公开，以使自定义 UI 在效果之间保持一致。前景/阴影颜色是根据应用程序亮度级别计算的，因此无论应用程序的“偏好设置”中的亮度设置如何，自定义 UI 始终可见。

PF_EffectCustomUIOverlayThemeSuite1

函数用途
PF_GetPreferredForegroundColor获取首选前景颜色。
 PF_GetPreferredForegroundColor(
  DRAWBOT_ColorRGBA  *foreground_colorP);
PF_GetPreferredShadowColor获取首选阴影颜色。
 PF_GetPreferredShadowColor(
  DRAWBOT_ColorRGBA  *shadow_colorP);
PF_GetPreferredStrokeWidth获取首选前景和阴影描边宽度。
 PF_GetPreferredStrokeWidth(
  float  *stroke_widthPF);
PF_GetPreferredVertexSize获取首选顶点大小。
 PF_GetPreferredVertexSize(
  float  *vertex_sizePF);
PF_GetPreferredShadowOffset获取首选阴影偏移。
 PF_GetPreferredShadowOffset(
  A_LPoint  *shadow_offsetP);
PF_StrokePath使用叠加主题前景颜色描边路径。
可选地使用叠加主题阴影颜色绘制阴影。
使用叠加主题描边宽度来描边前景和阴影描边。
 PF_StrokePath(
  const DRAWBOT_DrawRef  drawbot_ref,
  const DRAWBOT_PathRef  path_ref
  PF_Boolean             draw_shadowB);
PF_FillPath使用叠加主题前景颜色填充路径。
可选地使用叠加主题阴影颜色绘制阴影。
 PF_FillPath(
  const DRAWBOT_DrawRef  drawbot_ref,
  const DRAWBOT_PathRef  path_ref
  PF_Boolean             draw_shadowB);
PF_FillVertex使用叠加主题前景颜色和顶点大小在中心点周围填充一个方形顶点。
 PF_FillVertex(
  const DRAWBOT_DrawRef  drawbot_ref,
  const A_FloatPoint     *center_pointP
  PF_Boolean             draw_shadowB);