| // Copyright 2016 Google Inc. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| // Module Overview: Starboard Blitter API |
| // |
| // 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. |
| |
| #ifndef STARBOARD_BLITTER_H_ |
| #define STARBOARD_BLITTER_H_ |
| |
| #include "starboard/configuration.h" |
| #include "starboard/export.h" |
| #include "starboard/types.h" |
| #include "starboard/window.h" |
| |
| #if SB_HAS(BLITTER) |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // 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. |
| typedef struct SbBlitterDevicePrivate SbBlitterDevicePrivate; |
| typedef SbBlitterDevicePrivate* SbBlitterDevice; |
| #define kSbBlitterInvalidDevice ((SbBlitterDevice)NULL) |
| |
| // 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. |
| typedef struct SbBlitterSwapChainPrivate SbBlitterSwapChainPrivate; |
| typedef SbBlitterSwapChainPrivate* SbBlitterSwapChain; |
| #define kSbBlitterInvalidSwapChain ((SbBlitterSwapChain)NULL) |
| |
| // 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. |
| typedef struct SbBlitterRenderTargetPrivate SbBlitterRenderTargetPrivate; |
| typedef SbBlitterRenderTargetPrivate* SbBlitterRenderTarget; |
| #define kSbBlitterInvalidRenderTarget ((SbBlitterRenderTarget)NULL) |
| |
| // 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. |
| typedef struct SbBlitterPixelDataPrivate SbBlitterPixelDataPrivate; |
| typedef SbBlitterPixelDataPrivate* SbBlitterPixelData; |
| #define kSbBlitterInvalidPixelData ((SbBlitterPixelData)NULL) |
| |
| // 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. |
| typedef struct SbBlitterSurfacePrivate SbBlitterSurfacePrivate; |
| typedef SbBlitterSurfacePrivate* SbBlitterSurface; |
| #define kSbBlitterInvalidSurface ((SbBlitterSurface)NULL) |
| |
| // 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. |
| typedef struct SbBlitterContextPrivate SbBlitterContextPrivate; |
| typedef SbBlitterContextPrivate* SbBlitterContext; |
| #define kSbBlitterInvalidContext ((SbBlitterContext)NULL) |
| |
| // A simple 32-bit color representation that is a parameter to many Blitter |
| // functions. |
| typedef uint32_t SbBlitterColor; |
| |
| // 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. |
| typedef enum SbBlitterPixelDataFormat { |
| // 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. |
| kSbBlitterPixelDataFormatARGB8, |
| // 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. |
| kSbBlitterPixelDataFormatBGRA8, |
| // 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. |
| kSbBlitterPixelDataFormatRGBA8, |
| // 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). |
| kSbBlitterPixelDataFormatA8, |
| |
| // Constant that indicates how many unique pixel formats Starboard supports. |
| kSbBlitterNumPixelDataFormats, |
| kSbBlitterInvalidPixelDataFormat = kSbBlitterNumPixelDataFormats, |
| } SbBlitterPixelDataFormat; |
| |
| // 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. |
| typedef enum SbBlitterSurfaceFormat { |
| // 32-bit RGBA color, with 8 bits per channel. |
| kSbBlitterSurfaceFormatRGBA8, |
| |
| // 8-bit alpha-only color. |
| kSbBlitterSurfaceFormatA8, |
| |
| // Constant that indicates how many unique surface formats Starboard supports. |
| kSbBlitterNumSurfaceFormats, |
| kSbBlitterInvalidSurfaceFormat = kSbBlitterNumSurfaceFormats, |
| } SbBlitterSurfaceFormat; |
| |
| // 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. |
| typedef struct SbBlitterRect { |
| int x; |
| int y; |
| int width; |
| int height; |
| } SbBlitterRect; |
| |
| // SbBlitterSurfaceInfo collects information about surfaces that can be queried |
| // from them at any time. |
| typedef struct SbBlitterSurfaceInfo { |
| int width; |
| int height; |
| SbBlitterSurfaceFormat format; |
| } SbBlitterSurfaceInfo; |
| |
| // A convenience function to create a SbBlitterColor object from separate |
| // 8-bit RGBA components. |
| 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; |
| } |
| |
| // The following helper functions can be used to extract specific color |
| // components from a SbBlitterColor object. |
| static SB_C_FORCE_INLINE uint8_t SbBlitterRFromColor(SbBlitterColor color) { |
| return (color & 0xFF000000) >> 24; |
| } |
| |
| static SB_C_FORCE_INLINE uint8_t SbBlitterGFromColor(SbBlitterColor color) { |
| return (color & 0x00FF0000) >> 16; |
| } |
| |
| static SB_C_FORCE_INLINE uint8_t SbBlitterBFromColor(SbBlitterColor color) { |
| return (color & 0x0000FF00) >> 8; |
| } |
| |
| static SB_C_FORCE_INLINE uint8_t SbBlitterAFromColor(SbBlitterColor color) { |
| return (color & 0x000000FF) >> 0; |
| } |
| |
| // A convenience function to return the number of bytes per pixel for a given |
| // pixel format. |
| 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; |
| } |
| } |
| |
| // 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 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; |
| } |
| } |
| |
| // Convenience function to setup a rectangle with the specified parameters. |
| 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; |
| } |
| |
| // Helper functions to check whether or not a blitter object is invalid. |
| static SB_C_FORCE_INLINE bool SbBlitterIsDeviceValid(SbBlitterDevice device) { |
| return device != kSbBlitterInvalidDevice; |
| } |
| |
| static SB_C_FORCE_INLINE bool SbBlitterIsSwapChainValid( |
| SbBlitterSwapChain swap_chain) { |
| return swap_chain != kSbBlitterInvalidSwapChain; |
| } |
| |
| static SB_C_FORCE_INLINE bool SbBlitterIsRenderTargetValid( |
| SbBlitterRenderTarget render_target) { |
| return render_target != kSbBlitterInvalidRenderTarget; |
| } |
| |
| static SB_C_FORCE_INLINE bool SbBlitterIsPixelDataValid( |
| SbBlitterPixelData pixel_data) { |
| return pixel_data != kSbBlitterInvalidPixelData; |
| } |
| |
| static SB_C_FORCE_INLINE bool SbBlitterIsSurfaceValid( |
| SbBlitterSurface surface) { |
| return surface != kSbBlitterInvalidSurface; |
| } |
| |
| static SB_C_FORCE_INLINE bool SbBlitterIsContextValid( |
| SbBlitterContext context) { |
| return context != kSbBlitterInvalidContext; |
| } |
| |
| // 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. |
| SB_EXPORT SbBlitterDevice SbBlitterCreateDefaultDevice(); |
| |
| // 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. |
| // |
| // |device|: The SbBlitterDevice object to be destroyed. |
| SB_EXPORT bool SbBlitterDestroyDevice(SbBlitterDevice device); |
| |
| // 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. |
| SB_EXPORT SbBlitterSwapChain |
| SbBlitterCreateSwapChainFromWindow(SbBlitterDevice device, SbWindow window); |
| |
| // 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. |
| // |
| // |swap_chain|: The SbBlitterSwapChain to be destroyed. |
| SB_EXPORT bool SbBlitterDestroySwapChain(SbBlitterSwapChain swap_chain); |
| |
| // 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. |
| // |
| // |swap_chain|: The SbBlitterSwapChain for which the target object is being |
| // retrieved. |
| SB_EXPORT SbBlitterRenderTarget |
| SbBlitterGetRenderTargetFromSwapChain(SbBlitterSwapChain swap_chain); |
| |
| // Indicates whether |device| supports calls to SbBlitterCreatePixelData |
| // with the specified |pixel_format|. This function is thread-safe. |
| // |
| // |device|: The device for which compatibility is being checked. |
| // |pixel_format|: The SbBlitterPixelDataFormat for which compatibility is |
| // being checked. |
| SB_EXPORT bool SbBlitterIsPixelFormatSupportedByPixelData( |
| SbBlitterDevice device, |
| SbBlitterPixelDataFormat pixel_format); |
| |
| // 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. |
| SB_EXPORT SbBlitterPixelData |
| SbBlitterCreatePixelData(SbBlitterDevice device, |
| int width, |
| int height, |
| SbBlitterPixelDataFormat pixel_format); |
| |
| // 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. |
| // |
| // |pixel_data|: The object to be destroyed. |
| SB_EXPORT bool SbBlitterDestroyPixelData(SbBlitterPixelData pixel_data); |
| |
| // 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. |
| // |
| // |pixel_data|: The object for which you are retrieving the pitch. |
| SB_EXPORT int SbBlitterGetPixelDataPitchInBytes(SbBlitterPixelData pixel_data); |
| |
| // 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. |
| SB_EXPORT void* SbBlitterGetPixelDataPointer(SbBlitterPixelData pixel_data); |
| |
| // 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. |
| SB_EXPORT SbBlitterSurface |
| SbBlitterCreateSurfaceFromPixelData(SbBlitterDevice device, |
| SbBlitterPixelData pixel_data); |
| |
| // Indicates whether the |device| supports calls to |
| // SbBlitterCreateRenderTargetSurface() with |surface_format|. |
| // |
| // This function is thread-safe. |
| // |
| // |device|: The device being checked for compatibility. |
| // |surface_format|: The surface format being checked for compatibility. |
| SB_EXPORT bool SbBlitterIsSurfaceFormatSupportedByRenderTargetSurface( |
| SbBlitterDevice device, |
| SbBlitterSurfaceFormat surface_format); |
| |
| // 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. |
| SB_EXPORT SbBlitterSurface |
| SbBlitterCreateRenderTargetSurface(SbBlitterDevice device, |
| int width, |
| int height, |
| SbBlitterSurfaceFormat surface_format); |
| |
| // 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. |
| // |
| // |surface|: The object to be destroyed. |
| SB_EXPORT bool SbBlitterDestroySurface(SbBlitterSurface surface); |
| |
| // 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. |
| SB_EXPORT SbBlitterRenderTarget |
| SbBlitterGetRenderTargetFromSurface(SbBlitterSurface surface); |
| |
| // 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. |
| SB_EXPORT bool SbBlitterGetSurfaceInfo(SbBlitterSurface surface, |
| SbBlitterSurfaceInfo* surface_info); |
| |
| // Indicates whether the combination of parameter values is valid for calls |
| // to SbBlitterDownloadSurfacePixels(). |
| // |
| // This function is not thread-safe. |
| // |
| // |surface|: The surface being checked. |
| // |pixel_format|: The pixel format that would be used on the surface. |
| SB_EXPORT bool SbBlitterIsPixelFormatSupportedByDownloadSurfacePixels( |
| SbBlitterSurface surface, |
| SbBlitterPixelDataFormat pixel_format); |
| |
| // 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. |
| // |
| // |out_pixel_data|: A pointer to a region of memory with a size of |
| // (surface_height * |pitch_in_bytes| * |
| // SbBlitterBytesPerPixelForFormat(pixel_format) bytes. |
| SB_EXPORT bool SbBlitterDownloadSurfacePixels( |
| SbBlitterSurface surface, |
| SbBlitterPixelDataFormat pixel_format, |
| int pitch_in_bytes, |
| void* out_pixel_data); |
| |
| // 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. |
| // |
| // |swap_chain|: The SbBlitterSwapChain to be flipped. |
| SB_EXPORT bool SbBlitterFlipSwapChain(SbBlitterSwapChain swap_chain); |
| |
| // 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. |
| // |
| // |device|: The SbBlitterDevice for which the maximum number of contexts is |
| // returned. |
| SB_EXPORT int SbBlitterGetMaxContexts(SbBlitterDevice device); |
| |
| // 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. |
| // |
| // |device|: The SbBlitterDevice for which the SbBlitterContext object is |
| // created. |
| SB_EXPORT SbBlitterContext SbBlitterCreateContext(SbBlitterDevice device); |
| |
| // Destroys the specified |context|, freeing all its resources. This function |
| // is not thread-safe. |
| // |
| // The return value indicates whether the destruction succeeded. |
| // |
| // |context|: The object to be destroyed. |
| SB_EXPORT bool SbBlitterDestroyContext(SbBlitterContext context); |
| |
| // 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. |
| // |
| // |context|: The context for which draw calls are being flushed. |
| SB_EXPORT bool SbBlitterFlushContext(SbBlitterContext context); |
| |
| // 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. |
| // |
| // |context|: The object for which the render target is being set. |
| // |render_target|: The target that the |context| should use for draw calls. |
| SB_EXPORT bool SbBlitterSetRenderTarget(SbBlitterContext context, |
| SbBlitterRenderTarget render_target); |
| |
| // 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. |
| // |
| // |context|: The context for which the blending state is being set. |
| // |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. |
| SB_EXPORT bool SbBlitterSetBlending(SbBlitterContext context, bool blending); |
| |
| // 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. |
| // |
| // |context|: The context for which the color is being set. |
| // |color|: The context's new color, specified in unpremultiplied alpha format. |
| SB_EXPORT bool SbBlitterSetColor(SbBlitterContext context, |
| SbBlitterColor color); |
| |
| // 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. |
| // |
| // |modulate_blits_with_color|: Indicates whether to modulate source pixels |
| // in blit calls. |
| SB_EXPORT bool SbBlitterSetModulateBlitsWithColor( |
| SbBlitterContext context, |
| bool modulate_blits_with_color); |
| |
| // 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. |
| SB_EXPORT bool SbBlitterSetScissor(SbBlitterContext context, |
| SbBlitterRect rect); |
| |
| // 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. |
| // |
| // |context|: The context on which the draw call will operate. |
| // |rect|: The rectangle to be filled. |
| SB_EXPORT bool SbBlitterFillRect(SbBlitterContext context, SbBlitterRect rect); |
| |
| // 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. |
| // |
| // |src_rect|: The area to be block transferred (blitted). |
| SB_EXPORT bool SbBlitterBlitRectToRect(SbBlitterContext context, |
| SbBlitterSurface source_surface, |
| SbBlitterRect src_rect, |
| SbBlitterRect dst_rect); |
| |
| // 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. |
| SB_EXPORT bool SbBlitterBlitRectToRectTiled(SbBlitterContext context, |
| SbBlitterSurface source_surface, |
| SbBlitterRect src_rect, |
| SbBlitterRect dst_rect); |
| |
| // 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. |
| SB_EXPORT bool SbBlitterBlitRectsToRects(SbBlitterContext context, |
| SbBlitterSurface source_surface, |
| const SbBlitterRect* src_rects, |
| const SbBlitterRect* dst_rects, |
| int num_rects); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // SB_HAS(BLITTER) |
| |
| #endif // STARBOARD_BLITTER_H_ |