The Blitter API provides support for issuing simple blit-style draw commands to either an offscreen surface or to a Starboard
SbWindow object. Blitter is jargon that means “BLock Transfer,” which might be abbreviated as BLT and, hence, the word “blit.”
This API is designed to allow implementations make use of GPU hardware acceleration, if it is available. Draw commands exist for solid-color rectangles and rasterization/blitting of rectangular images onto rectangular target patches. Threading Concerns
Note that in general the Blitter API is not thread safe, except for all
SbBlitterDevice-related functions. All functions that are not required to internally ensure any thread safety guarantees are prefaced with a comment indicating that they are not thread safe.
Functions which claim to not be thread safe can still be used from multiple threads, but manual synchronization must be performed in order to ensure their parameters are not referenced at the same time on another thread by another function. Examples
Multiple threads should not issue commands to the same
SbBlitterContext object unless they are manually synchronized.
Multiple threads should not issue draw calls to the same render target, even if the draw calls are made within separate contexts. In this case, be sure to manually synchronize through the use of syncrhonization primitives and use of the
Multiple threads can operate on the swap chain, but they must perform manual synchronization.
Defines the set of pixel formats that can be used with the Blitter API
SbBlitterPixelData objects. Note that not all of these formats are guaranteed to be supported by a particular device, so before using these formats in pixel data creation commands, it should be checked that they are supported first (e.g. via
SbBlitterPixelDataFormat specifies specific orderings of the color channels, and when doing so, byte- order is used, e.g. “RGBA” implies that a value for red is stored in the byte with the lowest memory address. All pixel values are assumed to be in premultiplied alpha format.
32-bit pixels with 8-bits per channel, the alpha component in the byte with the lowest address and blue in the byte with the highest address.
32-bit pixels with 8-bits per channel, the blue component in the byte with the lowest address and alpha in the byte with the highest address.
32-bit pixels with 8-bits per channel, the red component in the byte with the lowest address and alpha in the byte with the highest address.
8-bit pixels that contain only a single alpha channel. When rendered, surfaces in this format will have
(R, G, B) values of
(255, 255, 255).
Constant that indicates how many unique pixel formats Starboard supports.
Enumeration that describes the color format of surfaces. Note that
SbBlitterSurfaceFormat does not differentiate between permutations of the color channel ordering (e.g. RGBA vs ARGB) since client code will never be able to access surface pixels directly. This is the main difference between
SbBlitterPixelDataFormat, which does explicitly dictate an ordering.
32-bit RGBA color, with 8 bits per channel.
8-bit alpha-only color.
Constant that indicates how many unique surface formats Starboard supports.
A simple 32-bit color representation that is a parameter to many Blitter functions.
typedef uint32_t SbBlitterColor
Defines a rectangle via a point
(x, y) and a size
(width, height). This structure is used as a parameter type in various blit calls.
SbBlitterSurfaceInfo collects information about surfaces that can be queried from them at any time.
This function achieves the same effect as calling
num_rects times with each of the
num_rects values of
dst_rects. This function allows for greater efficiency than looped calls to
This function is not thread-safe.
The return value indicates whether the draw call succeeded.
SB_DEPRECATED(bool SbBlitterBlitRectsToRects(SbBlitterContext context, SbBlitterSurface source_surface, const SbBlitterRect *src_rects, const SbBlitterRect *dst_rects, int num_rects))
Extract alpha from a
static uint8_t SbBlitterAFromColor(SbBlitterColor color)
Extract blue from a
static uint8_t SbBlitterBFromColor(SbBlitterColor color)
A convenience function to return the number of bytes per pixel for a given pixel format.
static int SbBlitterBytesPerPixelForFormat(SbBlitterPixelDataFormat format)
A convenience function to create a
SbBlitterColor object from separate 8-bit RGBA components.
static SbBlitterColor SbBlitterColorFromRGBA(uint8_t r, uint8_t g, uint8_t b, uint8_t a)
Extract green from a
static uint8_t SbBlitterGFromColor(SbBlitterColor color)
Checks whether a blitter context is invalid.
static bool SbBlitterIsContextValid(SbBlitterContext context)
Checks whether a blitter device is invalid.
static bool SbBlitterIsDeviceValid(SbBlitterDevice device)
Checks whether a pixel data object is invalid.
static bool SbBlitterIsPixelDataValid(SbBlitterPixelData pixel_data)
Checks whether a render target is invalid.
static bool SbBlitterIsRenderTargetValid(SbBlitterRenderTarget render_target)
Checks whether a surface is invalid.
static bool SbBlitterIsSurfaceValid(SbBlitterSurface surface)
Checks whether a swap chain is invalid.
static bool SbBlitterIsSwapChainValid(SbBlitterSwapChain swap_chain)
Convenience function to setup a rectangle with the specified parameters.
static SbBlitterRect SbBlitterMakeRect(int x, int y, int width, int height)
This function maps SbBlitterPixelDataFormat values to their corresponding
SbBlitterSurfaceFormat value. Note that many
SbBlitterPixelDataFormats correspond to the same
SbBlitterSurfaceFormat, so this function is not invertible. When creating a
SbBlitterSurface object from a
SbBlitterPixelData object, the
SbBlitterSurface's format will be computed from the
SbBlitterPixelData object by using this function.
static SbBlitterSurfaceFormat SbBlitterPixelDataFormatToSurfaceFormat(SbBlitterPixelDataFormat pixel_format)
Extract red from a
static uint8_t SbBlitterRFromColor(SbBlitterColor color)