Starboard Module Reference: blitter.h

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 SbBlitterFlushContext() command.
  • Multiple threads can operate on the swap chain, but they must perform manual synchronization.

Enums

SbBlitterPixelDataFormat

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 SbBlitterIsPixelFormatSupportedByPixelData()). 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.

Values

  • kSbBlitterPixelDataFormatARGB8 - 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.
  • kSbBlitterPixelDataFormatBGRA8 - 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.
  • kSbBlitterPixelDataFormatRGBA8 - 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.
  • kSbBlitterPixelDataFormatA8 - 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).
  • kSbBlitterNumPixelDataFormats - Constant that indicates how many unique pixel formats Starboard supports.
  • kSbBlitterInvalidPixelDataFormat

SbBlitterSurfaceFormat

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.

Values

  • kSbBlitterSurfaceFormatRGBA8 - 32-bit RGBA color, with 8 bits per channel.
  • kSbBlitterSurfaceFormatA8 - 8-bit alpha-only color.
  • kSbBlitterNumSurfaceFormats - Constant that indicates how many unique surface formats Starboard supports.
  • kSbBlitterInvalidSurfaceFormat

Structs

SbBlitterContextPrivate

SbBlitterContext objects represent a stateful communications channel with a device. All state changes and draw calls are made through a specific SbBlitterContext object. Every draw call made on a SbBlitterContext is submitted to the device with the SbBlitterContext's current state applied to it.
Draw calls may be submitted to the device as they are made on the SbBlitterContext. However, they are not guaranteed to be submitted until the SbBlitterContext object is flushed. That is, until you call SbBlitterFlushContext, you are not guaranteed that any API calls you have made have been received or acted on by the graphics device.

SbBlitterDevicePrivate

A SbBlitterDevice object represents a process' connection to a blitter device, such as a GPU. It is through this device that all subsequent Blitter API functionality can be accessed.

SbBlitterPixelDataPrivate

A SbBlitterPixelData object represents a buffer of pixels stored in CPU-accessible memory. In order to upload pixel data from the CPU to the GPU, clients should first create a SbBlitterPixelData object, fill in the pixel data, and then re-submit the filled in SbBlitterPixelData object to the Blitter API in order to obtain a SbBlitterSurface object that can be referenced by draw calls.

SbBlitterRect

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.

Members

Members
int
x
int
y
int
width
int
height

SbBlitterRenderTargetPrivate

A SbBlitterRenderTarget may be obtained from either a SbBlitterSwapChain if it represents a primary display output, or through a SbBlitterSurface if it represents an offscreen rendering target. A SbBlitterRenderTarget must be specified within a SbBlitterContext before making a draw call.

SbBlitterSurfaceInfo

SbBlitterSurfaceInfo collects information about surfaces that can be queried from them at any time.

Members

Members
int
width
int
height
SbBlitterSurfaceFormat
format

SbBlitterSurfacePrivate

A SbBlitterSurface object represents a device-side surface of pixel data that can be used as either the source or the target of device draw calls. Note that depending on how the surface is created, it may not be able to offer the ability to obtain a SbBlitterRenderTarget. SbBlitterSurface objects may be populated by data either by the CPU via SbBlitterPixelData objects, or via the device by using this SbBlitterSurface's SbBlitterRenderTarget object as the target of draw calls.

SbBlitterSwapChainPrivate

A SbBlitterSwapChain represents the (potentially back buffered) output display device. A SbBlitterRenderTarget can be retrieved from a SbBlitterSwapChain, providing a target for draw commands. The SbBlitterSwapChain object also exposes the ability to flip back buffers.

Functions

SbBlitterAFromColor

Declaration

static SB_C_FORCE_INLINE uint8_t SbBlitterAFromColor(SbBlitterColor color) {
  return (color & 0x000000FF) >> 0;
}

Parameters

Parameters
SbBlitterColor
color

SbBlitterBFromColor

Declaration

static SB_C_FORCE_INLINE uint8_t SbBlitterBFromColor(SbBlitterColor color) {
  return (color & 0x0000FF00) >> 8;
}

Parameters

Parameters
SbBlitterColor
color

SbBlitterBlitRectToRect

Description

Issues a draw call on context that blits the area of source_surface specified by src_rect to context's current render target at dst_rect. The source rectangle must lie within the dimensions of source_surface. Note that the source_surface's alpha is modulated by opacity before being drawn. For opacity, a value of 0 implies complete invisibility, and a value of 255 implies complete opacity.
This function is not thread-safe.
The return value indicates whether the draw call succeeded.

Declaration

SB_EXPORT bool SbBlitterBlitRectToRect(SbBlitterContext context,
                                       SbBlitterSurface source_surface,
                                       SbBlitterRect src_rect,
                                       SbBlitterRect dst_rect);

Parameters

Parameters
SbBlitterContext
context
SbBlitterSurface
source_surface
SbBlitterRect
src_rect
The area to be block transferred (blitted).
SbBlitterRect
dst_rect

SbBlitterBlitRectToRectTiled

Description

This function functions identically to SbBlitterBlitRectToRect(), except it permits values of src_rect outside the dimensions of source_surface. In those regions, the pixel data from source_surface will be wrapped. Negative values for src_rect.x and src_rect.y are allowed.
The output is all stretched to fit inside of dst_rect.
This function is not thread-safe.
The return value indicates whether the draw call succeeded.

Declaration

SB_EXPORT bool SbBlitterBlitRectToRectTiled(SbBlitterContext context,
                                            SbBlitterSurface source_surface,
                                            SbBlitterRect src_rect,
                                            SbBlitterRect dst_rect);

Parameters

Parameters
SbBlitterContext
context
SbBlitterSurface
source_surface
SbBlitterRect
src_rect
SbBlitterRect
dst_rect

SbBlitterBlitRectsToRects

Description

This function achieves the same effect as calling SbBlitterBlitRectToRect() num_rects times with each of the num_rects values of src_rects and dst_rects. This function allows for greater efficiency than looped calls to SbBlitterBlitRectToRect().
This function is not thread-safe.
The return value indicates whether the draw call succeeded.

Declaration

SB_EXPORT bool SbBlitterBlitRectsToRects(SbBlitterContext context,
                                         SbBlitterSurface source_surface,
                                         const SbBlitterRect* src_rects,
                                         const SbBlitterRect* dst_rects,
                                         int num_rects);

Parameters

Parameters
SbBlitterContext
context
SbBlitterSurface
source_surface
const SbBlitterRect*
src_rects
const SbBlitterRect*
dst_rects
int
num_rects

SbBlitterBytesPerPixelForFormat

Description

A convenience function to return the number of bytes per pixel for a given pixel format.

Declaration

static SB_C_FORCE_INLINE int SbBlitterBytesPerPixelForFormat(
    SbBlitterPixelDataFormat format) {
  switch (format) {
    case kSbBlitterPixelDataFormatARGB8:
      return 4;
    case kSbBlitterPixelDataFormatBGRA8:
      return 4;
    case kSbBlitterPixelDataFormatRGBA8:
      return 4;
    case kSbBlitterPixelDataFormatA8:
      return 1;
    default:
      return 0;
  }
}

Parameters

Parameters
SbBlitterPixelDataFormat
format

SbBlitterColorFromRGBA

Description

A convenience function to create a SbBlitterColor object from separate 8-bit RGBA components.

Declaration

static SB_C_FORCE_INLINE SbBlitterColor SbBlitterColorFromRGBA(uint8_t r,
                                                               uint8_t g,
                                                               uint8_t b,
                                                               uint8_t a) {
  return (r << 24) | (g << 16) | (b << 8) | a;
}

Parameters

Parameters
uint8_t
r
uint8_t
g
uint8_t
b
uint8_t
a

SbBlitterCreateContext

Description

Creates an SbBlitterContext object on device. The returned context can be used to set up draw state and issue draw calls.
Note that there is a limit on the number of contexts that can exist simultaneously, which can be queried by calling SbBlitterGetMaxContexts(). (The limit is often 1.)
SbBlitterContext objects keep track of draw state between a series of draw calls. Please refer to the SbBlitterContext() definition for more information about contexts.
This function is thread-safe.
This function returns kSbBlitterInvalidContext upon failure. Note that the function fails if it has already been used to create the maximum number of contexts.

Declaration

SB_EXPORT SbBlitterContext SbBlitterCreateContext(SbBlitterDevice device);

Parameters

Parameters
SbBlitterDevice
device
The SbBlitterDevice for which the SbBlitterContext object is created.

SbBlitterCreateDefaultDevice

Description

Creates and returns an SbBlitterDevice based on the Blitter API implementation's decision of which device should be the default. The returned SbBlitterDevice represents a connection to a device (like a GPU).
On many platforms there is always one single obvious choice for a device to use, and that is the one that this function will return. For example, if this is called on a platform that has a single GPU, this call should return an object that represents that GPU. On a platform that has no GPU, an object representing a software CPU implementation may be returned.
Only one default device can exist within a process at a time. This function is thread-safe. Returns kSbBlitterInvalidDevice on failure.

Declaration

SB_EXPORT SbBlitterDevice SbBlitterCreateDefaultDevice();

SbBlitterCreatePixelData

Description

Allocates an SbBlitterPixelData object through device with width, height and pixel_format. pixel_format must be supported by device (see SbBlitterIsPixelFormatSupportedByPixelData()). This function is thread-safe.
Calling this function results in the allocation of CPU-accessible (though perhaps blitter-device-resident) memory to store pixel data of the requested size/format. An SbBlitterPixelData object should eventually be passed either into a call to SbBlitterCreateSurfaceFromPixelData() or into a call to SbBlitterDestroyPixelData().
Returns kSbBlitterInvalidPixelData upon failure.

Declaration

SB_EXPORT SbBlitterPixelData
SbBlitterCreatePixelData(SbBlitterDevice device,
                         int width,
                         int height,
                         SbBlitterPixelDataFormat pixel_format);

Parameters

Parameters
SbBlitterDevice
device
int
width
int
height
SbBlitterPixelDataFormat
pixel_format

SbBlitterCreateRenderTargetSurface

Description

Creates a new surface with undefined pixel data on device with the specified width, height and surface_format. One can set the pixel data on the resulting surface by getting its associated SbBlitterRenderTarget object and then calling SbBlitterGetRenderTargetFromSurface().
This function is thread-safe.
Returns kSbBlitterInvalidSurface upon failure.

Declaration

SB_EXPORT SbBlitterSurface
SbBlitterCreateRenderTargetSurface(SbBlitterDevice device,
                                   int width,
                                   int height,
                                   SbBlitterSurfaceFormat surface_format);

Parameters

Parameters
SbBlitterDevice
device
int
width
int
height
SbBlitterSurfaceFormat
surface_format

SbBlitterCreateSurfaceFromPixelData

Description

Creates an SbBlitterSurface object on device. Note that device must match the device that was used to create the SbBlitterPixelData object provided via the pixel_data parameter.
This function also destroys the input pixel_data object. As a result, pixel_data should not be accessed again after a call to this function.
The returned object cannot be used as a render target (e.g. calling SbBlitterGetRenderTargetFromSurface() on it will return SbBlitterInvalidRenderTarget).
This function is thread-safe with respect to device, but pixel_data should not be modified on another thread while this function is called.
Returns kSbBlitterInvalidSurface in the event of an error.

Declaration

SB_EXPORT SbBlitterSurface
SbBlitterCreateSurfaceFromPixelData(SbBlitterDevice device,
                                    SbBlitterPixelData pixel_data);

Parameters

Parameters
SbBlitterDevice
device
SbBlitterPixelData
pixel_data

SbBlitterCreateSwapChainFromWindow

Description

Creates and returns an SbBlitterSwapChain that can then be used to send graphics to the display. This function links device to window's output, and drawing to the returned swap chain will result in device being used to render to window.
This function must be called from the thread that called SbWindowCreate() to create window.
Returns kSbBlitterInvalidSwapChain on failure.

Declaration

SB_EXPORT SbBlitterSwapChain
SbBlitterCreateSwapChainFromWindow(SbBlitterDevice device, SbWindow window);

Parameters

Parameters
SbBlitterDevice
device
SbWindow
window

SbBlitterDestroyContext

Description

Destroys the specified context, freeing all its resources. This function is not thread-safe.
The return value indicates whether the destruction succeeded.

Declaration

SB_EXPORT bool SbBlitterDestroyContext(SbBlitterContext context);

Parameters

Parameters
SbBlitterContext
context
The object to be destroyed.

SbBlitterDestroyDevice

Description

Destroys device, cleaning up all resources associated with it. This function is thread-safe, but it should not be called if device is still being accessed elsewhere.
The return value indicates whether the destruction succeeded.

Declaration

SB_EXPORT bool SbBlitterDestroyDevice(SbBlitterDevice device);

Parameters

Parameters
SbBlitterDevice
device
The SbBlitterDevice object to be destroyed.

SbBlitterDestroyPixelData

Description

Destroys pixel_data. Note that this function does not need to be called and should not be called if SbBlitterCreateSurfaceFromPixelData() has been called on pixel_data before. This function is thread-safe.
The return value indicates whether the destruction succeeded.

Declaration

SB_EXPORT bool SbBlitterDestroyPixelData(SbBlitterPixelData pixel_data);

Parameters

Parameters
SbBlitterPixelData
pixel_data
The object to be destroyed.

SbBlitterDestroySurface

Description

Destroys the surface object, cleaning up all resources associated with it. This function is not thread safe.
The return value indicates whether the destruction succeeded.

Declaration

SB_EXPORT bool SbBlitterDestroySurface(SbBlitterSurface surface);

Parameters

Parameters
SbBlitterSurface
surface
The object to be destroyed.

SbBlitterDestroySwapChain

Description

Destroys swap_chain, cleaning up all resources associated with it. This function is not thread-safe and must be called on the same thread that called SbBlitterCreateSwapChainFromWindow().
The return value indicates whether the destruction succeeded.

Declaration

SB_EXPORT bool SbBlitterDestroySwapChain(SbBlitterSwapChain swap_chain);

Parameters

Parameters
SbBlitterSwapChain
swap_chain
The SbBlitterSwapChain to be destroyed.

SbBlitterDownloadSurfacePixels

Description

Downloads surface pixel data into CPU memory pointed to by out_pixel_data, formatted according to the requested pixel_format and the requested pitch_in_bytes. Before calling this function, you can call SbBlitterIsPixelFormatSupportedByDownloadSurfacePixels() to confirm that pixel_format is, in fact, valid for surface.
When this function is called, it first waits for all previously flushed graphics commands to be executed by the device before downloading the data. Since this function waits for the pipeline to empty, it should be used sparingly, such as within in debug or test environments.
The return value indicates whether the pixel data was downloaded successfully.
The returned alpha format is premultiplied.
This function is not thread-safe.

Declaration

SB_EXPORT bool SbBlitterDownloadSurfacePixels(
    SbBlitterSurface surface,
    SbBlitterPixelDataFormat pixel_format,
    int pitch_in_bytes,
    void* out_pixel_data);

Parameters

Parameters
SbBlitterSurface
surface
SbBlitterPixelDataFormat
pixel_format
int
pitch_in_bytes
void*
out_pixel_data
A pointer to a region of memory with a size of surface_height * pitch_in_bytes bytes.

SbBlitterFillRect

Description

Issues a draw call on context that fills the specified rectangle rect. The rectangle's color is determined by the last call to SbBlitterSetColor().
This function is not thread-safe.
The return value indicates whether the draw call succeeded.

Declaration

SB_EXPORT bool SbBlitterFillRect(SbBlitterContext context, SbBlitterRect rect);

Parameters

Parameters
SbBlitterContext
context
The context on which the draw call will operate.
SbBlitterRect
rect
The rectangle to be filled.

SbBlitterFlipSwapChain

Description

Flips the swap_chain by making the buffer previously accessible to draw commands via SbBlitterGetRenderTargetFromSwapChain() visible on the display, while another buffer in an initially undefined state is set up as the new draw command target. Note that you do not need to call SbBlitterGetRenderTargetFromSwapChain() again after flipping, the swap chain's render target always refers to its current back buffer.
This function stalls the calling thread until the next vertical refresh. In addition, to ensure consistency with the Starboard Player API when rendering punch-out video, calls to SbPlayerSetBounds() do not take effect until this method is called.
The return value indicates whether the flip succeeded.
This function is not thread-safe.

Declaration

SB_EXPORT bool SbBlitterFlipSwapChain(SbBlitterSwapChain swap_chain);

Parameters

Parameters
SbBlitterSwapChain
swap_chain
The SbBlitterSwapChain to be flipped.

SbBlitterFlushContext

Description

Flushes all draw calls previously issued to context. Calling this function guarantees that the device processes all draw calls issued to this point on this context before processing any subsequent draw calls on any context.
Before calling SbBlitterFlipSwapChain(), it is often prudent to call this function to ensure that all draw calls are submitted before the flip occurs.
This function is not thread-safe.
The return value indicates whether the flush succeeded.

Declaration

SB_EXPORT bool SbBlitterFlushContext(SbBlitterContext context);

Parameters

Parameters
SbBlitterContext
context
The context for which draw calls are being flushed.

SbBlitterGFromColor

Declaration

static SB_C_FORCE_INLINE uint8_t SbBlitterGFromColor(SbBlitterColor color) {
  return (color & 0x00FF0000) >> 16;
}

Parameters

Parameters
SbBlitterColor
color

SbBlitterGetMaxContexts

Description

Returns the maximum number of contexts that device can support in parallel. Note that devices often support only a single context.
This function is thread-safe.
This function returns -1 upon failure.

Declaration

SB_EXPORT int SbBlitterGetMaxContexts(SbBlitterDevice device);

Parameters

Parameters
SbBlitterDevice
device
The SbBlitterDevice for which the maximum number of contexts is returned.

SbBlitterGetPixelDataPitchInBytes

Description

Retrieves the pitch (in bytes) for pixel_data. This indicates the number of bytes per row of pixel data in the image. This function is not thread-safe.
Returns -1 in the event of an error.

Declaration

SB_EXPORT int SbBlitterGetPixelDataPitchInBytes(SbBlitterPixelData pixel_data);

Parameters

Parameters
SbBlitterPixelData
pixel_data
The object for which you are retrieving the pitch.

SbBlitterGetPixelDataPointer

Description

Retrieves a CPU-accessible pointer to the pixel data represented by pixel_data. This pixel data can be modified by the CPU to initialize it on the CPU before calling SbBlitterCreateSurfaceFromPixelData().
Note that the pointer returned here is valid as long as pixel_data is valid, which means it is valid until either SbBlitterCreateSurfaceFromPixelData() or SbBlitterDestroyPixelData() is called.
This function is not thread-safe.
Returns NULL in the event of an error.

Declaration

SB_EXPORT void* SbBlitterGetPixelDataPointer(SbBlitterPixelData pixel_data);

Parameters

Parameters
SbBlitterPixelData
pixel_data

SbBlitterGetRenderTargetFromSurface

Description

Returns the SbBlitterRenderTarget object owned by surface. The returned object can be used as a target for draw calls.
This function returns kSbBlitterInvalidRenderTarget if surface is not able to provide a render target or on any other error.
This function is not thread-safe.

Declaration

SB_EXPORT SbBlitterRenderTarget
SbBlitterGetRenderTargetFromSurface(SbBlitterSurface surface);

Parameters

Parameters
SbBlitterSurface
surface

SbBlitterGetRenderTargetFromSwapChain

Description

Returns the SbBlitterRenderTarget object that is owned by swap_chain. The returned object can be used to provide a target to blitter draw calls that draw directly to the display buffer. This function is not thread-safe.
Returns kSbBlitterInvalidRenderTarget on failure.

Declaration

SB_EXPORT SbBlitterRenderTarget
SbBlitterGetRenderTargetFromSwapChain(SbBlitterSwapChain swap_chain);

Parameters

Parameters
SbBlitterSwapChain
swap_chain
The SbBlitterSwapChain for which the target object is being retrieved.

SbBlitterGetSurfaceInfo

Description

Retrieves an SbBlitterSurfaceInfo structure, which describes immutable parameters of the surface, such as its width, height and pixel format. The results are set on the output parameter surface_info, which cannot be NULL.
The return value indicates whether the information was retrieved successfully.
This function is not thread-safe.

Declaration

SB_EXPORT bool SbBlitterGetSurfaceInfo(SbBlitterSurface surface,
                                       SbBlitterSurfaceInfo* surface_info);

Parameters

Parameters
SbBlitterSurface
surface
SbBlitterSurfaceInfo*
surface_info

SbBlitterIsContextValid

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsContextValid(
    SbBlitterContext context) {
  return context != kSbBlitterInvalidContext;
}

Parameters

Parameters
SbBlitterContext
context

SbBlitterIsDeviceValid

Description

Helper functions to check whether or not a blitter object is invalid.

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsDeviceValid(SbBlitterDevice device) {
  return device != kSbBlitterInvalidDevice;
}

Parameters

Parameters
SbBlitterDevice
device

SbBlitterIsPixelDataValid

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsPixelDataValid(
    SbBlitterPixelData pixel_data) {
  return pixel_data != kSbBlitterInvalidPixelData;
}

Parameters

Parameters
SbBlitterPixelData
pixel_data

SbBlitterIsPixelFormatSupportedByDownloadSurfacePixels

Description

Indicates whether the combination of parameter values is valid for calls to SbBlitterDownloadSurfacePixels().
This function is not thread-safe.

Declaration

SB_EXPORT bool SbBlitterIsPixelFormatSupportedByDownloadSurfacePixels(
    SbBlitterSurface surface,
    SbBlitterPixelDataFormat pixel_format);

Parameters

Parameters
SbBlitterSurface
surface
The surface being checked.
SbBlitterPixelDataFormat
pixel_format
The pixel format that would be used on the surface.

SbBlitterIsPixelFormatSupportedByPixelData

Description

Indicates whether device supports calls to SbBlitterCreatePixelData with the specified pixel_format. This function is thread-safe.

Declaration

SB_EXPORT bool SbBlitterIsPixelFormatSupportedByPixelData(
    SbBlitterDevice device,
    SbBlitterPixelDataFormat pixel_format);

Parameters

Parameters
SbBlitterDevice
device
The device for which compatibility is being checked.
SbBlitterPixelDataFormat
pixel_format
The SbBlitterPixelDataFormat for which compatibility is being checked.

SbBlitterIsRenderTargetValid

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsRenderTargetValid(
    SbBlitterRenderTarget render_target) {
  return render_target != kSbBlitterInvalidRenderTarget;
}

Parameters

Parameters
SbBlitterRenderTarget
render_target

SbBlitterIsSurfaceFormatSupportedByRenderTargetSurface

Description

Indicates whether the device supports calls to SbBlitterCreateRenderTargetSurface() with surface_format.
This function is thread-safe.

Declaration

SB_EXPORT bool SbBlitterIsSurfaceFormatSupportedByRenderTargetSurface(
    SbBlitterDevice device,
    SbBlitterSurfaceFormat surface_format);

Parameters

Parameters
SbBlitterDevice
device
The device being checked for compatibility.
SbBlitterSurfaceFormat
surface_format
The surface format being checked for compatibility.

SbBlitterIsSurfaceValid

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsSurfaceValid(
    SbBlitterSurface surface) {
  return surface != kSbBlitterInvalidSurface;
}

Parameters

Parameters
SbBlitterSurface
surface

SbBlitterIsSwapChainValid

Declaration

static SB_C_FORCE_INLINE bool SbBlitterIsSwapChainValid(
    SbBlitterSwapChain swap_chain) {
  return swap_chain != kSbBlitterInvalidSwapChain;
}

Parameters

Parameters
SbBlitterSwapChain
swap_chain

SbBlitterMakeRect

Description

Convenience function to setup a rectangle with the specified parameters.

Declaration

static SB_C_FORCE_INLINE SbBlitterRect SbBlitterMakeRect(int x,
                                                         int y,
                                                         int width,
                                                         int height) {
  SbBlitterRect rect;
  rect.x = x;
  rect.y = y;
  rect.width = width;
  rect.height = height;
  return rect;
}

Parameters

Parameters
int
x
int
y
int
width
int
height

SbBlitterRFromColor

Description

The following helper functions can be used to extract specific color components from a SbBlitterColor object.

Declaration

static SB_C_FORCE_INLINE uint8_t SbBlitterRFromColor(SbBlitterColor color) {
  return (color & 0xFF000000) >> 24;
}

Parameters

Parameters
SbBlitterColor
color

SbBlitterSetBlending

Description

Sets the blending state for the specified context. By default, blending is disabled on a SbBlitterContext.
This function is not thread-safe.
The return value indicates whether the blending state was set successfully.

Declaration

SB_EXPORT bool SbBlitterSetBlending(SbBlitterContext context, bool blending);

Parameters

Parameters
SbBlitterContext
context
The context for which the blending state is being set.
bool
blending
The blending state for the context. If blending is true, the source alpha of subsequent draw calls is used to blend with the destination color. In particular, (Fc = Sc * Sa + Dc * (1 - Sa)), where:
  • Fc is the final color.
  • Sc is the source color.
  • Sa is the source alpha.
  • Dc is the destination color. If blending is false, the source color and source alpha overwrite the destination color and alpha.

SbBlitterSetColor

Description

Sets the context's current color. The current color's default value is SbBlitterColorFromRGBA(255, 255, 255 255).
The current color affects the fill rectangle's color in calls to SbBlitterFillRect(). If SbBlitterSetModulateBlitsWithColor() has been called to enable blit color modulation, the source blit surface pixel color is also modulated by the color before being output.
This function is not thread-safe.
The return value indicates whether the color was set successfully.

Declaration

SB_EXPORT bool SbBlitterSetColor(SbBlitterContext context,
                                 SbBlitterColor color);

Parameters

Parameters
SbBlitterContext
context
The context for which the color is being set.
SbBlitterColor
color
The context's new color, specified in unpremultiplied alpha format.

SbBlitterSetModulateBlitsWithColor

Description

Sets whether or not blit calls should have their source pixels modulated by the current color, which is set using SbBlitterSetColor(), before being output. This function can apply opacity to blit calls, color alpha-only surfaces, and apply other effects.
This function is not thread-safe.
The return value indicates whether the state was set successfully.

Declaration

SB_EXPORT bool SbBlitterSetModulateBlitsWithColor(
    SbBlitterContext context,
    bool modulate_blits_with_color);

Parameters

Parameters
SbBlitterContext
context
bool
modulate_blits_with_color
Indicates whether to modulate source pixels in blit calls.

SbBlitterSetRenderTarget

Description

Sets up render_target as the render target that all subsequent draw calls made on context will use.
This function is not thread-safe.
The return value indicates whether the render target was set successfully.

Declaration

SB_EXPORT bool SbBlitterSetRenderTarget(SbBlitterContext context,
                                        SbBlitterRenderTarget render_target);

Parameters

Parameters
SbBlitterContext
context
The object for which the render target is being set.
SbBlitterRenderTarget
render_target
The target that the context should use for draw calls.

SbBlitterSetScissor

Description

Sets the scissor rectangle, which dictates a visibility area that affects all draw calls. Only pixels within the scissor rectangle are rendered, and all drawing outside of that area is clipped.
When SbBlitterSetRenderTarget() is called, that function automatically sets the scissor rectangle to the size of the specified render target. If a scissor rectangle is specified outside of the extents of the current render target bounds, it will be intersected with the render target bounds.
This function is not thread-safe.
Returns whether the scissor was successfully set. It returns an error if it is called before a render target has been specified for the context.

Declaration

SB_EXPORT bool SbBlitterSetScissor(SbBlitterContext context,
                                   SbBlitterRect rect);

Parameters

Parameters
SbBlitterContext
context
SbBlitterRect
rect

SbBlitterSurfaceFormat

Description

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.

Declaration

static SB_C_FORCE_INLINE SbBlitterSurfaceFormat
SbBlitterPixelDataFormatToSurfaceFormat(SbBlitterPixelDataFormat pixel_format) {
  switch (pixel_format) {
    case kSbBlitterPixelDataFormatARGB8:
      return kSbBlitterSurfaceFormatRGBA8;
    case kSbBlitterPixelDataFormatBGRA8:
      return kSbBlitterSurfaceFormatRGBA8;
    case kSbBlitterPixelDataFormatRGBA8:
      return kSbBlitterSurfaceFormatRGBA8;
    case kSbBlitterPixelDataFormatA8:
      return kSbBlitterSurfaceFormatA8;
    default:
      return kSbBlitterInvalidSurfaceFormat;
  }
}

Parameters

Parameters
SbBlitterPixelDataFormatToSurfaceFormat(SbBlitterPixelDataFormat
pixel_format