Images
PBImage
Opaque object handle: An image that can be loaded into a PBImageDisplay or drawn on a PBRenderSurface. Once an image has been created or loaded, it cannot be modified.
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 PBImageRetain; to decrement the reference count, call PBImageRelease. These functions are thread-safe.
PBNamedImage
Enumeration/bitset of type uint32_t: Identifiers for system-provided images. Load with PBImageCreateFromName.
Constants
PBNamedImage_COLLAPSE_MARK
PBNamedImage_COLLAPSE_MARK = 4
The symbol shown next to an expanded tree item to let the user collapse it. This is a stencil image and should be drawn with PBDrawImageWithTintColor.
PBNamedImage_EXPAND_MARK
PBNamedImage_EXPAND_MARK = 5
The symbol shown next to an collapsed tree item to let the user expand it. This is a stencil image and should be drawn with PBDrawImageWithTintColor.
PBNamedImage_SORT_ASCENDING_MARK
PBNamedImage_SORT_ASCENDING_MARK = 6
A mark used to indicate that the displayed values are sorted in ascending order.
PBNamedImage_SORT_DESCENDING_MARK
PBNamedImage_SORT_DESCENDING_MARK = 7
A mark used to indicate that the displayed values are sorted in descending order.
PBImageCreateFromPathFlags
Enumeration/bitset of type uint32_t:
Constants
PBImageCreateFromPath_LAZY
PBImageCreateFromPath_LAZY = 1<<0
Only load the file data from the file system when the image is first used.
PBImageCollectionEntry
Structure: An image collection entry for use with PBImageCreateFromImageCollection.
Fields
image (referenced PBImage): The image to be drawn.
scaleFactorFrom (uint32_t): The lowest scale factor to use for this image. Ignored for the first entry in the collection. The entries in the collection must be sorted by this value.
PBImageCreateFromBitmapBuffer
Function: Create a bitmap PBImage from an array of pixel values.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromBitmapBuffer(
const uint8_t *_Nullable bits, size_t bitsCount, uint32_t strideInBytes,
uint32_t width, uint32_t height, uint32_t dpi, PBBitmapFormat bitmapFormat,
PBColorSpaceID colorSpace);
Syntax (Python)
ImageCreateFromBitmapBuffer(bits, strideInBytes, width, height, dpi, bitmapFormat, colorSpace) -> (image)
Parameters and Return Values
[in] bits (referenced array of uint8_t): The array of pixels values. The size of each each pixel depends on the bitmap format. The top-left pixel is given first in the array. Second is the pixel to its right; and so on, until the end of the first row of pixels is reached. Then, the left-most pixel of the second row is given. The final value in the array is the pixel at the bottom-right of the image. This pointer must be aligned correctly for the size of a pixel. The system maintains a copy of this array, stored with the PBImage.
[in] strideInBytes (uint32_t): The number of bytes from the start of one row to the next. This must be at least as large as the product of the image width and the bytes per pixel. This must be a multiple of the number of bytes per pixel.
[in] width (uint32_t): The width of the image in pixels. That is, the number of columns. This cannot be larger than 30,000.
[in] height (uint32_t): The height of the image in pixels. That is, the number of rows. This cannot be larger than 30,000.
[in] dpi (uint32_t): The density of the image, in dots (pixels) per inch. The density must be the same on both the vertical and horizontal axes. Set to 0 if unknown. For a screen with a scale factor of 100%, an image of 72 DPI will have its pixels match exactly with screen pixels.
[in] bitmapFormat (PBBitmapFormat): The format of the bitmap, determining the number of bytes that are used to store each pixel.
[in] colorSpace (PBColorSpaceID): The color space in which the pixel values are specified. This cannot be PBColorSpaceID_NAMED. The color space must be compatible with the bitmap format.
[out] image (nullable owned PBImage): The resulting image, or null on failure.
See Also
PBImageCreateFromData
Function: Load an image from a data buffer in an image file format.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromData(
const uint8_t *_Nullable dataBuffer, size_t dataBufferCount);
Syntax (Python)
ImageCreateFromData(dataBuffer) -> (image)
Parameters and Return Values
[in] dataBuffer (referenced array of uint8_t): The array containing the file data.
[out] image (nullable owned PBImage): The resulting image, or null on failure.
Discussion
At minimum, the following file formats will be supported: PNG files, JPEG files, Playbit vector icons.
See Also
PBImageCreateFromResource
Function: Load an image from the application's resource folder.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromResource(ConstStr resourceRelativePath);
Syntax (Python)
ImageCreateFromResource(resourceRelativePath) -> (image)
Parameters and Return Values
[in] resourceRelativePath (referenced string): The relative path, starting from the base of the application's resource folder.
[out] image (nullable owned PBImage): The resulting image, or null on failure.
Discussion
The application's resource folder is currently the "res" folder inside the application bundle.
At minimum, the following file formats will be supported: PNG files, JPEG files, Playbit vector icons.
See Also
PBImageCreateFromName
Function: Load the image with a given named image identifier.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromName(PBNamedImage namedImage);
Syntax (Python)
ImageCreateFromName(namedImage) -> (image)
Parameters and Return Values
[in] namedImage (PBNamedImage): The image's identifier.
[out] image (nullable owned PBImage): The resulting image, or null on failure.
See Also
PBImageCreateFromImageCollection
Function: Create a virtual PBImage from an array of images. When the virtual image is drawn, an appropriate image is selected from the collection based on the properties of the destination render surface.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromImageCollection(
const PBImageCollectionEntry *_Nullable entries, size_t entriesCount);
Syntax (Python)
ImageCreateFromImageCollection(entries) -> (image)
Parameters and Return Values
[in] entries (referenced array of PBImageCollectionEntry): The array of images. This must be non-empty. It must be sorted by the scaleFactorFrom field.
[out] image (nullable owned PBImage): The resulting image, or null on failure.
Discussion
The values returned by PBImageSize and PBImageGetSizeScaledForDisplayInWindow are determined by the first image in the collection.
Example (C/C++)
// When drawing this image collection,
// the bitmap will be used at a scale factor of 100%,
// and the vector will be used otherwise.
PBImageCollectionEntry entries[] = {
{ .image = bitmapImage },
{ .image = vectorImage, .scaleFactorFrom = 101 },
};
PBImage *collection = PBImageCreateFromImageCollection(&entries[0], 2);
PBImageRelease(bitmapImage);
PBImageRelease(vectorImage);
// ... use the image ...
PBImageRelease(collection);
PBImageCreateFromPath
Function: Create an image from a file on the file system.
Syntax (C/C++)
PBImagePtr _Nullable PBImageCreateFromPath(ConstStr path,
PBImageCreateFromPathFlags flags);
Syntax (Python)
ImageCreateFromPath(path, flags) -> (image)
Parameters and Return Values
[in] path (referenced string): The file system path to the image. This must be an absolute path.
[in] flags (PBImageCreateFromPathFlags):
[out] image (nullable owned PBImage): The resulting image, or null on failure.
Discussion
This function is wrapper around PBImageCreateFromData. See its page for more information on what image formats are supported.
See Also
PBImageGetSize
Function: Get the dimensions of an image in pixels.
Syntax (C/C++)
PBSize PBImageGetSize(PBImageRef image);
Syntax (Python)
ImageGetSize(image) -> (size)
Parameters and Return Values
[in] image (referenced PBImage): The image object.
[out] size (PBSize): For a bitmap image, this is the exact size of the bitmap in pixels. For a vector image, this is the size in pixels at which it should be drawn for a screen with a scale factor of 100%.
See Also
PBImageGetSizeScaledForDisplayInWindow
Function: Get the size that an image should be drawn at, in pixels, when drawing on the specified window.
Syntax (C/C++)
PBSize PBImageGetSizeScaledForDisplayInWindow(PBImageRef image,
PBWindowRef window);
Syntax (Python)
ImageGetSizeScaledForDisplayInWindow(image, window) -> (size)
Parameters and Return Values
[in] image (referenced PBImage): The image object.
[in] window (referenced PBWindow): The window in which the image shall be drawn.
[out] size (PBSize): The size at which to draw the image, in pixels.
See Also
PBImageGetSizeScaledForScaleFactor
Function: Get the size that an image should be drawn at, in pixels, when drawing on a screen with a given scale factor.
Syntax (C/C++)
PBSize PBImageGetSizeScaledForScaleFactor(PBImageRef image, uint32_t scaleFactor);
Syntax (Python)
ImageGetSizeScaledForScaleFactor(image, scaleFactor) -> (size)
Parameters and Return Values
[in] image (referenced PBImage): The image object.
[in] scaleFactor (uint32_t): The scale factor of the screen in which the image shall be drawn.
[out] size (PBSize): The size at which to draw the image, in pixels.