custom-ui-and-drawbot

Custom UI & Drawbot

Custom UI uses a composited drawing model using Drawbot. The Drawbot suites can be used for:

Basic 2D path drawing: Lines, Rect, Arc, Bezier
Stroking/Filling/Shading paths
Image drawing: Compositing an ARGB/BGRA buffer onto the surface
Pushing/popping surface state
Text drawing, if supplier supports it (clients should first check if text drawing is supported before actual drawing)

Drawing may only occur during PF_Event_DRAW (and not during PF_Event_DRAG or PF_Event_DO_CLICK).

To use Drawbot, first get the drawing reference by passing in PF_Context to a new suite call PF_GetDrawingReference.

If a non-NULL drawing reference is returned, use it to get the supplier and surface references from DRAWBOT_DrawbotSuite.

The Drawbot suites include DRAWBOT_DrawbotSuite, DRAWBOT_SupplierSuite, DRAWBOT_SurfaceSuite, DRAWBOT_PathSuite.

Make Your Custom UI Look Not So “Custom”

Use the new PF_EffectCustomUIOverlayThemeSuite to match the host application UI. Your users will thank you.

Redrawing

In order to redraw a specific area of a pane, we recommend the following:

Call PF_InvalidateRect (from PF_AppSuite) from the effect. This will cause a lazy display redraw, and will update at the next available idle moment. This rect is in coordinates related to the associated pane. Using a NULL rect will update the entire pane.
Set the event outflag to PF_EO_UPDATE_NOW, which will cause an immediate draw event for the specified pane when the current event returns.

If an effect needs to update more than one window at a time, it should set PF_OutFlag_REFRESH_UI (from PF_OutFlags), which will cause a redraw of the entire ECW, comp, and layer windows.

HiDPI and Retina Display Support

To support HiDPI and Retina Displays, you can use offscreen images that are twice the size, and then use the Transform function from Drawbot_SurfaceSuite to scale the image down in half before drawing it.

PF_EffectCustomUISuite

Enables an effect to get the drawing reference. This is the first call needed to use Drawbot.

PF_EffectCustomUISuite1

Function	Purpose
`PF_GetDrawingReference`	Get the drawing reference.
	PF_GetDrawingReference( const PF_ContextH effect_contextH, DRAWBOT_DrawRef *referenceP0);

Drawbot_DrawbotSuite

Using the Drawbot reference, get the supplier and surface references.

Drawbot_DrawbotSuite1

Function	Purpose
`GetSupplier`	Get the supplier reference.
	Needed to use Drawbot_SupplierSuite.
	GetSupplier( DRAWBOT_DrawRef in_drawbot_ref, DRAWBOT_SupplierRef *out_supplierP);
`GetSurface`	Get the surface reference.
	Needed to use Drawbot_SurfaceSuite.
	GetSurface( DRAWBOT_DrawRef in_drawbot_ref, DRAWBOT_SurfaceRef *out_surfaceP);

Drawbot_SupplierSuite

Calls to create and release drawing tools, get default settings, and query drawing capabilities.

Drawbot_SupplierSuite1

Function	Purpose
`NewPen`	Create a new pen. Release this using `ReleaseObject` from Drawbot_SupplierSuite.
	NewPen( DRAWBOT_SupplierRef in_supplier_ref, const DRAWBOT_ColorRGBA in_colorP, float in_size, DRAWBOT_PenRef out_penP);
`NewBrush`	Create a new brush. Release this using `ReleaseObject` from Drawbot_SupplierSuite.
	NewBrush( DRAWBOT_SupplierRef in_supplier_ref, const DRAWBOT_ColorRGBA in_colorP, DRAWBOT_BrushRef out_brushP);
`SupportsText`	Check if current supplier supports text.
	SupportsText( DRAWBOT_SupplierRef in_supplier_ref, DRAWBOT_Boolean *out_supports_textB);
`GetDefaultFontSize`	Get the default font size.
	GetDefaultFontSize( DRAWBOT_SupplierRef in_supplier_ref, float *out_font_sizeF);
`NewDefaultFont`	Create a new font with default settings.
	You can pass the default font size from `GetDefaultFontSize`.
	Release this using `ReleaseObject` from Drawbot_SupplierSuite.
	NewDefaultFont( DRAWBOT_SupplierRef in_supplier_ref, float in_font_sizeF, DRAWBOT_FontRef *out_fontP);
`NewImageFromBuffer`	Create a new image from buffer passed to in_dataP.
	Release this using `ReleaseObject` from Drawbot_SupplierSuite.
	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` can be one of the following:
	- `kDRAWBOT_PixelLayout_24RGB`
	- `kDRAWBOT_PixelLayout_24BGR`
	- `kDRAWBOT_PixelLayout_32RGB`
	- `ARGB` (A is ignored)
	- `kDRAWBOT_PixelLayout_32BGR`
	- `BGRA` (A is ignored)
	- `kDRAWBOT_PixelLayout_32ARGB_Straight`
	- `kDRAWBOT_PixelLayout_32ARGB_Premul`
	- `kDRAWBOT_PixelLayout_32BGRA_Straight`
	- `kDRAWBOT_PixelLayout_32BGRA_Premul`
`NewPath`	Create a new path. Release this using `ReleaseObject` from Drawbot_SupplierSuite.
	NewPath( DRAWBOT_SupplierRef in_supplier_ref, DRAWBOT_PathRef *out_pathP);
`SupportsPixelLayoutBGRA`	A given Drawbot implementation can support multiple channel orders, but will likely prefer one over the other.
	Use the following four callbacks to get the preferred channel order for any API that takes a `DRAWBOT_PixelLayout` (e.g. `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`	Retain (increase reference count on) any object (pen, brush, path, etc). For example, it should be used when any object is copied and the copied object should be retained.
	RetainObject( DRAWBOT_ObjectRef in_obj_ref);
`ReleaseObject`	Release (decrease reference count on) any object (pen, brush, path, etc). This function MUST be called for any object created using `NewXYZ()` from this suite.
	Do not call this function on a `DRAWBOT_SupplierRef` and `DRAWBOT_SupplierRef`, since these are not created by the plug-in.
	ReleaseObject( DRAWBOT_ObjectRef in_obj_ref);

Drawbot_SurfaceSuite

Calls to draw on the surface, and to query and set drawing settings.

Drawbot_SurfaceSuite1

Function	Purpose
`PushStateStack`	Push the current surface state onto the stack. It should be popped to retrieve old state.
	It is required to restore state if you are going to clip or transform a surface or change the interpolation or anti-aliasing policy.
	PushStateStack( DRAWBOT_SurfaceRef in_surface_ref);
`PopStateStack`	Pop the last pushed surface state off the stack.
	PopStateStack( DRAWBOT_SurfaceRef in_surface_ref);
`PaintRect`	Paint a rectangle with a color on the surface.
	PaintRect( DRAWBOT_SurfaceRef in_surface_ref, const DRAWBOT_ColorRGBA in_colorP, const DRAWBOT_RectF32 in_rectPR);
`FillPath`	Fill a path using a brush and fill type.
	FillPath( DRAWBOT_SurfaceRef in_surface_ref, DRAWBOT_BrushRef in_brush_ref, DRAWBOT_PathRef in_path_ref, DRAWBOT_FillType in_fill_type);
	`DRAWBOT_FillType` is one of the following:
	- `kDRAWBOT_FillType_EvenOdd`
	- `kDRAWBOT_FillType_Winding`
`StrokePath`	Stroke a path using a pen.
	StrokePath( DRAWBOT_SurfaceRef in_surface_ref, DRAWBOT_PenRef in_pen_ref, DRAWBOT_PathRef in_path_ref);
`Clip`	Clip the surface.
	Clip( DRAWBOT_SurfaceRef in_surface_ref, DRAWBOT_SupplierRef in_supplier_ref, const DRAWBOT_Rect32 *in_rectPR);
`GetClipBounds`	Get clip bounds.
	GetClipBounds( DRAWBOT_SurfaceRef in_surface_ref, DRAWBOT_Rect32 *out_rectPR);
`IsWithinClipBounds`	Checks whether a rect is within the clip bounds.
	IsWithinClipBounds( DRAWBOT_SurfaceRef in_surface_ref, const DRAWBOT_Rect32 in_rectPR, DRAWBOT_Boolean out_withinPB);
`Transform`	Transform the last surface state.
	Transform( DRAWBOT_SurfaceRef in_surface_ref, const DRAWBOT_MatrixF32 *in_matrixP);
`DrawString`	Draw a string.
	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` is one of the following:
	- `kDRAWBOT_TextAlignment_Left`
	- `kDRAWBOT_TextAlignment_Center`
	- `kDRAWBOT_TextAlignment_Right`
	`DRAWBOT_TextTruncation` is one of the following:
	- `kDRAWBOT_TextTruncation_None`
	- `kDRAWBOT_TextTruncation_End`
	- `kDRAWBOT_TextTruncation_EndEllipsis`
	- `kDRAWBOT_TextTruncation_PathEllipsis`
`DrawImage`	Draw an image created using `NewImageFromBuffer()` on the surface. 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` is one of the following:
	- `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` is one of the following:
	- `kDRAWBOT_AntiAliasPolicy_None`
	- `kDRAWBOT_AntiAliasPolicy_Med`
	- `kDRAWBOT_AntiAliasPolicy_High`
`GetAntiAliasPolicy`	GetAntiAliasPolicy( DRAWBOT_SurfaceRef in_surface_ref, DRAWBOT_AntiAliasPolicy *out_policyP);
`Flush`	Flush drawing. This is not always needed, and if overused, may cause excessive redrawing and flashing.
	Flush( DRAWBOT_SurfaceRef in_surface_ref);

Drawbot_PathSuite

Calls to draw paths.

Drawbot_PathSuite1

Function	Purpose
`MoveTo`	Move to a point.
	MoveTo( DRAWBOT_PathRef in_path_ref, float in_x, float in_y);
`LineTo`	Add a line to the path.
	LineTo( DRAWBOT_PathRef in_path_ref, float in_x, float in_y);
`BezierTo`	Add a cubic bezier to the path.
	BezierTo( DRAWBOT_PathRef in_path_ref, const DRAWBOT_PointF32 in_pt1P, const DRAWBOT_PointF32 in_pt2P, const DRAWBOT_PointF32 *in_pt3P);
`AddRect`	Add a rect to the path.
	AddRect( DRAWBOT_PathRef in_path_ref, const DRAWBOT_RectF32 *in_rectPR);
`AddArc`	Add a arc to the path. Zero start degrees == 3 o’clock.
	Sweep is clockwise. Units for angle are in degrees.
	AddArc( DRAWBOT_PathRef in_path_ref, const DRAWBOT_PointF32 *in_centerP, float in_radius, float in_start_angle, float in_sweep);
`Close`	Close the path.
	Close( DRAWBOT_PathRef in_path_ref);

PF_EffectCustomUIOverlayThemeSuite

This suite should be used for stroking and filling paths and vertices on the Composition and Layer Windows. After Effects is using this suite internally, and we have made it available to make custom UI look consistent across effects. The foreground/shadow colors are computed based on the app brightness level so that custom UI is always visible regardless of the application’s Brightness setting in the Preferences.

PF_EffectCustomUIOverlayThemeSuite1

Function	Purpose
`PF_GetPreferredForegroundColor`	Get the preferred foreground color.
	PF_GetPreferredForegroundColor( DRAWBOT_ColorRGBA *foreground_colorP);
`PF_GetPreferredShadowColor`	Get the preferred shadow color.
	PF_GetPreferredShadowColor( DRAWBOT_ColorRGBA *shadow_colorP);
`PF_GetPreferredStrokeWidth`	Get the preferred foreground & shadow stroke width.
	PF_GetPreferredStrokeWidth( float *stroke_widthPF);
`PF_GetPreferredVertexSize`	Get the preferred vertex size.
	PF_GetPreferredVertexSize( float *vertex_sizePF);
`PF_GetPreferredShadowOffset`	Get the preferred shadow offset.
	PF_GetPreferredShadowOffset( A_LPoint *shadow_offsetP);
`PF_StrokePath`	Stroke the path with the overlay theme foreground color.
	Optionally draw the shadow using the overlay theme shadow color.
	Uses overlay theme stroke width for stroking foreground and shadow strokes.
	PF_StrokePath( const DRAWBOT_DrawRef drawbot_ref, const DRAWBOT_PathRef path_ref PF_Boolean draw_shadowB);
`PF_FillPath`	Fills the path with overlay theme foreground color.
	Optionally draw the shadow using the overlay theme shadow color.
	PF_FillPath( const DRAWBOT_DrawRef drawbot_ref, const DRAWBOT_PathRef path_ref PF_Boolean draw_shadowB);
`PF_FillVertex`	Fills a square vertex around the center point using the overlay theme foreground color and vertex size.
	PF_FillVertex( const DRAWBOT_DrawRef drawbot_ref, const A_FloatPoint *center_pointP PF_Boolean draw_shadowB);