Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Starboard media header description #2958

Merged
merged 1 commit into from
May 8, 2024
Merged

Update Starboard media header description #2958

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions starboard/decode_target.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
// copies, and also avoiding pushing data between CPU and GPU memory
// unnecessarily.
//
// # SbDecodeTargetFormat
// * 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
Expand All @@ -33,7 +33,7 @@
// an error. Each decoder provides a way to check if a given
// SbDecodeTargetFormat is supported by that decoder.
//
// # SbDecodeTargetGraphicsContextProvider
// * SbDecodeTargetGraphicsContextProvider
//
// Some components may need to acquire SbDecodeTargets compatible with a certain
// rendering context, which may need to be created on a particular thread. The
Expand All @@ -42,7 +42,7 @@
// rendering context that will be used to render the SbDecodeTarget objects.
// For GLES renderers, it also provides functionality to enable the Starboard
// implementation to run arbitrary code on the application's renderer thread
// with the renderer's EGLContext held current. This may be useful if your
// with the renderer's EGLContext held current. This may be useful if your
// SbDecodeTarget creation code needs to execute GLES commands like, for
// example, glGenTextures().
//
Expand Down Expand Up @@ -104,10 +104,10 @@ typedef enum SbDecodeTargetFormat {
#endif // SB_API_VERSION >= 14

// A decoder target format consisting of a single plane with pixels laid out
// in the format UYVY. Since there are two Y values per sample, but only one
// in the format UYVY. Since there are two Y values per sample, but only one
// U value and only one V value, horizontally the Y resolution is twice the
// size of both the U and V resolutions. Vertically, they Y, U and V all
// have the same resolution. This is a YUV 422 format. When using this
// size of both the U and V resolutions. Vertically, the Y, U, and V planes
// all have the same resolution. This is a YUV 422 format. When using this
// format with GL platforms, it is expected that the underlying texture will
// be set to the GL_RGBA format, and the width of the texture will be equal to
// the number of UYVY tuples per row (e.g. the u/v width resolution).
Expand Down Expand Up @@ -157,19 +157,19 @@ typedef void (*SbDecodeTargetGlesContextRunner)(

// In general, the SbDecodeTargetGraphicsContextProvider structure provides
// information about the graphics context that will be used to render
// SbDecodeTargets. Some Starboard implementations may need to have references
// SbDecodeTargets. Some Starboard implementations may need to have references
// to some graphics objects when creating/destroying resources used by
// SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects
// SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects
// should be provided to all Starboard functions that might create
// SbDecodeTargets.
typedef struct SbDecodeTargetGraphicsContextProvider {
// A reference to the EGLDisplay object that hosts the EGLContext that will
// be used to render any produced SbDecodeTargets. Note that it has the
// type |void*| in order to avoid #including the EGL header files here.
// be used to render any produced SbDecodeTargets. Note that it has the
// type |void*| in order to avoid including the EGL header files here.
void* egl_display;
// The EGLContext object that will be used to render any produced
// SbDecodeTargets. Note that it has the
// type |void*| in order to avoid #including the EGL header files here.
// SbDecodeTargets. Note that it has the type |void*| in order to avoid
// including the EGL header files here.
void* egl_context;

// The |gles_context_runner| function pointer is passed in from the
Expand Down Expand Up @@ -220,9 +220,9 @@ typedef struct SbDecodeTargetInfoPlane {
int height;

// The following properties specify a rectangle indicating a region within
// the texture/surface that contains valid image data. The top-left corner
// is (0, 0) and increases to the right and to the bottom. The units
// specified by these parameters are number of pixels. The range for
// the texture/surface that contains valid image data. The top-left corner
// is (0, 0) and increases to the right and to the bottom. The units
// specified by these parameters are number of pixels. The range for
// left/right is [0, width], and for top/bottom it is [0, height].
SbDecodeTargetInfoContentRegion content_region;
} SbDecodeTargetInfoPlane;
Expand All @@ -234,16 +234,16 @@ typedef struct SbDecodeTargetInfo {
// expected in |planes|.
SbDecodeTargetFormat format;

// Specifies whether the decode target is opaque. 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
// Specifies whether the decode target is opaque. 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 value is set to true. By opaque, it is meant
// that all alpha values are guaranteed to be 255, if the decode target is of
// a format that has alpha values. If the decode target is of a format that
// does not have alpha values, then this value should be set to true.
// Applications may rely on this value in order to implement certain
// optimizations such as occlusion culling.
// such a way that this value is set to true. By opaque, it is meant that all
// alpha values are guaranteed to be 255, if the decode target is of a format
// that has alpha values. If the decode target is of a format that does not
// have alpha values, then this value should be set to true. Applications may
// rely on this value in order to implement certain optimizations such as
// occlusion culling.
bool is_opaque;

// The width of the image represented by this decode target.
Expand All @@ -252,7 +252,7 @@ typedef struct SbDecodeTargetInfo {
int height;

// The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY,
// kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this
// kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this
borongc marked this conversation as resolved.
Show resolved Hide resolved
// decode target.
SbDecodeTargetInfoPlane planes[3];
} SbDecodeTargetInfo;
Expand Down Expand Up @@ -299,20 +299,20 @@ static inline int SbDecodeTargetNumberOfPlanesForFormat(
// Returns ownership of |decode_target| to the Starboard implementation.
// This function will likely result in the destruction of the SbDecodeTarget and
// all its associated surfaces, though in some cases, platforms may simply
// adjust a reference count. This function must be called on a thread with
// the context
// adjust a reference count. This function must be called on a thread with
// the context.
SB_EXPORT void SbDecodeTargetRelease(SbDecodeTarget decode_target);

// Writes all information about |decode_target| into |out_info|.
// The |decode_target| must not be kSbDecodeTargetInvalid.
// The |out_info| pointer must not be NULL.
// Returns false if the provided |out_info| structure is not zero initialized.
// Writes all information about |decode_target| into |out_info|. The
// |decode_target| must not be kSbDecodeTargetInvalid. The |out_info| pointer
// must not be NULL. Returns false if the provided |out_info| structure is
// not zero initialized.
SB_EXPORT bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target,
SbDecodeTargetInfo* out_info);

// Inline convenience function to run an arbitrary
// SbDecodeTargetGlesContextRunnerTarget function through a
// SbDecodeTargetGraphicsContextProvider. This is intended to be called by
// SbDecodeTargetGraphicsContextProvider. This is intended to be called by
// Starboard implementations, if it is necessary.
static inline void SbDecodeTargetRunInGlesContext(
SbDecodeTargetGraphicsContextProvider* provider,
Expand Down
77 changes: 48 additions & 29 deletions starboard/drm.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,14 @@ typedef enum SbDrmStatus {
kSbDrmStatusNotSupportedError,
kSbDrmStatusInvalidStateError,
kSbDrmStatusQuotaExceededError,
// The following error can be used when the error status cannot be mapped to
// one of the above errors.
// The kSbDrmStatusUnknownError can be used when the error status cannot be
// mapped to one of the rest errors. New error codes (if needed) should be
// added before kSbDrmStatusUnknownError.
kSbDrmStatusUnknownError,
} SbDrmStatus;

// Status of a particular media key.
// https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus
// https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus
typedef enum SbDrmKeyStatus {
kSbDrmKeyStatusUsable,
kSbDrmKeyStatusExpired,
Expand Down Expand Up @@ -134,15 +135,16 @@ typedef struct SbDrmSystemPrivate* SbDrmSystem;
// |type| is the status of the session request.
//
// |error_message| may contain an optional error message when |status| isn't
// |kSbDrmStatusSuccess| to provide more details about the error. It may be
// |kSbDrmStatusSuccess| to provide more details about the error. It may be
// NULL if |status| is |kSbDrmStatusSuccess| or if no error message can be
// provided.
//
// |ticket| will be the same ticket that was passed to
borongc marked this conversation as resolved.
Show resolved Hide resolved
// SbDrmGenerateSessionUpdateRequest() or |kSbDrmTicketInvalid| if the update
// request was generated by the DRM system.
//
// |session_id| cannot be NULL when |ticket| is |kSbDrmTicketInvalid|, even when
// there was an error generating the request. This allows Cobalt to find and
// there was an error generating the request. This allows Cobalt to find and
// reject the correct Promise corresponding to the associated
// SbDrmGenerateSessionUpdateRequest().
typedef void (*SbDrmSessionUpdateRequestFunc)(SbDrmSystem drm_system,
Expand All @@ -167,7 +169,7 @@ typedef void (*SbDrmSessionUpdateRequestFunc)(SbDrmSystem drm_system,
// |status| is the status of the session request.
//
// |error_message| may contain an optional error message when |status| isn't
// |kSbDrmStatusSuccess| to provide more details about the error. It may be
// |kSbDrmStatusSuccess| to provide more details about the error. It may be
// NULL if |status| is |kSbDrmStatusSuccess| or if no error message can be
// provided.
// |succeeded| is whether the session was successfully updated or not.
Expand All @@ -180,8 +182,15 @@ typedef void (*SbDrmSessionUpdatedFunc)(SbDrmSystem drm_system,
int session_id_size);

// A callback for notifications that the status of one or more keys in a session
// has been changed. All keys of the session and their new status will be
// passed along. Any keys not in the list is considered as deleted.
// has been changed. A pointer to an array of all keys |key_ids| of the session
// and their new status will be passed along. Any keys not in the list are
// considered as deleted.
//
// |number_of_keys| is the number of keys.
//
// |key_ids| is a pointer to an array of keys.
//
// |key_statuses| is a pointer of a vector contains the status of each key.
typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
SbDrmSystem drm_system,
void* context,
Expand All @@ -191,7 +200,7 @@ typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
const SbDrmKeyId* key_ids,
const SbDrmKeyStatus* key_statuses);

// A callback for signalling that a session has been closed by the SbDrmSystem
// A callback for signalling that a session has been closed by the SbDrmSystem.
typedef void (*SbDrmSessionClosedFunc)(SbDrmSystem drm_system,
void* context,
const void* session_id,
Expand Down Expand Up @@ -234,29 +243,34 @@ static SB_C_FORCE_INLINE bool SbDrmTicketIsValid(int ticket) {
// SbDrmUpdateSession() for more details.
//
// |key_system|: The DRM key system to be created. The value should be in the
// form of "com.example.somesystem" as suggested by
// https://w3c.github.io/encrypted-media/#key-system. All letters in the value
// form of "com.example.somesystem". All letters in the value
// should be lowercase and will be matched exactly with known DRM key systems of
// the platform.
// the platform. Note the key system will be matched case sensitive. For more
// details, refer to https://w3c.github.io/encrypted-media/#dfn-key-system-s
//
// |context|: A value passed when any of this function's callback parameters are
// called.
//
// |update_request_callback|: A function that is called every time after
// SbDrmGenerateSessionUpdateRequest() is called.
//
// |session_updated_callback|: A function that is called every time after
// SbDrmUpdateSession() is called.
//
// |key_statuses_changed_callback|: A function that can be called to indicate
// that key statuses have changed.
//
// |server_certificate_updated_callback|: A function that is called to report
// whether the server certificate has been successfully updated. It is called
// once and only once. It is possible that the callback is called before the
// whether the server certificate has been successfully updated. It is called
// once and only once. It is possible that the callback is called before the
// function returns.
//
// |session_closed_callback|: A function that can be called to indicate that a
// session has closed.
// If |NULL| is passed for any of the callbacks (|update_request_callback|,
// |session_updated_callback|, |key_statuses_changed_callback|,
// |server_certificate_updated_callback|, or |session_closed_callback|), then
// |kSbDrmSystemInvalid| must be returned.

SB_EXPORT SbDrmSystem SbDrmCreateSystem(
const char* key_system,
void* context,
Expand Down Expand Up @@ -294,9 +308,11 @@ SB_EXPORT SbDrmSystem SbDrmCreateSystem(
// used.
//
// |type|: The case-sensitive type of the session update request payload. Must
// not be NULL.
// not be NULL.
//
// |initialization_data|: The data for which the session update
// request payload is created. Must not be NULL.
// request payload is created. Must not be NULL.
//
// |initialization_data_size|: The size of the session update request payload.
SB_EXPORT void SbDrmGenerateSessionUpdateRequest(
SbDrmSystem drm_system,
Expand Down Expand Up @@ -339,28 +355,31 @@ SB_EXPORT void SbDrmCloseSession(SbDrmSystem drm_system,
int session_id_size);

// Returns true if server certificate of |drm_system| can be updated via
// SbDrmUpdateServerCertificate(). The return value should remain the same
// SbDrmUpdateServerCertificate(). The return value should remain the same
// during the life time of |drm_system|.
//
// |drm_system|: The DRM system to check if its server certificate is updatable.
// Must not be |kSbDrmSystemInvalid|.
SB_EXPORT bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system);

// Update the server certificate of |drm_system|. The function can be called
// multiple times. It is possible that a call to it happens before the callback
// Update the server certificate of |drm_system|. The function can be called
// multiple times. It is possible that a call to it happens before the callback
// of a previous call is called.
// Note that this function should only be called after
// |SbDrmIsServerCertificateUpdatable| is called first and returned true.
//
// |drm_system|: The DRM system whose server certificate is being updated. Must
// not be |kSbDrmSystemInvalid|.
// not be |kSbDrmSystemInvalid|.
//
// |ticket|: The opaque ID that allows to distinguish callbacks from multiple
// concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
// |server_certificate_updated_callback| as-is. It is the responsibility of
// the caller to establish ticket uniqueness, issuing multiple requests with
// the same ticket may result in undefined behavior. The value
// |kSbDrmTicketInvalid| must not be used.
// concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
// |server_certificate_updated_callback| as-is. It is the responsibility of
// the caller to establish ticket uniqueness, issuing multiple requests with
// the same ticket may result in undefined behavior. The value
// |kSbDrmTicketInvalid| must not be used.
//
// |certificate|: Pointer to the server certificate data. Must not be NULL.
//
// |certificate_size|: Size of the server certificate data.
SB_EXPORT void SbDrmUpdateServerCertificate(SbDrmSystem drm_system,
int ticket,
Expand All @@ -377,7 +396,7 @@ SB_EXPORT void SbDrmUpdateServerCertificate(SbDrmSystem drm_system,
// using url safe base64 without padding and line wrapping. On systems using
// Widevine CE CDM with oemcrypto 16 or later, it should return the metrics
// retrieved via Cdm::getMetrics(), encoded using url safe base64 without
// padding and line wrapping. The returned pointer should remain valid and its
// padding and line wrapping. The returned pointer should remain valid and its
// content should remain unmodified until the next time this function is called
// on the associated |drm_system| or the |drm_system| is destroyed.
//
Expand All @@ -396,12 +415,12 @@ SB_EXPORT const void* SbDrmGetMetrics(SbDrmSystem drm_system, int* size);
// destroyed unless any associated SbPlayer or SbDecoder has first been
// destroyed.
//
// All callbacks are guaranteed to be finished when this function returns. As a
// All callbacks are guaranteed to be finished when this function returns. As a
// result, if this function is called from a callback that is passed to
// SbDrmCreateSystem(), a deadlock will occur.
//
// |drm_system|: The DRM system to be destroyed. Must not be
// |kSbDrmSystemInvalid|.
// |kSbDrmSystemInvalid|.
SB_EXPORT void SbDrmDestroySystem(SbDrmSystem drm_system);

#ifdef __cplusplus
Expand Down
Loading
Loading