Starboard Module Reference: decode_target.h

A target for decoding image and video data into. This corresponds roughly to an EGLImage, but that extension may not be fully supported on all GL platforms. SbDecodeTarget supports multi-plane targets. We need a mechanism for SbBlitter as well, and this is able to more-or-less unify the two.
An SbDecodeTarget can be passed into any function which decodes video or image data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily.

SbDecodeTargetFormat

SbDecodeTargets support several different formats that can be used to decode into and render from. Some formats may be easier to decode into, and others may be easier to render. Some may take less memory. Each decoder needs to support the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder.

SbDecodeTargetProvider

Some components may need to acquire SbDecodeTargets compatible with a certain rendering context, which may need to be created on a particular thread. The SbDecodeTargetProvider is a way for the primary rendering context to provide an interface that can create SbDecodeTargets on demand by other system.
The primary usage is likely to be the the SbPlayer implementation on some platforms.

SbDecodeTarget Example

Let's say there's an image decoder for .foo files:
bool SbImageDecodeFooSupportsFormat(SbDecodeTargetFormat format); SbDecodeTarget SbImageDecodeFoo(void* data, int data_size, SbDecodeTargetFormat format);
First, the client should enumerate which SbDecodeTargetFormats are supported by that decoder.
SbDecodeTargetFormat kPreferredFormats[] = { kSbDecodeTargetFormat3PlaneYUVI420, kSbDecodeTargetFormat1PlaneRGBA, kSbDecodeTargetFormat1PlaneBGRA, };
SbDecodeTargetFormat format = kSbDecodeTargetFormatInvalid; for (int i = 0; i < SB_ARRAY_SIZE_INT(kPreferredFormats); ++i) { if (SbImageDecodeFooSupportsFormat(kPreferredFormats[i])) { format = kPreferredFormats[i]; break; } }
Now that the client has a format, it can create a decode target that it will use to decode the .foo file into. Let's assume format is kSbDecodeTargetFormat1PlaneRGBA, that we are on an EGL/GLES2 platform. Also, we won't do any error checking, to keep things even simpler.
SbDecodeTarget target = SbImageDecodeFoo(encoded_foo_data, encoded_foo_data_size, format);
// If the decode works, you can get the texture out and render it. GLuint texture = SbDecodeTargetGetPlane(target, kSbDecodeTargetPlaneRGBA);

Enums

SbDecodeTargetFormat

The list of all possible decoder target formats. An SbDecodeTarget consists of one or more planes of data, each plane corresponding with a surface. For some formats, different planes will be different sizes for the same dimensions.
NOTE: For enumeration entries with an alpha component, the alpha will always be premultiplied unless otherwise explicitly specified.

Values

  • kSbDecodeTargetFormat1PlaneRGBA - A decoder target format consisting of a single RGBA plane, in that channelorder.
  • kSbDecodeTargetFormat1PlaneBGRA - A decoder target format consisting of a single BGRA plane, in that channelorder.
  • kSbDecodeTargetFormat2PlaneYUVNV12 - A decoder target format consisting of Y and interleaved UV planes, in thatplane and channel order.
  • kSbDecodeTargetFormat3PlaneYUVI420 - A decoder target format consisting of Y, U, and V planes, in that order.
  • kSbDecodeTargetFormatInvalid - An invalid decode target format.

SbDecodeTargetPlane

All the planes supported by SbDecodeTarget.

Values

  • kSbDecodeTargetPlaneRGBA - The RGBA plane for the RGBA format.
  • kSbDecodeTargetPlaneBGRA - The BGRA plane for the BGRA format.
  • kSbDecodeTargetPlaneY - The Y plane for multi-plane YUV formats.
  • kSbDecodeTargetPlaneUV - The UV plane for 2-plane YUV formats.
  • kSbDecodeTargetPlaneU - The U plane for 3-plane YUV formats.
  • kSbDecodeTargetPlaneV - The V plane for 3-plane YUV formats.

Structs

SbDecodeTargetPrivate

Private structure representing a target for image data decoding.

SbDecodeTargetProvider

An object that can acquire and release SbDecodeTarget instances.

Members

Members
SbDecodeTargetAcquireFunction
acquire
The function to acquire a new SbDecodeTarget from the provider.
SbDecodeTargetReleaseFunction
release
The function to release an acquired SbDecodeTarget back to the provider.

Functions

SbDecodeTarget

Description

Inline convenience function to acquire an SbDecodeTarget of type format, width, and height from provider.

Declaration

static SB_C_INLINE SbDecodeTarget
SbDecodeTargetAcquireFromProvider(SbDecodeTargetProvider* provider,
                                  SbDecodeTargetFormat format,
                                  int width,
                                  int height) {
  return provider->acquire(provider->context, format, width, height);
}

Parameters

Parameters
SbDecodeTargetAcquireFromProvider(SbDecodeTargetProvider*
provider
SbDecodeTargetFormat
format
int
width
int
height

SbDecodeTargetCreate

Description

Creates a new EGL/GLES2-compatible SbDecodeTarget from one or more planes owned by context, created from display. Must be called from a thread where context is current.

Declaration

SB_EXPORT SbDecodeTarget SbDecodeTargetCreate(EGLDisplay display,
                                              EGLContext context,
                                              SbDecodeTargetFormat format,
                                              GLuint* planes);

Parameters

Parameters
EGLDisplay
display
The EGLDisplay being targeted.
EGLContext
context
The EGLContext used for this operation, or EGL_NO_CONTEXT if a context is not required.
SbDecodeTargetFormat
format
The format of the decode target being created.
GLuint*
planes
An array of GLES Texture handles to be bundled into an SbDecodeTarget. Must not be NULL. Is expected to have the same number of entries as the number of planes for format, in the order and size expected by that format.

SbDecodeTargetDestroy

Description

Destroys the given SbDecodeTarget. Note that calling this function does NOT destroy the associated surfaces with it, in order to accommodate the case in which it is desirable for the lifetime of the surface to outlive the SbDecodeTarget that contains it. If the surfaces should be destroyed along with the SbDecodeTarget, then they should be extracted with SbDecodeTargetGetPlane and destroyed manually by the client.

Declaration and definitions

SB_EXPORT void SbDecodeTargetDestroy(SbDecodeTarget decode_target);

#include "starboard/decode_target.h"

void SbDecodeTargetDestroy(SbDecodeTarget /*decode_target*/) {}

Parameters

Parameters
SbDecodeTarget
decode_target

SbDecodeTargetGetFormat

Description

Gets the format that decode_target was created with.

Declaration and definitions

SB_EXPORT SbDecodeTargetFormat
SbDecodeTargetGetFormat(SbDecodeTarget decode_target);

#include "starboard/decode_target.h"

SbDecodeTargetFormat SbDecodeTargetGetFormat(SbDecodeTarget /*decode_target*/) {
  return kSbDecodeTargetFormatInvalid;
}

Parameters

Parameters
SbDecodeTarget
decode_target

SbDecodeTargetGetPlane

Description

Stub function for when graphics aren't enabled. There is no concept of a plane, and NULL is always returned.

Declaration

static SB_C_INLINE void* SbDecodeTargetGetPlane(SbDecodeTarget decode_target,
                                                SbDecodeTargetPlane plane) {
  SB_UNREFERENCED_PARAMETER(decode_target);
  SB_UNREFERENCED_PARAMETER(plane);
  return NULL;
}

Parameters

Parameters
SbDecodeTarget
decode_target
SbDecodeTargetPlane
plane

SbDecodeTargetIsFormatValid

Description

Returns whether a given format is valid.

Declaration

static SB_C_INLINE bool SbDecodeTargetIsFormatValid(
    SbDecodeTargetFormat format) {
  return format != kSbDecodeTargetFormatInvalid;
}

Parameters

Parameters
SbDecodeTargetFormat
format

SbDecodeTargetIsOpaque

Description

Gets whether decode_target is opaque or not. The underlying source of this value is expected to be properly maintained by the Starboard implementation. So, for example, if an opaque only image type were decoded into an SbDecodeTarget, then the implementation would configure things in such a way that this function would return true. By opaque, it is meant that all alpha values are guaranteed to be 255, if decode_target is of a format that has alpha values. If decode_target is of a format that does not have alpha values, then this function should return true.

Declaration and definitions

SB_EXPORT bool SbDecodeTargetIsOpaque(SbDecodeTarget decode_target);

#include "starboard/configuration.h"
#include "starboard/decode_target.h"

#if !(SB_VERSION(3) && SB_HAS(GRAPHICS))
#error "SbDecodeTargetIsOpaque requires SB_VERSION(3) and SB_HAS(GRAPHICS)."
#endif

bool SbDecodeTargetIsOpaque(SbDecodeTarget decode_target) {
  return false;
}

Parameters

Parameters
SbDecodeTarget
decode_target

SbDecodeTargetIsValid

Description

Returns whether the given file handle is valid.

Declaration

static SB_C_INLINE bool SbDecodeTargetIsValid(SbDecodeTarget handle) {
  return handle != kSbDecodeTargetInvalid;
}

Parameters

Parameters
SbDecodeTarget
handle

SbDecodeTargetReleaseToProvider

Description

Inline convenience function to release decode_target back to provider.

Declaration

static SB_C_INLINE void SbDecodeTargetReleaseToProvider(
    SbDecodeTargetProvider* provider,
    SbDecodeTarget decode_target) {
  provider->release(provider->context, decode_target);
}

Parameters

Parameters
SbDecodeTargetProvider*
provider
SbDecodeTarget
decode_target