Skip to content

Commit

Permalink
Update Starboard media header description (#2958)
Browse files Browse the repository at this point in the history 
This PR updates the description in drm.h, decode_target.h, media.h, and
player.h. This also fixes formatting issues in PR
#2984.

b/326450058
  • Loading branch information
@borongc
borongc committed May 8, 2024
1 parent f138279 commit 80a62f0
Show file tree
Hide file tree
Showing 4 changed files with 331 additions and 297 deletions.
64 changes: 32 additions & 32 deletions starboard/decode_target.h
View file
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
// 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
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
// 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

0 comments on commit 80a62f0

Please sign in to comment.