Drawing
PBPainter
Opaque object handle: An object that allows you to draw on a PBRenderSurface.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBPainterRetain; to decrement the reference count, call PBPainterRelease. These functions are thread-safe.
See Also
PBBoxShadowMode
Enumeration/bitset of type uint8_t:
Constants
PBBoxShadow_OUTER
PBBoxShadow_OUTER = 0
PBBoxShadow_INNER
PBBoxShadow_INNER = 1
PBBoxShadow_NO_CLIP
PBBoxShadow_NO_CLIP = 2
PBBlendMode
Enumeration/bitset of type uint8_t:
Constants
PBBlend_OVER_PERCEPTUAL
PBBlend_OVER_PERCEPTUAL = 0
Over operator with perceptual blending. Drawing gray A with 50% opacity over gray B results in a gray that appears halfway between A and B to the human eye.
PBBlend_OVER_LINEAR
PBBlend_OVER_LINEAR = 1
Over operator with linear blending. The opacity of a color determines the percentage of light it lets through.
PBColorSpaceID
Enumeration/bitset of type uint8_t:
Constants
PBColorSpaceID_SRGB
PBColorSpaceID_SRGB = 1
The sRGB color space.
PBColorSpaceID_NAMED
PBColorSpaceID_NAMED = 2
A set of named colors.
PBColorSpaceID_DISPLAY_P3
PBColorSpaceID_DISPLAY_P3 = 3
The Display P3 color space, as defined at https://www.color.org/chardata/rgb/DisplayP3.xalter.
PBBitmapFormat
Enumeration/bitset of type uint32_t:
Constants
PBBitmapFormat_RGB8_OPAQUE
PBBitmapFormat_RGB8_OPAQUE = 1
PBBitmapFormat_RGB8
PBBitmapFormat_RGB8 = 2
PBDrawElementFlags
Enumeration/bitset of type uint32_t:
Constants
PBDrawElement_CLIP_TO_BOUNDS
PBDrawElement_CLIP_TO_BOUNDS = 1<<0
PBDrawElement_MAIN_LAYER_ONLY
PBDrawElement_MAIN_LAYER_ONLY = 1<<1
PBDrawTextSelectionFlags
Enumeration/bitset of type uint32_t:
Constants
PBDrawTextSelection_PAST_END
PBDrawTextSelection_PAST_END = 1<<0
The selection region should be drawn in a way to indicate that the actual text selection goes past the end of this line/paragraph onto another one.
See Also
PBDepthIndex
Enumeration/bitset of type int8_t:
Constants
PBDepthIndex_SHADOW
PBDepthIndex_SHADOW = 0
PBDepthIndex_MAIN
PBDepthIndex_MAIN = 1
PBDepthIndex_OVERLAY
PBDepthIndex_OVERLAY = 2
PBPreviousClipRegion
Structure:
Fields
_private0 (PBRectangle):
_private1 (uint32_t):
PBPreviousTransformation
Structure: An opaque structure, storing the necessary information to restore the PBPainter transformation state. The format of the data stored here can change between system versions.
Fields
_private0 (int32_t):
_private1 (int32_t):
_private2 (uint32_t):
_private3 (uint32_t):
_private4 (uint32_t):
_private5 (uint32_t):
_private6 (uint32_t):
_private7 (uint32_t):
_private8 (uint32_t):
_private9 (uint32_t):
_private10 (uint32_t):
_private11 (uint32_t):
PBPreviousBlendMode
Structure: An opaque structure, storing the necessary information to restore the PBPainter blend mode state. The format of the data stored here can change between system versions.
Fields
_private0 (uint32_t):
_private1 (uint32_t):
_private2 (uint32_t):
_private3 (uint32_t):
PBMessageCustomPaint
Structure: Parameters for a custom paint message.
Fields
[in] atDepth (PBDepthIndex): The depth that is currently being drawn by the nearest ancestor with the PBElement_CLIP_LAYER flag. Typically, you will only want to perform your custom drawing if this is equal to PBDepthIndex_MAIN.
[in] painter (referenced PBPainter): The painter object to draw onto. Its coordinate system will have be modified so that the top-left corner of your element should be drawn at (0,0) and the sizes are measured in pixels. Do not use this painter after returning from your message handler.
PBMessageGetPaintBounds
Structure: Give the rectangular boundary in which your element can drawn. For elements with the PBElement_CUSTOM_PAINT flag only.
Fields
bounds (PBRectangle): The region in which the element can be drawn, in window coordinates, in pixels.
PBDrawBox
Function: Draw a rectangle with a border, fill and rounded corners.
Syntax (C/C++)
void PBDrawBox(PBPainterRef painter, PBRectangle rectangle, PBColor fillColor,
PBColor borderColor, int32_t borderSize, int32_t cornerRadius,
uint8_t cornerMask);
Syntax (Python)
DrawBox(painter, rectangle, fillColor, borderColor, borderSize, cornerRadius, cornerMask)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] rectangle (PBRectangle): The bounding rectangle of the box to draw, given in the painter's coordinate system (typically pixels).
[in] fillColor (PBColor): The color to fill the non-border region inside the box.
[in] borderColor (PBColor): The color to fill the border region.
[in] borderSize (int32_t): The width of the border region.
[in] cornerRadius (int32_t): The radius of the rounded corners.
[in] cornerMask (uint8_t): A mask giving on which corners to disable rounding. Bit 0 disables rounding of the top-left corner; bit 1 top-right; bit 2 bottom-left; bit 3 bottom-right.
Discussion
If the painter is not applying a scaling transformation; then the border size and corner radius will be in pixels.
The bounding rectangle does not include pixels with x-coordinate equal to the right side of the rectangle parameter. Similarly, pixels with y-coordinate equal to the bottom side of the rectangle parameter are not included.
Example (C/C++)
PBDrawBox(painter, rectangle, PBColorTransparent() /* no fill */,
PBColorFromSRGB8(0xFFFF0000) /* red border */, 2, 0, 0);
See Also
PBDrawBoxShadow
Function: Draw the shadow of a rectangle with rounded corners.
Syntax (C/C++)
void PBDrawBoxShadow(PBPainterRef painter, PBRectangle originalBox,
int32_t originalCornerRadius, PBColor shadowColor, int32_t shadowOffsetX,
int32_t shadowOffsetY, int32_t shadowSpread, float shadowBlur,
PBBoxShadowMode shadowMode);
Syntax (Python)
DrawBoxShadow(painter, originalBox, originalCornerRadius, shadowColor, shadowOffsetX, shadowOffsetY, shadowSpread, shadowBlur, shadowMode)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] originalBox (PBRectangle): The bounding rectangle of the box (not the shadow).
[in] originalCornerRadius (int32_t): The radius of the rounded corners of the box (not the shadow)
[in] shadowColor (PBColor): The color to fill the shadow region.
[in] shadowOffsetX (int32_t): The horizontal offset of the shadow from the original box.
[in] shadowOffsetY (int32_t): The vertical offset of the shadow from the original box.
[in] shadowSpread (int32_t): The shadow region is extended by this amount on all sides, and the corner radius is correspondingly increased.
[in] shadowBlur (float): The standard deviation of an approximated Gaussian blur applied to the shadow.
[in] shadowMode (PBBoxShadowMode): Determines whether this is a drop-shadow or an inner-shadow.
Discussion
This function is intended to be used in conjunction with PBDrawBox. See its documentation for a description of how its bounding rectangle and corner radius is interpreted.
Note that at the time of writing blurred shadows are not fully supported on boxes with rounded corners.
Example (C/C++)
PBDrawBoxShadow(painter, rectangle, 0,
PBColorFromName(PBNamedColor_FIXED_BLACK), 10, 10, 0, 0, PBBoxShadow_OUTER);
PBDrawBox(painter, rectangle, PBColorTransparent() /* no fill */,
PBColorFromSRGB8(0xFFFF0000) /* red border */, 2, 0, 0);
See Also
PBDrawElement
Function: Draw an element and its descendents as they appear in their window.
Syntax (C/C++)
void PBDrawElement(PBPainterRef painter, PBElementRef element,
PBDrawElementFlags flags);
Syntax (Python)
DrawElement(painter, element, flags)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] element (referenced PBElement): The PBElement to draw. Its descendents will also be drawn.
[in] flags (PBDrawElementFlags): Flags bitwise OR-ed together controlling the draw operation.
Discussion
For each PBDepthIndex, the element and its non-hidden descendents will be drawn. A hidden element can be drawn with its function, but if any of its descendents are hidden, then that descendent and all of its descendents will not be drawn.
If an element is outside the painter's clip region, then no attempt may be made to draw it. In particular, for an element with the PBElement_CUSTOM_PAINT flag, it may never receive the PBMsg_CUSTOM_PAINT message.
Example (C/C++)
PBRenderSurface *surface = PBRenderSurfaceCreateCompatibleWithElement(element, PBElementGetSize(element), false);
if (surface) {
PBPainter *painter = PBRenderSurfaceBeginPainting(surface, PBBeginPainting_CLEAR, NULL)
if (painter) {
PBDrawElement(painter, element, 0);
PBRenderSurfaceEndPainting(surface, painter);
}
}
// do something with the surface...
PBRenderSurfaceRelease(surface);
See Also
PBDrawText
Function: Draw text from a text plan.
Syntax (C/C++)
void PBDrawText(PBPainterRef painter, PBTextPlanRef textPlan, int32_t originX,
int32_t originY,
/* optional */ const PBColor * _Nullable __restrict overrideColor);
Syntax (Python)
DrawText(painter, textPlan, originX, originY, overrideColor)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] textPlan (referenced PBTextPlan): The PBTextPlan to draw.
[in] originX (int32_t): The left side of the first line.
[in] originY (int32_t): The top side of the first line. The text baseline of the first line is determined by adding the largest ascent height for any glyph on this line to the top side.
[optional-in] overrideColor (PBColor): The color in which to draw the text, or null to use the colors specified within the text plan's underlying PBTextDocument.
Discussion
If overrideColor is null and the text plan does not contain any color information for a glyph, then PBNamedColor_WINDOW_TEXT is used as default; see PBNamedTextStyle_RESET.
Note well that at the time of writing that not all features involving text plans with multiple lines have been implemented.
The text plan must have been laid out (see PBTextPlanLayout) before calling this function.
Example (C/C++)
PBTextPlan *plan = PBTextPlanCreate(PB_STR("Hello, world!"), NULL, 0, window);
if (plan) {
PBTextPlanLayout(plan, 0, 0, 0);
PBDrawText(painter, plan, 0, 0, NULL);
PBTextPlanRelease(plan);
}
See Also
PBDrawTextCaret
Function: Draw a text caret.
Syntax (C/C++)
void PBDrawTextCaret(PBPainterRef painter, PBTextPlanRef textPlan,
int32_t originX, int32_t originY, uintptr_t caretTextIndex, float caretWidth,
PBColor color);
Syntax (Python)
DrawTextCaret(painter, textPlan, originX, originY, caretTextIndex, caretWidth, color)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] textPlan (referenced PBTextPlan): The PBTextPlan to draw.
[in] originX (int32_t): The left side of the first line.
[in] originY (int32_t): The top side of the first line. The text baseline of the first line is determined by adding the largest ascent height for any glyph on this line to the top side.
[in] caretTextIndex (uintptr_t): The offset, in bytes, into the text document giving the caret's position.
[in] caretWidth (float): The width of the caret, in dps. See PBSystemProperty_CARET_THICKNESS.
[in] color (PBColor): The color of the caret.
Discussion
This should be called after PBDrawText.
The text plan must have been laid out (see PBTextPlanLayout) before calling this function.
See Also
PBDrawTextSelection
Function: Draw a text selection background.
Syntax (C/C++)
void PBDrawTextSelection(PBPainterRef painter, PBTextPlanRef textPlan,
int32_t originX, int32_t originY, uintptr_t selection0, uintptr_t selection1,
PBColor color, PBDrawTextSelectionFlags flags);
Syntax (Python)
DrawTextSelection(painter, textPlan, originX, originY, selection0, selection1, color, flags)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] textPlan (referenced PBTextPlan): The PBTextPlan to draw.
[in] originX (int32_t): The left side of the first line.
[in] originY (int32_t): The top side of the first line. The text baseline of the first line is determined by adding the largest ascent height for any glyph on this line to the top side.
[in] selection0 (uintptr_t): One of the selection's offsets, in bytes, into the text document.
[in] selection1 (uintptr_t): The second offset giving the other end of the selection range.
[in] color (PBColor): The color with which to fill the selection region.
[in] flags (PBDrawTextSelectionFlags): The bitwise OR of flags controlling the operation.
Discussion
This should be called before PBDrawText.
The text plan must have been laid out (see PBTextPlanLayout) before calling this function.
See Also
PBDrawImage
Function: Draw an image.
Syntax (C/C++)
void PBDrawImage(PBPainterRef painter, PBImageRef image,
PBRectangle sourceRectangle, PBRectangle destinationRectangle, float opacity);
Syntax (Python)
DrawImage(painter, image, sourceRectangle, destinationRectangle, opacity)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] image (referenced PBImage): The PBImage to draw.
[in] sourceRectangle (PBRectangle): The region of the image, in pixels, to copy to the destination.
[in] destinationRectangle (PBRectangle): The bounding rectangle of the region into which the image is drawn.
[in] opacity (float): The opacity level at which draw the image. 0 is fully transparent and 1 is fully opaque.
Discussion
The bounding rectangle does not include pixels with x-coordinate equal to the right side of the rectangle parameter. Similarly, pixels with y-coordinate equal to the bottom side of the rectangle parameter are not included.
If you need to specify a tint color for stencil images, use PBDrawImageWithTintColor.
Example (C/C++)
PBSize imageSize = PBImageGetSize(image);
PBDrawImage(painter, image, PB_RECT_2S(imageSize.width, imageSize.height), rectangle, 1.0f);
See Also
PBDrawBitmapBuffer
Function: Draw an in-memory bitmap as an image.
Syntax (C/C++)
void PBDrawBitmapBuffer(PBPainterRef painter,
const uint8_t *_Nullable bits, size_t bitsCount, uint32_t strideInBytes,
uint32_t width, uint32_t height, PBBitmapFormat bitmapFormat,
PBColorSpaceID colorSpace, PBRectangle sourceRectangle,
PBRectangle destinationRectangle, float opacity);
Syntax (Python)
DrawBitmapBuffer(painter, bits, strideInBytes, width, height, bitmapFormat, colorSpace, sourceRectangle, destinationRectangle, opacity)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] bits (referenced array of uint8_t): The bitmap buffer, starting at the top-left pixel. The size of this array must exactly (height × strideInBytes). This memory address must be aligned to the size of a pixel.
[in] strideInBytes (uint32_t): The number of bytes between the starts of two adjacent rows of pixel data. This must be at least (width × bytesPerPixel), where bytesPerPixel is determined by the bitmap format. Additionally, it must be a multiple of bytesPerPixel.
[in] width (uint32_t): The width of the bitmap, in pixels.
[in] height (uint32_t): The height of the bitmap, in pixels.
[in] bitmapFormat (PBBitmapFormat): The format of the pixels in the bitmap buffer.
[in] colorSpace (PBColorSpaceID): The color space of the bitmap. This will be used to convert the image to the target device's color space.
[in] sourceRectangle (PBRectangle): The region of the image, in pixels, to copy to the destination.
[in] destinationRectangle (PBRectangle): The bounding rectangle of the region into which the image is drawn.
[in] opacity (float): The opacity level at which draw the image. 0 is fully transparent and 1 is fully opaque.
Discussion
If you need to draw the same bitmap multiple times, use PBImageCreateFromBitmapBuffer instead.
The bounding rectangle does not include pixels with x-coordinate equal to the right side of the rectangle parameter. Similarly, pixels with y-coordinate equal to the bottom side of the rectangle parameter are not included.
Example (C/C++)
PBDrawBitmapBuffer(painter, (uint8_t *) texture, w * h * sizeof(uint32_t), w * sizeof(uint32_t), w, h,
PBBitmapFormat_RGB8_OPAQUE, PBColorSpaceID_SRGB, PB_RECT_2S(w, h), destinationRectangle, 1.0f);
See Also
PBDrawImageWithTintColor
Function: Draw a stencil image with a specific tint color.
Syntax (C/C++)
void PBDrawImageWithTintColor(PBPainterRef painter, PBImageRef image,
PBRectangle sourceRectangle, PBRectangle destinationRectangle, float opacity,
PBColor tintColor);
Syntax (Python)
DrawImageWithTintColor(painter, image, sourceRectangle, destinationRectangle, opacity, tintColor)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] image (referenced PBImage): The PBImage to draw.
[in] sourceRectangle (PBRectangle): The region of the image, in pixels, to copy to the destination.
[in] destinationRectangle (PBRectangle): The bounding rectangle of the region into which the image is drawn.
[in] opacity (float): The opacity level at which draw the image. 0 is fully transparent and 1 is fully opaque.
[in] tintColor (PBColor): The tint color for stencil vector images.
Discussion
This function is equivalent to PBDrawImage except it allows you to specific the tint color of stencil images.
See Also
PBDrawRectangle
Function: Draw a filled rectangle.
Syntax (C/C++)
void PBDrawRectangle(PBPainterRef painter, PBRectangle rectangle, PBColor color);
Syntax (Python)
DrawRectangle(painter, rectangle, color)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] rectangle (PBRectangle): The bounding rectangle of the box to draw, given in the painter's coordinate system (typically pixels).
[in] color (PBColor): The color with which to fill the rectangle.
Discussion
This function is a wrapper around PBDrawBox. It draws a box with no border or rounded corners.
The bounding rectangle does not include pixels with x-coordinate equal to the right side of the rectangle parameter. Similarly, pixels with y-coordinate equal to the bottom side of the rectangle parameter are not included.
Example (C/C++)
PBDrawRectangle(painter, rectangle, PBColorFromSRGB8(0xFF000000) /* opaque black */);
See Also
PBPainterClipRectangle
Function: Intersect the current clip region with a rectangle.
Syntax (C/C++)
PBPreviousClipRegion PBPainterClipRectangle(PBPainterRef painter,
PBRectangle rectangle,
/* output */ bool * _Nullable __restrict isNewClipRegionNonEmpty);
Syntax (Python)
PainterClipRectangle(painter, rectangle) -> (previousClipRegion, isNewClipRegionNonEmpty)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] rectangle (PBRectangle): The rectangle to intersect with the clip region, given in the painter's coordinate system.
[out] previousClipRegion (PBPreviousClipRegion): The previous clip region before this call.
[optional-out] isNewClipRegionNonEmpty (bool): True if the new clip region is non-empty (i.e. the rectangle intersected the previous clip region); otherwise, false.
Discussion
Each call to any PBPainterClip* function must be balanced with a call to PBPainterRestoreClip, passing the returned PBPreviousClipRegion back. The calls to PBPainterRestoreClip must be made in the opposite order to the calls to PBPainterClip*.
Example (C/C++)
bool isNewClipRegionNonEmpty;
PBPreviousClipRegion previous = PBPainterClipRectangle(painter, clipToRectangle, &isNewClipRegionNonEmpty);
if (isNewClipRegionNonEmpty) {
// ...
}
PBPainterRestoreClip(painter, previous);
See Also
PBPainterRestoreClip
Function: Restore the previous clip region.
Syntax (C/C++)
void PBPainterRestoreClip(PBPainterRef painter, PBPreviousClipRegion clipRegion);
Syntax (Python)
PainterRestoreClip(painter, clipRegion)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] clipRegion (PBPreviousClipRegion): The previous clip region, returned by the function that modified the clip region.
Discussion
Each call to any PBPainterClip* function must be balanced with a call to PBPainterRestoreClip, passing the returned PBPreviousClipRegion back. The calls to PBPainterRestoreClip must be made in the opposite order to the calls to PBPainterClip*.
See Also
PBPainterIsClipRegionEmpty
Function: Check if the clip region is currently empty.
Syntax (C/C++)
bool PBPainterIsClipRegionEmpty(PBPainterRef painter);
Syntax (Python)
PainterIsClipRegionEmpty(painter) -> (isClipRegionEmpty)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[out] isClipRegionEmpty (bool): True if the clip region is empty; false if the clip region is non-empty.
Discussion
If the clip region is empty then all drawing commands will do nothing.
See Also
PBPainterGetBoundingRectangleOfClipRegion
Function: Get the bounding rectangle of the current clip region.
Syntax (C/C++)
PBRectangle PBPainterGetBoundingRectangleOfClipRegion(PBPainterRef painter);
Syntax (Python)
PainterGetBoundingRectangleOfClipRegion(painter) -> (boundingRectangleOfClipRegion)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[out] boundingRectangleOfClipRegion (PBRectangle): The smallest rectangle that entirely contains the clip region, given in the painter's coordinate system.
Discussion
If the clip region is rectangular, then the clip region is returned precisely. If the clip region is empty, then an invalid rectangle is returned (see PBRectangleValid).
See Also
PBPainterApplyTranslation
Function: Apply a translation to the painter's transformation.
Syntax (C/C++)
PBPreviousTransformation PBPainterApplyTranslation(PBPainterRef painter,
int32_t offsetX, int32_t offsetY);
Syntax (Python)
PainterApplyTranslation(painter, offsetX, offsetY) -> (previousTransformation)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] offsetX (int32_t): The translation on the x-axis.
[in] offsetY (int32_t): The translation on the y-axis.
[out] previousTransformation (PBPreviousTransformation): The painter's previous transformation. Pass this to PBPainterRestoreTransformation.
Discussion
The translation is applied to input points before all existing transformations.
Each call to any PBPainterApply* function must be balanced with a call to PBPainterRestoreTransformation, passing the returned PBPreviousTransformation back. The calls to PBPainterRestoreTransformation must be made in the opposite order to the calls to PBPainterApply*.
Example (C/C++)
PBPreviousTransformation previous = PBPainterApplyTranslation(painter, 10, 10);
// ...
PBPainterRestoreTransformation(painter, previous);
See Also
PBPainterRestoreTransformation
Function: Restore the previous transformation.
Syntax (C/C++)
void PBPainterRestoreTransformation(PBPainterRef painter,
PBPreviousTransformation transformation);
Syntax (Python)
PainterRestoreTransformation(painter, transformation)
Parameters and Return Values
[in] painter (referenced PBPainter): The PBPainter object.
[in] transformation (PBPreviousTransformation): The previous transformation, returned by the function that modified the transformation.
Discussion
Each call to any PBPainterApply* function must be balanced with a call to PBPainterRestoreTransformation, passing the returned PBPreviousTransformation back. The calls to PBPainterRestoreTransformation must be made in the opposite order to the calls to PBPainterApply*.
See Also
PBDrawRenderSurface
Function:
Syntax (C/C++)
void PBDrawRenderSurface(PBPainterRef painter, PBRenderSurfaceRef surface,
PBRectangle sourceRectangle, PBRectangle destinationRectangle, float opacity);
Syntax (Python)
DrawRenderSurface(painter, surface, sourceRectangle, destinationRectangle, opacity)
Parameters and Return Values
[in] painter (referenced PBPainter):
[in] surface (referenced PBRenderSurface):
[in] sourceRectangle (PBRectangle):
[in] destinationRectangle (PBRectangle):
[in] opacity (float):