Skip to content

Commit

Permalink
Update starboard media header description
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.

b/326450058
  • Loading branch information
@borongc
borongc committed Apr 18, 2024
1 parent 69937fe commit fd2db8a
Show file tree
Hide file tree
Showing 4 changed files with 234 additions and 201 deletions.
10 changes: 5 additions & 5 deletions starboard/decode_target.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,11 +165,11 @@ typedef void (*SbDecodeTargetGlesContextRunner)(
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.
// 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.
// 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 @@ -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 @@ -300,7 +300,7 @@ static inline int SbDecodeTargetNumberOfPlanesForFormat(
// 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
// the context.
SB_EXPORT void SbDecodeTargetRelease(SbDecodeTarget decode_target);

// Writes all information about |decode_target| into |out_info|.
Expand All @@ -312,7 +312,7 @@ SB_EXPORT bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target,

// 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
52 changes: 34 additions & 18 deletions starboard/drm.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,13 @@ 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.
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 @@ -167,7 +167,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 +180,14 @@ 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. 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 of a vector contains 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 +197,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 @@ -235,28 +241,33 @@ static SB_C_FORCE_INLINE bool SbDrmTicketIsValid(int ticket) {
//
// |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
// https://w3c.github.io/encrypted-media/#key-system . All letters in the value
// should be lowercase and will be matched exactly with known DRM key systems of
// the platform.
//
// |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
// 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 +305,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 @@ -353,14 +366,17 @@ SB_EXPORT bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system);
// |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 Down Expand Up @@ -401,7 +417,7 @@ SB_EXPORT const void* SbDrmGetMetrics(SbDrmSystem drm_system, int* size);
// 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
118 changes: 62 additions & 56 deletions starboard/media.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,9 +311,7 @@ typedef enum SbMediaRangeId {

// HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR
// formats, together with the ColorSpace. HDR reproduces a greater dynamic range
// of luminosity than is possible with standard digital imaging. See the
// Consumer Electronics Association press release:
// https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx
// of luminosity than is possible with standard digital imaging.
typedef struct SbMediaColorMetadata {
// Number of decoded bits per channel. A value of 0 indicates that the
// BitsPerChannel is unspecified.
Expand Down Expand Up @@ -462,7 +460,7 @@ typedef struct SbMediaVideoSampleInfo {
// The video codec of this sample.
SbMediaVideoCodec codec;

// The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone. It
// The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone. It
// may point to an empty string if the mime is not available, and it can only
// be set to NULL when |codec| is kSbMediaVideoCodecNone.
const char* mime;
Expand Down Expand Up @@ -561,8 +559,7 @@ typedef struct SbMediaAudioStreamInfo {
// The size, in bytes, of the audio_specific_config.
uint16_t audio_specific_config_size;

// The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1:
// http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF
// The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1.
const void* audio_specific_config;
} SbMediaAudioStreamInfo;

Expand All @@ -583,12 +580,12 @@ typedef struct SbMediaAudioSampleInfo {
// The audio sample info consists of information found in the |WAVEFORMATEX|
// structure, as well as other information for the audio decoder, including the
// Audio-specific configuration field. The |WAVEFORMATEX| structure is
// specified at http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx.
// specified at http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx .
typedef struct SbMediaAudioSampleInfo {
// The audio codec of this sample.
SbMediaAudioCodec codec;

// The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone. It
// The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone. It
// may point to an empty string if the mime is not available, and it can only
// be set to NULL when |codec| is kSbMediaAudioCodecNone.
const char* mime;
Expand All @@ -614,8 +611,7 @@ typedef struct SbMediaAudioSampleInfo {
// The size, in bytes, of the audio_specific_config.
uint16_t audio_specific_config_size;

// The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1:
// http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF
// The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1.
const void* audio_specific_config;
} SbMediaAudioSampleInfo, SbMediaAudioStreamInfo;

Expand All @@ -630,47 +626,48 @@ typedef struct SbMediaAudioSampleInfo {
// |kSbMediaSupportNotSupported| if either is NULL.
//
// |mime|: The mime information of the media in the form of |video/webm| or
// |video/mp4; codecs="avc1.42001E"|. It may include arbitrary parameters like
// "codecs", "channels", etc. Note that the "codecs" parameter may contain
// more than one codec, delimited by comma.
// |video/mp4; codecs="avc1.42001E"|. It may include arbitrary parameters like
// "codecs", "channels", etc. Note that the "codecs" parameter may contain
// more than one codec, delimited by comma.
//
// |key_system|: A lowercase value in the form of "com.example.somesystem" as
// suggested by https://w3c.github.io/encrypted-media/#key-system that can be
// matched exactly with known DRM key systems of the platform. When
// |key_system| is an empty string, the return value is an indication for
// non-encrypted media.
// suggested by https://w3c.github.io/encrypted-media/#key-system that can be
// matched exactly with known DRM key systems of the platform. When
// |key_system| is an empty string, the return value is an indication for
// non-encrypted media.
//
// An implementation may choose to support |key_system| with extra attributes,
// separated by ';', like
// |com.example.somesystem; attribute_name1="value1"; attribute_name2=value1|.
// If |key_system| with attributes is not supported by an implementation, it
// should treat |key_system| as if it contains only the key system, and reject
// any input containing extra attributes, i.e. it can keep using its existing
// implementation.
// When an implementation supports |key_system| with attributes, it has to
// support all attributes defined by the Starboard version the implementation
// uses.
// An implementation should ignore any unknown attributes, and make a decision
// solely based on the key system and the known attributes. For example, if
// an implementation supports "com.widevine.alpha", it should also return
// `kSbMediaSupportTypeProbably` when |key_system| is
// |com.widevine.alpha; invalid_attribute="invalid_value"|.
// Currently the only attribute has to be supported is |encryptionscheme|. It
// reflects the value passed to `encryptionScheme` of
// MediaKeySystemMediaCapability, as defined in
// https://wicg.github.io/encrypted-media-encryption-scheme/, which can take
// value "cenc", "cbcs", or "cbcs-1-9".
// Empty string is not a valid value for |encryptionscheme| and the
// implementation should return `kSbMediaSupportTypeNotSupported` when
// |encryptionscheme| is set to "".
// The implementation should return `kSbMediaSupportTypeNotSupported` for
// unknown values of known attributes. For example, if an implementation
// supports "encryptionscheme" with value "cenc", "cbcs", or "cbcs-1-9", then
// it should return `kSbMediaSupportTypeProbably` when |key_system| is
// |com.widevine.alpha; encryptionscheme="cenc"|, and return
// `kSbMediaSupportTypeNotSupported` when |key_system| is
// |com.widevine.alpha; encryptionscheme="invalid"|.
// If an implementation supports key system with attributes on one key system,
// it has to support key system with attributes on all key systems supported.
// An implementation may choose to support |key_system| with extra attributes,
// separated by ';', like
// |com.example.somesystem; attribute_name1="value1"; attribute_name2=value1|.
// If |key_system| with attributes is not supported by an implementation, it
// should treat |key_system| as if it contains only the key system, and reject
// any input containing extra attributes, i.e. it can keep using its existing
// implementation.
// When an implementation supports |key_system| with attributes, it has to
// support all attributes defined by the Starboard version the implementation
// uses.
// An implementation should ignore any unknown attributes, and make a decision
// solely based on the key system and the known attributes. For example, if
// an implementation supports "com.widevine.alpha", it should also return
// `kSbMediaSupportTypeProbably` when |key_system| is
// |com.widevine.alpha; invalid_attribute="invalid_value"|.
// Currently the only attribute has to be supported is |encryptionscheme|. It
// reflects the value passed to `encryptionScheme` of
// MediaKeySystemMediaCapability, as defined in
// https://wicg.github.io/encrypted-media-encryption-scheme , which can take
// value "cenc", "cbcs", or "cbcs-1-9".
// Empty string is not a valid value for |encryptionscheme| and the
// implementation should return `kSbMediaSupportTypeNotSupported` when
// |encryptionscheme| is set to "".
// The implementation should return `kSbMediaSupportTypeNotSupported` for
// unknown values of known attributes. For example, if an implementation
// supports "encryptionscheme" with value "cenc", "cbcs", or "cbcs-1-9", then
// it should return `kSbMediaSupportTypeProbably` when |key_system| is
// |com.widevine.alpha; encryptionscheme="cenc"|, and return
// `kSbMediaSupportTypeNotSupported` when |key_system| is
// |com.widevine.alpha; encryptionscheme="invalid"|.
// If an implementation supports key system with attributes on one key system,
// it has to support key system with attributes on all key systems supported.
SB_EXPORT SbMediaSupportType
SbMediaCanPlayMimeAndKeySystem(const char* mime, const char* key_system);

Expand All @@ -688,7 +685,7 @@ SB_EXPORT int SbMediaGetAudioOutputCount();
// platform or if |output_index| does not exist on this device.
//
// |out_configuration|: The variable that holds the audio configuration
// information.
// information.
SB_EXPORT bool SbMediaGetAudioConfiguration(
int output_index,
SbMediaAudioConfiguration* out_configuration);
Expand Down Expand Up @@ -756,10 +753,13 @@ SB_EXPORT int SbMediaGetInitialBufferCapacity();
// app will be terminated as under other OOM situations.
//
// |codec|: the video codec associated with the buffer.
//
// |resolution_width|: the width of the video resolution.
//
// |resolution_height|: the height of the video resolution.
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
// HDR video.
//
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
// than non-HDR video.
SB_EXPORT int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec,
int resolution_width,
int resolution_height,
Expand Down Expand Up @@ -792,10 +792,13 @@ SB_EXPORT bool SbMediaIsBufferPoolAllocateOnDemand();
// 'SbMediaGetVideoBufferBudget(..., 1920, 1080, ...) but not less than 8 MB.
//
// |codec|: the video codec associated with the buffer.
//
// |resolution_width|: the width of the video resolution.
//
// |resolution_height|: the height of the video resolution.
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
// HDR video.
//
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
// than non-HDR video.
SB_EXPORT int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec,
int resolution_width,
int resolution_height,
Expand All @@ -822,10 +825,13 @@ SB_EXPORT bool SbMediaIsBufferUsingMemoryPool();
// value is too low.
//
// |codec|: the video codec associated with the buffer.
//
// |resolution_width|: the width of the video resolution.
//
// |resolution_height|: the height of the video resolution.
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
// HDR video.
//
// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
// than non-HDR video.
SB_EXPORT int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec,
int resolution_width,
int resolution_height,
Expand Down
Loading

0 comments on commit fd2db8a

Please sign in to comment.