From e9ad514662e862d8a487123937c798023fbe28e3 Mon Sep 17 00:00:00 2001 From: cobalt-github-releaser-bot Date: Thu, 13 Jun 2024 23:51:37 +0000 Subject: [PATCH] [create-pull-request] automated change --- .../site/docs/gen/cobalt/doc/voice_search.md | 18 +- .../build/doc/migrating_gyp_to_gn.md | 4 +- cobalt/site/docs/gen/starboard/doc/c99.md | 22 + .../docs/gen/starboard/doc/crash_handlers.md | 5 +- .../doc/evergreen/cobalt_evergreen_lite.md | 1 - .../evergreen/cobalt_evergreen_overview.md | 41 +- .../cobalt_evergreen_reference_port_raspi2.md | 5 +- .../doc/evergreen/symbolizing_minidumps.md | 35 +- .../doc/resources/starboard_16_posix.png | Bin 0 -> 70781 bytes .../gen/starboard/doc/starboard_16_posix.md | 342 ++++++++ cobalt/site/docs/gen/starboard/doc/style.md | 13 - .../site/docs/gen/starboard/doc/versioning.md | 165 +--- .../starboard/configuration-public.md | 9 + .../reference/starboard/gn-configuration.md | 4 +- .../starboard/modules/13/byte_swap.md | 75 -- .../modules/13/condition_variable.md | 140 ---- .../reference/starboard/modules/13/image.md | 77 -- .../reference/starboard/modules/13/memory.md | 345 -------- .../starboard/modules/13/memory_reporter.md | 106 --- .../reference/starboard/modules/13/mutex.md | 127 --- .../reference/starboard/modules/13/once.md | 57 -- .../reference/starboard/modules/13/player.md | 475 ----------- .../reference/starboard/modules/13/string.md | 174 ----- .../reference/starboard/modules/13/thread.md | 533 ------------- .../reference/starboard/modules/13/time.md | 152 ---- .../starboard/modules/13/ui_navigation.md | 322 -------- .../reference/starboard/modules/13/user.md | 133 ---- .../starboard/modules/14/accessibility.md | 1 + .../reference/starboard/modules/14/atomic.md | 1 + .../starboard/modules/14/audio_sink.md | 1 + .../starboard/modules/14/byte_swap.md | 1 + .../modules/14/condition_variable.md | 11 +- .../starboard/modules/14/configuration.md | 27 +- .../starboard/modules/14/cpu_features.md | 3 +- .../starboard/modules/14/decode_target.md | 69 +- .../starboard/modules/14/directory.md | 1 + .../reference/starboard/modules/14/drm.md | 95 ++- .../reference/starboard/modules/14/egl.md | 1 + .../reference/starboard/modules/14/event.md | 5 +- .../reference/starboard/modules/14/file.md | 13 +- .../reference/starboard/modules/14/gles.md | 1 + .../reference/starboard/modules/14/image.md | 2 + .../reference/starboard/modules/14/input.md | 1 + .../reference/starboard/modules/14/key.md | 1 + .../reference/starboard/modules/14/log.md | 1 + .../reference/starboard/modules/14/media.md | 118 +-- .../reference/starboard/modules/14/memory.md | 6 +- .../starboard/modules/14/memory_reporter.md | 1 + .../starboard/modules/14/microphone.md | 1 + .../reference/starboard/modules/14/mutex.md | 3 +- .../reference/starboard/modules/14/once.md | 3 +- .../reference/starboard/modules/14/player.md | 263 ++++++- .../reference/starboard/modules/14/socket.md | 11 +- .../starboard/modules/14/socket_waiter.md | 11 +- .../starboard/modules/14/speech_synthesis.md | 1 + .../reference/starboard/modules/14/storage.md | 1 + .../reference/starboard/modules/14/string.md | 16 +- .../reference/starboard/modules/14/system.md | 1 + .../reference/starboard/modules/14/thread.md | 3 +- .../reference/starboard/modules/14/time.md | 1 + .../starboard/modules/14/time_zone.md | 13 +- .../starboard/modules/14/ui_navigation.md | 6 +- .../reference/starboard/modules/14/user.md | 1 + .../reference/starboard/modules/14/window.md | 1 + .../starboard/modules/15/accessibility.md | 1 + .../reference/starboard/modules/15/atomic.md | 1 + .../starboard/modules/15/audio_sink.md | 1 + .../starboard/modules/15/byte_swap.md | 1 + .../modules/15/condition_variable.md | 11 +- .../starboard/modules/15/configuration.md | 27 +- .../starboard/modules/15/cpu_features.md | 3 +- .../starboard/modules/15/decode_target.md | 69 +- .../starboard/modules/15/directory.md | 1 + .../reference/starboard/modules/15/drm.md | 95 ++- .../reference/starboard/modules/15/egl.md | 1 + .../reference/starboard/modules/15/event.md | 5 +- .../reference/starboard/modules/15/file.md | 13 +- .../reference/starboard/modules/15/gles.md | 1 + .../reference/starboard/modules/15/image.md | 2 + .../reference/starboard/modules/15/input.md | 1 + .../reference/starboard/modules/15/key.md | 1 + .../reference/starboard/modules/15/log.md | 1 + .../reference/starboard/modules/15/media.md | 106 +-- .../reference/starboard/modules/15/memory.md | 6 +- .../starboard/modules/15/memory_reporter.md | 106 --- .../starboard/modules/15/microphone.md | 1 + .../reference/starboard/modules/15/mutex.md | 3 +- .../reference/starboard/modules/15/once.md | 3 +- .../reference/starboard/modules/15/player.md | 335 ++++++-- .../reference/starboard/modules/15/socket.md | 11 +- .../starboard/modules/15/socket_waiter.md | 11 +- .../starboard/modules/15/speech_synthesis.md | 1 + .../reference/starboard/modules/15/storage.md | 1 + .../reference/starboard/modules/15/string.md | 16 +- .../reference/starboard/modules/15/system.md | 1 + .../reference/starboard/modules/15/thread.md | 3 +- .../reference/starboard/modules/15/time.md | 1 + .../starboard/modules/15/time_zone.md | 13 +- .../starboard/modules/15/ui_navigation.md | 6 +- .../reference/starboard/modules/15/user.md | 1 + .../reference/starboard/modules/15/window.md | 1 + .../modules/{13 => 16}/accessibility.md | 1 + .../starboard/modules/{13 => 16}/atomic.md | 1 + .../modules/{13 => 16}/audio_sink.md | 1 + .../modules/{13 => 16}/configuration.md | 27 +- .../{13 => 16}/configuration_constants.md | 21 +- .../modules/{13 => 16}/cpu_features.md | 3 +- .../modules/{13 => 16}/decode_target.md | 74 +- .../starboard/modules/{13 => 16}/directory.md | 27 +- .../starboard/modules/{13 => 16}/drm.md | 95 ++- .../starboard/modules/{13 => 16}/egl.md | 1 + .../starboard/modules/{13 => 16}/event.md | 31 +- .../starboard/modules/{13 => 16}/export.md | 0 .../starboard/modules/{13 => 16}/file.md | 25 +- .../starboard/modules/{13 => 16}/gles.md | 1 + .../starboard/modules/{13 => 16}/input.md | 1 + .../starboard/modules/{13 => 16}/key.md | 2 + .../starboard/modules/{13 => 16}/log.md | 1 + .../starboard/modules/{13 => 16}/media.md | 227 +++--- .../reference/starboard/modules/16/memory.md | 47 ++ .../modules/{13 => 16}/microphone.md | 1 + .../reference/starboard/modules/16/player.md | 738 ++++++++++++++++++ .../starboard/modules/{13 => 16}/socket.md | 11 +- .../modules/{13 => 16}/socket_waiter.md | 11 +- .../modules/{13 => 16}/speech_synthesis.md | 1 + .../starboard/modules/{13 => 16}/storage.md | 38 +- .../starboard/modules/{13 => 16}/system.md | 87 +-- .../reference/starboard/modules/16/thread.md | 250 ++++++ .../starboard/modules/{13 => 16}/time_zone.md | 13 +- .../starboard/modules/{13 => 16}/types.md | 0 .../starboard/modules/{13 => 16}/window.md | 146 ---- .../starboard/modules/accessibility.md | 1 + .../reference/starboard/modules/atomic.md | 1 + .../reference/starboard/modules/audio_sink.md | 1 + .../reference/starboard/modules/byte_swap.md | 75 -- .../starboard/modules/condition_variable.md | 140 ---- .../starboard/modules/configuration.md | 18 +- .../modules/configuration_constants.md | 13 +- .../starboard/modules/cpu_features.md | 3 +- .../starboard/modules/decode_target.md | 68 +- .../reference/starboard/modules/directory.md | 27 +- .../docs/reference/starboard/modules/drm.md | 95 ++- .../docs/reference/starboard/modules/egl.md | 1 + .../docs/reference/starboard/modules/event.md | 8 +- .../docs/reference/starboard/modules/file.md | 25 +- .../docs/reference/starboard/modules/gles.md | 1 + .../docs/reference/starboard/modules/image.md | 77 -- .../docs/reference/starboard/modules/input.md | 1 + .../docs/reference/starboard/modules/key.md | 1 + .../docs/reference/starboard/modules/log.md | 1 + .../docs/reference/starboard/modules/media.md | 130 ++- .../reference/starboard/modules/memory.md | 291 +------ .../starboard/modules/memory_reporter.md | 106 --- .../reference/starboard/modules/microphone.md | 1 + .../docs/reference/starboard/modules/mutex.md | 127 --- .../docs/reference/starboard/modules/once.md | 57 -- .../reference/starboard/modules/player.md | 335 ++++++-- .../reference/starboard/modules/socket.md | 11 +- .../starboard/modules/socket_waiter.md | 11 +- .../starboard/modules/speech_synthesis.md | 1 + .../reference/starboard/modules/storage.md | 38 +- .../reference/starboard/modules/string.md | 174 ----- .../reference/starboard/modules/system.md | 1 + .../reference/starboard/modules/thread.md | 297 +------ .../docs/reference/starboard/modules/time.md | 152 ---- .../reference/starboard/modules/time_zone.md | 13 +- .../starboard/modules/ui_navigation.md | 322 -------- .../docs/reference/starboard/modules/user.md | 133 ---- .../reference/starboard/modules/window.md | 18 +- 169 files changed, 3241 insertions(+), 6353 deletions(-) create mode 100644 cobalt/site/docs/gen/starboard/doc/resources/starboard_16_posix.png create mode 100644 cobalt/site/docs/gen/starboard/doc/starboard_16_posix.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/byte_swap.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/condition_variable.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/image.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/memory.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/mutex.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/once.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/player.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/string.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/thread.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/time.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/13/user.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/accessibility.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/atomic.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/audio_sink.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/configuration.md (86%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/configuration_constants.md (93%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/cpu_features.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/decode_target.md (84%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/directory.md (80%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/drm.md (78%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/egl.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/event.md (95%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/export.md (100%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/file.md (96%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/gles.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/input.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/key.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/log.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/media.md (75%) create mode 100644 cobalt/site/docs/reference/starboard/modules/16/memory.md rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/microphone.md (99%) create mode 100644 cobalt/site/docs/reference/starboard/modules/16/player.md rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/socket.md (98%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/socket_waiter.md (95%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/speech_synthesis.md (99%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/storage.md (73%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/system.md (93%) create mode 100644 cobalt/site/docs/reference/starboard/modules/16/thread.md rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/time_zone.md (54%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/types.md (100%) rename cobalt/site/docs/reference/starboard/modules/{13 => 16}/window.md (52%) delete mode 100644 cobalt/site/docs/reference/starboard/modules/byte_swap.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/condition_variable.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/image.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/memory_reporter.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/mutex.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/once.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/string.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/time.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/ui_navigation.md delete mode 100644 cobalt/site/docs/reference/starboard/modules/user.md diff --git a/cobalt/site/docs/gen/cobalt/doc/voice_search.md b/cobalt/site/docs/gen/cobalt/doc/voice_search.md index c8bfcc43ea7e7..e0eabb7eb4281 100644 --- a/cobalt/site/docs/gen/cobalt/doc/voice_search.md +++ b/cobalt/site/docs/gen/cobalt/doc/voice_search.md @@ -26,15 +26,15 @@ on the SbMicrophone API as detailed above. In `starboard/linux/shared/soft_mic_platform_service.cc` there is an example stub implementation of the SoftMicPlatformService. Platforms can optionally -implement this [CobaltPlatformService](https://cobalt.dev/gen/cobalt/doc/\ -platform_services.html) to specify if they support the `soft mic` and/or `hard mic` -for voice search. The `soft mic` refers to the software activation of the microphone -for voice search through the UI microphone button on the Youtube Web Application -search page. The `hard mic` refers to hardware button activation of the microphone -for voice search. Platforms can also specify the optional `micGesture`. This -specifies the type of UI prompt the YouTube Web Application should display to guide -the user to start voice search. The options include an empty or `null` value for no -prompt, `"TAP"` for tap the `soft mic` and/or `hard mic` to start voice search, or +implement this [CobaltPlatformService](platform_services.md) to specify if they +support the `soft mic` and/or `hard mic` for voice search. The `soft mic` refers +to the software activation of the microphone for voice search through the UI +microphone button on the Youtube Web Application search page. The `hard mic` +refers to hardware button activation of the microphone for voice search. +Platforms can also specify the optional `micGesture`. This specifies the type of +UI prompt the YouTube Web Application should display to guide the user to start +voice search. The options include an empty or `null` value for no prompt, +`"TAP"` for tap the `soft mic` and/or `hard mic` to start voice search, or `"HOLD"` for hold the `soft mic` and/or the `hard mic` to start voice search. The Web Application messages to the platform will be singular strings, encoded with diff --git a/cobalt/site/docs/gen/starboard/build/doc/migrating_gyp_to_gn.md b/cobalt/site/docs/gen/starboard/build/doc/migrating_gyp_to_gn.md index c0758069251ed..c0e46b5bdb05f 100644 --- a/cobalt/site/docs/gen/starboard/build/doc/migrating_gyp_to_gn.md +++ b/cobalt/site/docs/gen/starboard/build/doc/migrating_gyp_to_gn.md @@ -266,8 +266,8 @@ This [document](./gn_migrate_stub_to_platform.md) outlines a step by step process for converting the stub platform's GN files to GN files that will be able to be built for your platform. -[cobalt_porting_guide]: https://cobalt.dev/starboard/porting.html -[dev_setup_linux]: https://cobalt.dev/development/setup-linux.html +[cobalt_porting_guide]: https://developers.google.com/youtube/cobalt/docs/starboard/porting +[dev_setup_linux]: https://developers.google.com/youtube/cobalt/docs/development/setup-linux [gn_check_tool]: https://cobalt.googlesource.com/third_party/gn/+/refs/heads/main/docs/reference.md#cmd_check [gn_doc_home]: https://cobalt.googlesource.com/third_party/gn/+/refs/heads/main/docs [gn_format_tool]: https://cobalt.googlesource.com/third_party/gn/+/refs/heads/main/docs/reference.md#cmd_format diff --git a/cobalt/site/docs/gen/starboard/doc/c99.md b/cobalt/site/docs/gen/starboard/doc/c99.md index 5fb5f90d6b1ee..0378393248e8f 100644 --- a/cobalt/site/docs/gen/starboard/doc/c99.md +++ b/cobalt/site/docs/gen/starboard/doc/c99.md @@ -36,30 +36,38 @@ deprecated and eventually removed. ### * acos * acosf +* acosh * asin * asinf +* asinh * atan * atan2 * atan2f * atanf +* atanh * cbrt * cbrtf * ceil * ceilf * cos * cosf +* cosh * div * erf * erff * exp * expf +* exp2 * exp2f * fabs +* fabsf * floor * floorf +* fmaf * fmod * fmodf * frexp +* ilogbf * isfinite * isnan * labs @@ -80,17 +88,23 @@ deprecated and eventually removed. * nextafterf * pow * powf +* remainder * round * roundf * scalbn * sin * sinf +* sinh * sqrt * sqrtf * tan * tanf +* tanh * trunc * truncf +### +* sscanf +* vsscanf ### * abs * atoi @@ -134,3 +148,11 @@ deprecated and eventually removed. * wmemmove * wmemset * wcsncmp +* snprintf +* sprintf +* vfwprintf +* vsnprintf +* vswprintf +* ferror +* fputwc +* fwide diff --git a/cobalt/site/docs/gen/starboard/doc/crash_handlers.md b/cobalt/site/docs/gen/starboard/doc/crash_handlers.md index d7dac077d2f53..b23b29471dd6f 100644 --- a/cobalt/site/docs/gen/starboard/doc/crash_handlers.md +++ b/cobalt/site/docs/gen/starboard/doc/crash_handlers.md @@ -35,7 +35,7 @@ const void* SbSystemGetExtension(const char* name) { } ``` -3. Calling the `third_party::crashpad::wrapper::InstallCrashpadHandler(bool start_at_crash)` hook +3. Calling the `third_party::crashpad::wrapper::InstallCrashpadHandler()` hook directly after installing system crash handlers. On linux, for example, this could look like: @@ -47,7 +47,8 @@ int main(int argc, char** argv) { starboard::shared::signal::InstallCrashSignalHandlers(); starboard::shared::signal::InstallSuspendSignalHandlers(); - third_party::crashpad::wrapper::InstallCrashpadHandler(true); + std::string ca_certificates_path = starboard::common::GetCACertificatesPath(); + third_party::crashpad::wrapper::InstallCrashpadHandler(ca_certificates_path); int result = application.Run(argc, argv); ... diff --git a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_lite.md b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_lite.md index 55b54e2ea46c1..6072f212bfcbb 100644 --- a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_lite.md +++ b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_lite.md @@ -100,7 +100,6 @@ Cobalt Evergreen currently supports the following Target Architectures: -* `x86_32` * `x86_64` * `armv7 32` * `armv8 64` diff --git a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md index 7b8a8de9cb333..160f8fa2dab0b 100644 --- a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md +++ b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md @@ -147,9 +147,9 @@ Evergreen: for more details. * `kSbMemoryMapProtectExec` * Ensures mapped memory can be executed -* `#define SB_CAN_MAP_EXECUTABLE_MEMORY 1` +* Set `kSbCanMapExecutableMemory` to `true` * Specifies that the platform can map executable memory - * Defined in `configuration_public.h` + * Defined in `configuration_constants.h` Only if necessary, create a customized SABI configuration for your architecture. Note, we do not anticipate that you will need to make a new configuration for @@ -306,8 +306,8 @@ instructions available [here](cobalt_evergreen_reference_port_raspi2.md). 1. Build the `crashpad_database_util` target and deploy it onto the device. ``` -$ cobalt/build/gn.py -p -c qa -$ ninja -C out/_qa crashpad_database_util +$ gn gen out/_qa --args='target_platform="" build_type="qa"' +$ ninja -C out/_qa native_target/crashpad_database_util ``` 2. Remove the existing state for crashpad as it throttles uploads to 1 per hour: ``` @@ -489,7 +489,6 @@ Image required for all slot configurations: │ └── cobalt <--(SLOT_0) │ ├── content <--(relative path defined in kSystemImageContentPath) │ │ ├── fonts <--(`empty` configuration) -│ │ ├── (icu) <--(only present when it needs to be updated by Cobalt Update) │ │ ├── licenses │ │ ├── ssl │ ├── lib @@ -510,7 +509,6 @@ updates in an example 3-slot configuration: ├── installation_2 <--(SLOT_2 - contains new Cobalt version) │ ├── content │ │ ├── fonts <--(`empty` configuration) - │ │ ├── (icu) <--(only present when it needs to be updated by Cobalt Update) │ │ ├── licenses │ │ ├── ssl │ ├── lib @@ -518,7 +516,6 @@ updates in an example 3-slot configuration: │ ├── manifest.fingerprint │ └── manifest.json <-- (Evergreen version information of libcobalt.so under SLOT_2) ├── installation_store_.pb - └── icu (default location shared by installation slots, to be explained below) ``` Note that after the Cobalt binary is loaded by the loader_app, `kSbSystemPathContentDirectory` points to the content directory of the running binary, as stated in Starboard Module Reference of system.h. @@ -562,24 +559,6 @@ On Raspberry Pi the Cobalt fonts are configured the following way: /fonts ``` -### ICU Tables -The ICU table should be deployed under the `kSbSystemPathStorageDirectory`. This -way all Cobalt Evergreen installations would be able to share the same tables. -The current storage size for the ICU tables is 7MB. - -On Raspberry Pi this is: - -``` -/home/pi/.cobalt_storage/icu -``` -The Cobalt Evergreen package will not carry ICU tables by default but may add -them in the future if needed. When the package has ICU tables they would be -stored under the content location for the installation: - -``` -/content/icu -``` - ### Handling Pending Updates Pending updates will be picked up on the next application start, which means that on platforms that support suspending the platform should check @@ -609,9 +588,6 @@ behavior can be easily configured on a per-app basis with simple command-line fl The configurable options for Cobalt Updater configuration are: * `--evergreen_lite` *Use the System Image version of Cobalt under Slot_0 and turn off the updater for the specified application.* -* `--disable_updater_module` *Stay on the current version of Cobalt that might be the - system image or an installed update, and turn off the updater for the - specified application.* Each app’s Cobalt Updater will perform an independent, regular check for new Cobalt Evergreen updates. Note that all apps will share the same set of slots, @@ -640,7 +616,7 @@ existing slot. In this case, `APP_1` and `APP_2` are now using the same Cobalt binaries in SLOT_2. If `APP_3` has not been launched, not run through a regular Cobalt Updater -check, or launched with the `--evergreen_lite`/`--disable_updater_module` flag, +check, or launched with the `--evergreen_lite` flag, it stays with its current configuration. #### AFTER COBALT UPDATE @@ -667,15 +643,14 @@ loader_app --url="" loader_app --url="" -# Only APP_1 gets Evergreen Updates, APP_2 disables the updater and uses an alternate splash screen, APP_3 uses +# APP_1 gets Evergreen Updates, APP_2 uses an alternate splash screen, APP_3 uses # the system image and disables the updater [APP_1] (Cobalt Updater ENABLED) -[APP_2] (Cobalt Updater DISABLED) +[APP_2] (Cobalt Updater ENABLED) [APP_3] (System Image loaded, Cobalt Updater DISABLED) loader_app --url="" -loader_app --url="" --disable_updater_module \ ---fallback_splash_screen_url="//app_2_splash_screen.html" +loader_app --url="" --fallback_splash_screen_url="//app_2_splash_screen.html" loader_app --url="" --evergreen_lite diff --git a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_reference_port_raspi2.md b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_reference_port_raspi2.md index 2bfc1e3b34dd9..b9c3d45260a4a 100644 --- a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_reference_port_raspi2.md +++ b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_reference_port_raspi2.md @@ -5,9 +5,8 @@ Book: /youtube/cobalt/_book.yaml ## Requirements -* Raspberry Pi 2 (image configured per - [instructions](https://cobalt.dev/development/setup-raspi.html) on - cobalt.dev) +* Raspberry Pi environment setup per + [instructions](https://developers.google.com/youtube/cobalt/docs/development/setup-raspi). ## Build instructions diff --git a/cobalt/site/docs/gen/starboard/doc/evergreen/symbolizing_minidumps.md b/cobalt/site/docs/gen/starboard/doc/evergreen/symbolizing_minidumps.md index 08e8d39d0712b..dbab3d9e5dc8d 100644 --- a/cobalt/site/docs/gen/starboard/doc/evergreen/symbolizing_minidumps.md +++ b/cobalt/site/docs/gen/starboard/doc/evergreen/symbolizing_minidumps.md @@ -11,7 +11,33 @@ debugging, as these minidumps have the information for the dynamic `libcobalt.so` module correctly mapped, which a out-of-the-box dumper could not manage. -## Obtaining the Tools to Symbolize Minidumps +## Symbolizing with the Provided Docker Container (Recommended) + +We provide a docker container at `docker/crashpad_symbolize/Dockerfile` with a +corresponding docker-compose service, `crashpad-symbolize`, with which you can +symbolize your minidumps. + +Build and run the container with: + +``` +MINIDUMP_PATH=/path/to/minidump_file.dmp docker-compose up --build crashpad-symbolize +``` + +Where `MINIDUMP_PATH` is the path to your minidump file. The service will also +pick up environment values for `GITHUB_TAG`, `ARCHITECTURE`, `SB_API_VERSION`, +and `CONFIG`, so ensure these are correct. + +* `GITHUB_TAG`: A Cobalt version with an associated release, i.e. 25.lts.10 +* `ARCHITECTURE`: One of `x64`, `x86`, `arm64`, `arm-hardfp`, or `arm-softfp` +* `SB_API_VERSION`: The Starboard version, i.e. `16` +* `CONFIG`: One of `release` or `qa` + +## Symbolizing Locally + +If you wish, you can download all the necessary tools to locally symbolize +minidumps. This is more work than doing it with the docker container. + +### Obtaining the Tools to Symbolize Minidumps Tools for symbolizing these dumps are available through [Breakpad](https://chromium.googlesource.com/breakpad/breakpad/). Breakpad is @@ -19,8 +45,7 @@ an open source crash reporting library that we use to obtain symbol files (`.sym`) from unstripped binaries, and to process the symbol files with the minidumps to produce human-readable stacktraces. - -### Building Breakpad +#### Building Breakpad [Breakpad](https://chromium.googlesource.com/breakpad/breakpad/) provides instructions for building these tools yourself. The @@ -54,7 +79,7 @@ building on Linux it will also build the `dump_syms` tool depot_tools from your `$PATH` environment variable, as it can conflict with Cobalt's depot_tools. -## Symbolizing Minidumps +### Symbolizing Minidumps Now that you have all the tools you need, we can symbolize the dumps. To be able to symbolize Cobalt using Evergreen, you need to be get the unstripped @@ -100,7 +125,7 @@ $ /path/to/minidump_stackwalk /path/to/your/minidump.dmp symbols/ `minidump_stackwalk` produces verbose output on stderr, and the stacktrace on stdout, so you may want to redirect stderr. -### Addendum: Adding Other Symbols +#### Addendum: Adding Other Symbols We can use the process above to add symbols for any library or executable you use, not just `libcobalt.so`. To do this, all you have to do is run the diff --git a/cobalt/site/docs/gen/starboard/doc/resources/starboard_16_posix.png b/cobalt/site/docs/gen/starboard/doc/resources/starboard_16_posix.png new file mode 100644 index 0000000000000000000000000000000000000000..0d4034b1ab4574bc6aabbbf3f46de3b0494697e5 GIT binary patch literal 70781 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 and all the Starboard and POSIX symbols are +registered there. The implementation resides in +[starboard/elf_loader/exported_symbols.cc](../elf_loader/exported_symbols.cc). +For POSIX APIs a wrapper function is used whenever a translation +from `musl` types to platform POSIX types is needed e.g. + +``` +map_["clock_gettime"] = reinterpret_cast(&__abi_wrap_clock_gettime); +``` +The symbol may be registered directly without a wrapper if there is no need +for any translation or ajustements of the API e.g. +``` +REGISTER_SYMBOL(malloc); +``` + +### Verification +A test suite [starboard/nplb/posix_compliance](../nplb/posix_compliance) is added to `nplb` +to verify the POSIX APIs specification and to enforce uniformity across all platforms. + +The `elf_loader_sandbox` binary can be used to run tests in Evergreen mode. + +The `elf_loader_sandbox` is run using two command line switches: +`--evergreen_library` and `--evergreen_content`. These switches are the path to +the shared library to be run and the path to that shared library's content. +These paths should be *relative to the content of the elf_loader_sandbox*. + +For example, if we wanted to run the `nplb` set of tests and had the following +directory tree, + +``` +.../elf_loader_sandbox +.../content/app/nplb/lib/libnplb.so +.../content/app/nplb/content +``` + +we would use the following command to run `nplb`: + +``` +.../elf_loader_sandbox --evergreen_library=app/nplb/lib/libnplb.so + --evergreen_content=app/nplb/content +``` + +To build the `nplb` tests for Evergreen use the following commands. +The first of which builds the test using the Evergreen toolchain and +the second builds `elf_loader_sandbox` using the partner's toolchain: + +``` + +ninja -C out/evergreen-arm-softfp_devel/ nplb_install +ninja -C out/${PLATFORM}_devel/ elf_loader_sandbox_install + +``` + + +### Backwards compatibility with Starboard 14 and Starboard 15 +For older Starboard Versions e.g. 14 and 15 an emulation layer was provided through +the `third_party/musl` library. This should be completely transparent to +partner's integrations. diff --git a/cobalt/site/docs/gen/starboard/doc/style.md b/cobalt/site/docs/gen/starboard/doc/style.md index 84c55f19efb39..22998a5babe02 100644 --- a/cobalt/site/docs/gen/starboard/doc/style.md +++ b/cobalt/site/docs/gen/starboard/doc/style.md @@ -123,9 +123,6 @@ the guidelines follow thusly as follows. casting the handle back and forth to the pointer type. * If a word in the name of a type is redundant with the module name, it is omitted. - * A monotonic time type in the Time module is `SbTimeMonotonic`, not - ~~`SbMonotonicTime`, `SbTimeMonotonicTime`, or - `SbTimeMonotonicSbTime`~~. ### Functions @@ -191,10 +188,8 @@ namespace at the starboard repository root. * After the `k`, all constants have `Sb`, the Starboard namespace. * `kSb` * After `kSb`, all constants then have the module name. - * `kSbTime` * `kSbFile` * After `kSb` comes the rest of the name of the constant. - * `kSbTimeMillisecond` * `kSbFileInvalid` * Enum entries are prefixed with the full name of the enum. * The enum `SbSystemDeviceType` contains entries like @@ -238,14 +233,6 @@ namespace at the starboard repository root. ### Implementations - * Each API implementation should attempt to minimize other platform - assumptions, and should therefore use Starboard APIs to accomplish - platform-specific work unless directly related to the platform functionality - being implemented. - * For example, `SbFile` can use POSIX file I/O, because that what it is - abstracting, but it should use `SbMemoryAllocate` for any memory - allocations, because it might be used with a variety of `SbMemory` - implementations. * Whenever possible, each shared function implementation should be implemented in an individual file so as to maximize the chances of reuse between implementations. diff --git a/cobalt/site/docs/gen/starboard/doc/versioning.md b/cobalt/site/docs/gen/starboard/doc/versioning.md index b33e73bcbc105..02afb2f75d99c 100644 --- a/cobalt/site/docs/gen/starboard/doc/versioning.md +++ b/cobalt/site/docs/gen/starboard/doc/versioning.md @@ -59,8 +59,6 @@ error at compilation time. Generally Starboard applications will not support all versions of the Starboard API indefinitely. Starboard application owners may increment the minimum required Starboard version at their discretion. -TBD: Timelines and communication around when an upcoming Cobalt release will -require porters to implement a newer version of Starboard. ## Using new Starboard APIs from Starboard Applications @@ -72,170 +70,11 @@ new functionality in Starboard applications if this evaluates to false. ## Adding and using new Starboard APIs -### The "Experimental" Starboard Version - -At any given time, exactly one version of Starboard will be denoted as the -"experimental" version, as defined by the `SB_EXPERIMENTAL_API_VERSION` macro in -`starboard/configuration.h`. It is generally not recommended to declare support -for this version. Any Starboard APIs defined in the experimental version are -subject to change and API requirements could be added, removed, or changed at -any time. - -### The "Release Candidate" Starboard Version - -At any given time, zero or more versions of Starboard will be denoted as the -"release candidate" version, as defined by the -`SB_RELEASE_CANDIDATE_API_VERSION` macro in `starboard/configuration.h`. The -"release candidate" version is a set of API changes that have been considered -and tested together. It is reasonable to port against this version, it has gone -through some stabilization and may become frozen as it currently is. But, be -aware that it is possible that minor incompatible changes may be made to this -version if an unexpected situation arises. `SB_RELEASE_CANDIDATE_API_VERSION` is -not defined if there is no "release candidate" version. Every API version -greater than `SB_RELEASE_CANDIDATE_API_VERSION` but less than `SB_EXPERIMENTAL_API_VERSION` is also considered a release candidate. ### "Frozen" Starboard versions -All Starboard versions that are less than the experimental and release candidate -versions are considered frozen. Any Starboard APIs in a frozen version MUST not -change. - -### Version Numbers, and how They Interrelate Numerically - -``` -frozen < release-candidate < experimental < future -``` - -As mentioned previously, a release candidate version may or may not exist at any -given time. When there is a release candate version, it follows the invariant -above. - -### Life of a Starboard API - -New Starboard APIs should be defined in the experimental version. - -When introducing a new Starboard API (or modifying an existing one), a new -feature version define should be created within the "Experimental Feature -Defines" section of `starboard/configuration.h`, and set to -`SB_EXPERIMENTAL_API_VERSION`. A well written comment should be added in front -of the feature define that describes exactly what is introduced by the feature. -In the comment, all new/modified/removed symbols should be identified, and all -modified header files should be named. - -For example, - -``` -// in starboard/configuration.h - -#define SB_EXPERIMENTAL_API_VERSION 7 - -#undef SB_RELEASE_CANDIDATE_API_VERSION - -// --- Experimental Feature Defines ------------------------------------------ - -... - -// Introduce a new API in starboard/screensaver.h, which declares the following -// functions for managing the platform's screensaver settings: -// SbScreensaverDisableScreensaver() -// SbScreensaverEnableScreensaver() -// Additionally, a new event, kSbEventTypeScreensaverStarted, is introduced in -// starboard/event.h. -#define SB_SCREENSAVER_FEATURE_API_VERSION SB_EXPERIMENTAL_API_VERSION - -// Introduce a new API in starboard/new_functionality.h which declares the -// function SbNewFunctionality(). -#define SB_MY_NEW_FEATURE_API_VERSION SB_EXPERIMENTAL_API_VERSION - -// Introduce another new API in starboard/still_in_development.h which -// declares the function SbStillInDevelopment(). -#define SB_MY_OTHER_NEW_FEATURE_API_VERSION SB_EXPERIMENTAL_API_VERSION -``` - -When declaring the new interface, the following syntax should be used: - -``` -// starboard/new_functionality.h -#if SB_API_VERSION >= SB_MY_NEW_FEATURE_API_VERSION -void SbNewFunctionality(); -#endif -``` - -Starboard application features that use a new API must have a similar check: - -``` -// cobalt/new_feature.cc -#if SB_API_VERSION >= SB_MY_NEW_FEATURE_API_VERSION -void DoSomethingCool() { - SbNewFunctionality(); -} -#endif -``` - -When promoting the experimental API version to be the release candidate API -version, the previously undefined `SB_RELEASE_CANDIDATE_API_VERSION` is set to -the current value of `SB_EXPERIMENTAL_API_VERSION`, and -`SB_EXPERIMENTAL_API_VERSION` is then incremented by one. As a result, -`SB_RELEASE_CANDIDATE_API_VERSION` on the master branch should always either be -undefined, or `SB_EXPERIMENTAL_API_VERSION - 1`. - -One or more features are then moved from `SB_EXPERIMENTAL_API_VERSION` to -`SB_RELEASE_CANDIDATE_API_VERSION`, and into the "Release Candidate Feature -Defines" section of `starboard/configuration.h`. Some features may be left in -experimental if they are not ready for release. The documentation comments of -these features should be moved into the (newly created) section for the -corresponding version in [starboard/CHANGELOG.md](../CHANGELOG.md). - -``` -// in starboard/configuration.h - -#define SB_EXPERIMENTAL_API_VERSION 8 - -#define SB_RELEASE_CANDIDATE_API_VERSION 7 - -// --- Experimental Feature Defines ------------------------------------------ - -// Introduce another new API in starboard/still_in_development.h which -// declares the function SbStillInDevelopment(). -#define SB_MY_OTHER_NEW_FEATURE_API_VERSION SB_EXPERIMENTAL_API_VERSION - -// --- Release Candidate Features Defines ------------------------------------ - -#define SB_MY_NEW_FEATURE_API_VERSION SB_RELEASE_CANDIDATE_API_VERSION - -``` - -When a release candidate branch is promoted to a full release, these new -Starboard APIs will be irrevocably frozen to the value of -`SB_RELEASE_CANDIDATE_API_VERSION`, and the release candidate version will be -undefined. Additionally, the feature defines should be removed. - -``` -// starboard/new_functionality.h -#if SB_API_VERSION >= 7 -void SbNewFunctionality(); -#endif - -// starboard/other_new_functionality.h -#if SB_API_VERSION >= SB_MY_OTHER_NEW_FEATURE_API_VERSION -void SbStillInDevelopment(); -#endif - -// starboard/configuration.h -#define SB_EXPERIMENTAL_API_VERSION 8 -#undef SB_RELEASE_CANDIDATE_API_VERSION - -// cobalt/new_feature.cc -#if SB_API_VERSION >= 7 -void DoSomethingCool() { - SbNewFunctionality(); -} -#endif -``` - -Whoever increments the experimental version must ensure that stubs and reference -platforms declare support for the new experimental version through their -respective `SB_API_VERSION` macros. +All Starboard versions that are less than the `SB_MAXIMUM_API_VERSION` version +are considered frozen. Any Starboard APIs in a frozen version MUST not change. ### Communicating Starboard API changes to porters diff --git a/cobalt/site/docs/reference/starboard/configuration-public.md b/cobalt/site/docs/reference/starboard/configuration-public.md index 6300b740994f2..f9f7adb6665aa 100644 --- a/cobalt/site/docs/reference/starboard/configuration-public.md +++ b/cobalt/site/docs/reference/starboard/configuration-public.md @@ -3,6 +3,13 @@ Book: /youtube/cobalt/_book.yaml # Starboard Configuration Reference Guide +## Media Configuration + +| Properties | +| :--- | +| **`SB_HAS_QUIRK_SUPPORT_INT16_AUDIO_SAMPLES`**

The implementation is allowed to support kSbMediaAudioSampleTypeInt16 only when this macro is defined.

By default, this property is undefined. | + + ## Network Configuration | Properties | @@ -21,3 +28,5 @@ Book: /youtube/cobalt/_book.yaml | **`SB_IS_WCHAR_T_UTF32`**

Type detection for wchar_t.

The default value in the Stub implementation is `1` | | **`SB_IS_WCHAR_T_UTF16`**

The default value in the Stub implementation is `1` | | **`SB_IS_WCHAR_T_UNSIGNED`**

Chrome only defines this for ARMEL. Chrome has an exclusion for iOS here, we should too when we support iOS.

The default value in the Stub implementation is `1` | + + diff --git a/cobalt/site/docs/reference/starboard/gn-configuration.md b/cobalt/site/docs/reference/starboard/gn-configuration.md index f3e517354ca5b..a93fae0df15da 100644 --- a/cobalt/site/docs/reference/starboard/gn-configuration.md +++ b/cobalt/site/docs/reference/starboard/gn-configuration.md @@ -13,7 +13,7 @@ Book: /youtube/cobalt/_book.yaml | **`enable_in_app_dial`**

Enables or disables the DIAL server that runs inside Cobalt. Note: Only enable if there's no system-wide DIAL support.

The default value is `false`. | | **`executable_configs`**

Target-specific configurations for executable targets.

The default value is `[]`. | | **`final_executable_type`**

The target type for executable targets. Allows changing the target type on platforms where the native code may require an additional packaging step (ex. Android).

The default value is `"executable"`. | -| **`gl_type`**

The source of EGL and GLES headers and libraries. Valid values (case and everything sensitive!):
  • none - No EGL + GLES implementation is available on this platform.
  • system_gles2 - Use the system implementation of EGL + GLES2. The headers and libraries must be on the system include and link paths.
  • glimp - Cobalt's own EGL + GLES2 implementation. This requires a valid Glimp implementation for the platform.
  • angle - A DirectX-to-OpenGL adaptation layer. This requires a valid ANGLE implementation for the platform.

    The default value is `"system_gles2"`. | +| **`gl_type`**

    The source of EGL and GLES headers and libraries. Valid values (case and everything sensitive!):
    • system_gles2 - Use the system implementation of EGL + GLES2. The headers and libraries must be on the system include and link paths.
    • glimp - Cobalt's own EGL + GLES2 implementation. This requires a valid Glimp implementation for the platform.
    • angle - A DirectX-to-OpenGL adaptation layer. This requires a valid ANGLE implementation for the platform.

      The default value is `"system_gles2"`. | | **`gtest_target_type`**

      The target type for test targets. Allows changing the target type on platforms where the native code may require an additional packaging step (ex. Android).

      The default value is `"executable"`. | | **`has_platform_targets`**

      Whether the platform has platform-specific targets to depend on.

      The default value is `false`. | | **`install_target_path`**

      The path to the gni file containing the install_target template which defines how the build should produce the install/ directory.

      The default value is `"//starboard/build/install/no_install.gni"`. | @@ -26,11 +26,13 @@ Book: /youtube/cobalt/_book.yaml | **`sb_api_version`**

      The Starboard API version of the current build configuration. The default value is meant to be overridden by a Starboard ABI file.

      The default value is `16`. | | **`sb_enable_benchmark`**

      Used to enable benchmarks.

      The default value is `false`. | | **`sb_enable_cpp17_audit`**

      Enables an NPLB audit of C++17 support.

      The default value is `true`. | +| **`sb_enable_cpp20_audit`**

      Enables an NPLB audit of C++20 support.

      The default value is `true`. | | **`sb_enable_lib`**

      Enables embedding Cobalt as a shared library within another app. This requires a 'lib' starboard implementation for the corresponding platform.

      The default value is `false`. | | **`sb_enable_opus_sse`**

      Enables optimizations on SSE compatible platforms.

      The default value is `true`. | | **`sb_evergreen_compatible_package`**

      Whether to generate the whole package containing both Loader app and Cobalt core on the Evergreen compatible platform.

      The default value is `false`. | | **`sb_evergreen_compatible_use_libunwind`**

      Whether to use the libunwind library on Evergreen compatible platform.

      The default value is `false`. | | **`sb_filter_based_player`**

      Used to indicate that the player is filter based.

      The default value is `true`. | +| **`sb_has_unused_symbol_issue`**

      Set this to true if the modular toolchain linker doesn't strip all unused symbols and nplb fails to link.

      The default value is `false`. | | **`sb_is_evergreen`**

      Whether this is an Evergreen build.

      The default value is `false`. | | **`sb_is_evergreen_compatible`**

      Whether this is an Evergreen compatible platform. A compatible platform can run the elf_loader and launch the Evergreen build.

      The default value is `false`. | | **`sb_libevent_method`**

      The event polling mechanism available on this platform to support libevent. Platforms may redefine to 'poll' if necessary. Other mechanisms, e.g. devpoll, kqueue, select, are not yet supported.

      The default value is `"epoll"`. | diff --git a/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md deleted file mode 100644 index 72dc9327ed1e3..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md +++ /dev/null @@ -1,75 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `byte_swap.h` - -Specifies functions for swapping byte order. These functions are used to deal -with endianness when performing I/O. - -## Functions - -### SbByteSwapS16 - -Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int16_t SbByteSwapS16(int16_t value) -``` - -### SbByteSwapS32 - -Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int32_t SbByteSwapS32(int32_t value) -``` - -### SbByteSwapS64 - -Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int64_t SbByteSwapS64(int64_t value) -``` - -### SbByteSwapU16 - -Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint16_t SbByteSwapU16(uint16_t value) -``` - -### SbByteSwapU32 - -Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint32_t SbByteSwapU32(uint32_t value) -``` - -### SbByteSwapU64 - -Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint64_t SbByteSwapU64(uint64_t value) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md deleted file mode 100644 index 2d8f30b5fdce2..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md +++ /dev/null @@ -1,140 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `condition_variable.h` - -Defines an interface for condition variables. - -## Macros - -### SB_CONDITION_VARIABLE_MAX_SIZE - -Max size of the SbConditionVariable type. - -## Enums - -### SbConditionVariableResult - -Enumeration of possible results from waiting on a condvar. - -#### Values - -* `kSbConditionVariableSignaled` - - The wait completed because the condition variable was signaled. -* `kSbConditionVariableTimedOut` - - The wait completed because it timed out, and was not signaled. -* `kSbConditionVariableFailed` - - The wait failed, either because a parameter wasn't valid, or the condition - variable has already been destroyed, or something similar. - -## Typedefs - -### SbConditionVariable - -An opaque handle to a condition variable type with reserved memory buffer of -size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbConditionVariable SbConditionVariable -``` - -## Functions - -### SbConditionVariableBroadcast - -Broadcasts to all current waiters of `condition` to stop waiting. This function -wakes all of the threads waiting on `condition` while SbConditionVariableSignal -wakes a single thread. - -`condition`: The condition that should no longer be waited for. - -#### Declaration - -``` -bool SbConditionVariableBroadcast(SbConditionVariable *condition) -``` - -### SbConditionVariableCreate - -Creates a new condition variable to work with `opt_mutex`, which may be null, -placing the newly created condition variable in `out_condition`. - -The return value indicates whether the condition variable could be created. - -#### Declaration - -``` -bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) -``` - -### SbConditionVariableDestroy - -Destroys the specified SbConditionVariable . The return value indicates whether -the destruction was successful. The behavior is undefined if other threads are -currently waiting on this condition variable. - -`condition`: The SbConditionVariable to be destroyed. This invalidates the -condition variable. - -#### Declaration - -``` -bool SbConditionVariableDestroy(SbConditionVariable *condition) -``` - -### SbConditionVariableIsSignaled - -Returns whether the given result is a success. - -#### Declaration - -``` -static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) -``` - -### SbConditionVariableSignal - -Signals the next waiter of `condition` to stop waiting. This function wakes a -single thread waiting on `condition` while SbConditionVariableBroadcast wakes -all threads waiting on it. - -`condition`: The condition that the waiter should stop waiting for. - -#### Declaration - -``` -bool SbConditionVariableSignal(SbConditionVariable *condition) -``` - -### SbConditionVariableWait - -Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, -and returning the result. Behavior is undefined if `mutex` is not held. - -#### Declaration - -``` -SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) -``` - -### SbConditionVariableWaitTimed - -Waits for `condition`, releasing the held lock `mutex`, blocking up to -`timeout_duration`, and returning the acquisition result. Behavior is undefined -if `mutex` is not held. - -`timeout_duration`: The maximum amount of time that function should wait for -`condition`. If the `timeout_duration` value is less than or equal to zero, the -function returns as quickly as possible with a kSbConditionVariableTimedOut -result. - -#### Declaration - -``` -SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime timeout_duration) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/image.md b/cobalt/site/docs/reference/starboard/modules/13/image.md deleted file mode 100644 index 945938a099033..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/image.md +++ /dev/null @@ -1,77 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `image.h` - -API for hardware accelerated image decoding. This module allows for the client -to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It -also provides an interface for the client to query what combinations of encoded -image formats and SbDecodeTargetFormats are supported or not. - -All functions in this module are safe to call from any thread at any point in -time. - -## SbImageIsDecodeSupported and SbImageDecode Example - -``` -SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); -void* data = GetCompressedJPEGFromSomewhere(); -int data_size = GetCompressedJPEGSizeFromSomewhere(); -const char* mime_type = "image/jpeg"; -SbDecodeTargetFormat format = kSbDecodeTargetFormat1PlaneRGBA; - -if (!SbImageIsDecodeSupported(mime_type, format)) { - return; -} - -SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, - mime_type, format); -``` - -## Functions - -### SbImageDecode - -Attempt to decode encoded `mime_type` image data `data` of size `data_size` into -an SbDecodeTarget of SbDecodeFormatType `format`, possibly using -SbDecodeTargetProvider `provider`, if it is non-null. Thus, four following -scenarios regarding the provider may happen: - -1. The provider is required by the `SbImageDecode` implementation and no - provider is given. The implementation should gracefully fail by immediately - returning kSbDecodeTargetInvalid. - -1. The provider is required and is passed in. The implementation will proceed - forward, using the SbDecodeTarget from the provider. - -1. The provider is not required and is passed in. The provider will NOT be - called, and the implementation will proceed to decoding however it desires. - -1. The provider is not required and is not passed in. The implementation will - proceed forward. The `data` pointer must not be NULL. The `mime_type` string - must not be NULL. Thus, it is NOT safe for clients of this API to assume - that the `provider` it passes in will be called. Finally, if the decode - succeeds, a new SbDecodeTarget will be allocated. If `mime_type` image - decoding for the requested format is not supported or the decode fails, - kSbDecodeTargetInvalid will be returned, with any intermediate allocations - being cleaned up in the implementation. - -#### Declaration - -``` -SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) -``` - -### SbImageIsDecodeSupported - -Whether the current platform supports hardware accelerated decoding an image of -mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must -not be NULL. The result of this function must not change over the course of the -program, which means that the results of this function may be cached -indefinitely. - -#### Declaration - -``` -bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory.md b/cobalt/site/docs/reference/starboard/modules/13/memory.md deleted file mode 100644 index 0c404e36ea30c..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/memory.md +++ /dev/null @@ -1,345 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `memory.h` - -Defines functions for memory allocation, alignment, copying, and comparing. - -## Porters - -All of the "Unchecked" and "Free" functions must be implemented, but they should -not be called directly. The Starboard platform wraps them with extra accounting -under certain circumstances. - -## Porters and Application Developers - -Nobody should call the "Checked", "Unchecked" or "Free" functions directly -because that evades Starboard's memory tracking. In both port implementations -and Starboard client application code, you should always call SbMemoryAllocate -and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. - -* The "checked" functions are SbMemoryAllocateChecked(), - SbMemoryReallocateChecked(), and SbMemoryAllocateAlignedChecked(). - -* The "unchecked" functions are SbMemoryAllocateUnchecked(), - SbMemoryReallocateUnchecked(), and SbMemoryAllocateAlignedUnchecked(). - -* The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). - -## Enums - -### SbMemoryMapFlags - -The bitwise OR of these flags should be passed to SbMemoryMap to indicate how -the mapped memory can be used. - -#### Values - -* `kSbMemoryMapProtectReserved` - - No flags set: Reserves virtual address space. SbMemoryProtect() can later - make it accessible. -* `kSbMemoryMapProtectRead` -* `kSbMemoryMapProtectWrite` -* `kSbMemoryMapProtectExec` -* `kSbMemoryMapProtectReadWrite` - -## Functions - -### SbMemoryAllocate - -Allocates and returns a chunk of memory of at least `size` bytes. This function -should be called from the client codebase. It is intended to be a drop-in -replacement for `malloc`. - -Note that this function returns `NULL` if it is unable to allocate the memory. - -`size`: The amount of memory to be allocated. If `size` is 0, the function may -return `NULL` or it may return a unique pointer value that can be passed to -SbMemoryDeallocate. - -#### Declaration - -``` -void* SbMemoryAllocate(size_t size) -``` - -### SbMemoryAllocateAligned - -Allocates and returns a chunk of memory of at least `size` bytes, aligned to -`alignment`. This function should be called from the client codebase. It is -meant to be a drop-in replacement for `memalign`. - -The function returns `NULL` if it cannot allocate the memory. In addition, the -function's behavior is undefined if `alignment` is not a power of two. - -`alignment`: The way that data is arranged and accessed in memory. The value -must be a power of two. `size`: The size of the memory to be allocated. If -`size` is `0`, the function may return `NULL` or it may return a unique aligned -pointer value that can be passed to SbMemoryDeallocateAligned. - -#### Declaration - -``` -void* SbMemoryAllocateAligned(size_t alignment, size_t size) -``` - -### SbMemoryAllocateAlignedChecked - -Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an -allocation failure. - -DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) -``` - -### SbMemoryAllocateAlignedUnchecked - -This is the implementation of SbMemoryAllocateAligned that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) -``` - -### SbMemoryAllocateChecked - -Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation -failure. - -DO NOT CALL. Call SbMemoryAllocate(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateChecked(size_t size) -``` - -### SbMemoryAllocateNoReport - -DEPRECATED: Same as SbMemoryAllocate(). - -#### Declaration - -``` -void* SbMemoryAllocateNoReport(size_t size) -``` - -### SbMemoryAllocateUnchecked - -This is the implementation of SbMemoryAllocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryAllocate(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateUnchecked(size_t size) -``` - -### SbMemoryCalloc - -A wrapper that implements a drop-in replacement for `calloc`, which is used in -some packages. - -#### Declaration - -``` -static void* SbMemoryCalloc(size_t count, size_t size) -``` - -### SbMemoryDeallocate - -Frees a previously allocated chunk of memory. If `memory` is NULL, then the -operation is a no-op. This function should be called from the client codebase. -It is meant to be a drop-in replacement for `free`. - -`memory`: The chunk of memory to be freed. - -#### Declaration - -``` -void SbMemoryDeallocate(void *memory) -``` - -### SbMemoryDeallocateAligned - -`memory`: The chunk of memory to be freed. If `memory` is NULL, then the -function is a no-op. - -#### Declaration - -``` -void SbMemoryDeallocateAligned(void *memory) -``` - -### SbMemoryDeallocateNoReport - -DEPRECATED: Same as SbMemoryDeallocate() - -#### Declaration - -``` -void SbMemoryDeallocateNoReport(void *memory) -``` - -### SbMemoryFlush - -Flushes any data in the given virtual address range that is cached locally in -the current processor core to physical memory, ensuring that data and -instruction caches are cleared. This is required to be called on executable -memory that has been written to and might be executed in the future. - -#### Declaration - -``` -void SbMemoryFlush(void *virtual_address, int64_t size_bytes) -``` - -### SbMemoryFree - -This is the implementation of SbMemoryDeallocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryDeallocate(...) instead. - -#### Declaration - -``` -void SbMemoryFree(void *memory) -``` - -### SbMemoryFreeAligned - -This is the implementation of SbMemoryFreeAligned that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. - -#### Declaration - -``` -void SbMemoryFreeAligned(void *memory) -``` - -### SbMemoryGetStackBounds - -Gets the stack bounds for the current thread. - -`out_high`: The highest addressable byte + 1 for the current thread. `out_low`: -The lowest addressable byte for the current thread. - -#### Declaration - -``` -void SbMemoryGetStackBounds(void **out_high, void **out_low) -``` - -### SbMemoryMap - -Allocates `size_bytes` worth of physical memory pages and maps them into an -available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on -failure. `NULL` is a valid return value. - -`size_bytes`: The amount of physical memory pages to be allocated. `flags`: The -bitwise OR of the protection flags for the mapped memory as specified in -`SbMemoryMapFlags`. Allocating executable memory is not allowed and will fail. -If executable memory is needed, map non-executable memory first and then switch -access to executable using SbMemoryProtect. When kSbMemoryMapProtectReserved is -used, the address space will not be accessible and, if possible, the platform -should not count it against any memory budget. `name`: A value that appears in -the debugger on some platforms. The value can be up to 32 bytes. - -#### Declaration - -``` -void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) -``` - -### SbMemoryProtect - -Change the protection of `size_bytes` of memory regions, starting from -`virtual_address`, to `flags`, returning `true` on success. - -#### Declaration - -``` -bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) -``` - -### SbMemoryReallocate - -Attempts to resize `memory` to be at least `size` bytes, without touching the -contents of memory. - -* If the function cannot perform the fast resize, it allocates a new chunk of - memory, copies the contents over, and frees the previous chunk, returning a - pointer to the new chunk. - -* If the function cannot perform the slow resize, it returns `NULL`, leaving - the given memory chunk unchanged. - -This function should be called from the client codebase. It is meant to be a -drop-in replacement for `realloc`. - -`memory`: The chunk of memory to be resized. `memory` may be NULL, in which case -it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which -`memory` will be resized. If `size` is `0`, the function may return `NULL` or it -may return a unique pointer value that can be passed to SbMemoryDeallocate. - -#### Declaration - -``` -void* SbMemoryReallocate(void *memory, size_t size) -``` - -### SbMemoryReallocateChecked - -Same as SbMemoryReallocateUnchecked, but will abort() in the case of an -allocation failure. - -DO NOT CALL. Call SbMemoryReallocate(...) instead. - -#### Declaration - -``` -void* SbMemoryReallocateChecked(void *memory, size_t size) -``` - -### SbMemoryReallocateUnchecked - -This is the implementation of SbMemoryReallocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryReallocate(...) instead. - -#### Declaration - -``` -void* SbMemoryReallocateUnchecked(void *memory, size_t size) -``` - -### SbMemoryUnmap - -Unmap `size_bytes` of physical pages starting from `virtual_address`, returning -`true` on success. After this function completes, [virtual_address, -virtual_address + size_bytes) will not be read/writable. This function can unmap -multiple contiguous regions that were mapped with separate calls to -SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns -`(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns -`(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. - -#### Declaration - -``` -bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md deleted file mode 100644 index 505d2a7d03471..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md +++ /dev/null @@ -1,106 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `memory_reporter.h` - -DEPRECATED: Provides an interface for memory reporting. - -## Typedefs - -### SbMemoryReporterOnAlloc - -A function to report a memory allocation from SbMemoryAllocate(). Note that -operator new calls SbMemoryAllocate which will delegate to this callback. - -#### Definition - -``` -typedef void(* SbMemoryReporterOnAlloc) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnDealloc - -A function to report a memory deallocation from SbMemoryDeallcoate(). Note that -operator delete calls SbMemoryDeallocate which will delegate to this callback. - -#### Definition - -``` -typedef void(* SbMemoryReporterOnDealloc) (void *context, const void *memory) -``` - -### SbMemoryReporterOnMapMemory - -A function to report a memory mapping from SbMemoryMap(). - -#### Definition - -``` -typedef void(* SbMemoryReporterOnMapMemory) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnUnMapMemory - -A function to report a memory unmapping from SbMemoryUnmap(). - -#### Definition - -``` -typedef void(* SbMemoryReporterOnUnMapMemory) (void *context, const void *memory, size_t size) -``` - -## Structs - -### SbMemoryReporter - -SbMemoryReporter allows memory reporting via user-supplied functions. The void* -context is passed to every call back. It's strongly recommended that C-Style -struct initialization is used so that the arguments can be typed check by the -compiler. For example, SbMemoryReporter mem_reporter = { MallocCallback, .... -context }; - -#### Members - -* `SbMemoryReporterOnAlloc on_alloc_cb` - - Callback to report allocations. -* `SbMemoryReporterOnDealloc on_dealloc_cb` - - Callback to report deallocations. -* `SbMemoryReporterOnMapMemory on_mapmem_cb` - - Callback to report memory map. -* `SbMemoryReporterOnUnMapMemory on_unmapmem_cb` - - Callback to report memory unmap. -* `void * context` - - Optional, is passed to callbacks as first argument. - -## Functions - -### SbMemorySetReporter - -Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime -management is done internally on input pointer. - -NOTE: This module is unused starting with Starboard 15 and will be removed in -the future. - -Returns true if the memory reporter was set with no errors. If an error was -reported then check the log for why it failed. - -Note that other than a thread-barrier-write of the input pointer, there is no -thread safety guarantees with this function due to performance considerations. -It's recommended that this be called once during the lifetime of the program, or -not at all. Do not delete the supplied pointer, ever. Example (Good): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); // allow value to leak. Example (Bad): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); delete mem_reporter; // May crash. - -#### Declaration - -``` -bool SbMemorySetReporter(struct SbMemoryReporter *tracker) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/mutex.md b/cobalt/site/docs/reference/starboard/modules/13/mutex.md deleted file mode 100644 index 82ff8500ab8d8..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/mutex.md +++ /dev/null @@ -1,127 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `mutex.h` - -Defines a mutually exclusive lock that can be used to coordinate with other -threads. - -## Macros - -### SB_MUTEX_MAX_SIZE - -Max size of the SbMutex type. - -## Enums - -### SbMutexResult - -Enumeration of possible results from acquiring a mutex. - -#### Values - -* `kSbMutexAcquired` - - The mutex was acquired successfully. -* `kSbMutexBusy` - - The mutex was not acquired because it was held by someone else. -* `kSbMutexDestroyed` - - The mutex has already been destroyed. - -## Typedefs - -### SbMutex - -An opaque handle to a mutex type with reserved memory buffer of size -SB_MUTEX_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbMutex SbMutex -``` - -## Functions - -### SbMutexAcquire - -Acquires `mutex`, blocking indefinitely. The return value identifies the -acquisition result. SbMutexes are not reentrant, so a recursive acquisition -blocks forever. - -`mutex`: The mutex to be acquired. - -#### Declaration - -``` -SbMutexResult SbMutexAcquire(SbMutex *mutex) -``` - -### SbMutexAcquireTry - -Acquires `mutex`, without blocking. The return value identifies the acquisition -result. SbMutexes are not reentrant, so a recursive acquisition has undefined -behavior. - -`mutex`: The mutex to be acquired. - -#### Declaration - -``` -SbMutexResult SbMutexAcquireTry(SbMutex *mutex) -``` - -### SbMutexCreate - -Creates a new mutex. The return value indicates whether the function was able to -create a new mutex. - -`out_mutex`: The handle to the newly created mutex. - -#### Declaration - -``` -bool SbMutexCreate(SbMutex *out_mutex) -``` - -### SbMutexDestroy - -Destroys a mutex. The return value indicates whether the destruction was -successful. Destroying a locked mutex results in undefined behavior. - -`mutex`: The mutex to be invalidated. - -#### Declaration - -``` -bool SbMutexDestroy(SbMutex *mutex) -``` - -### SbMutexIsSuccess - -Indicates whether the given result is a success. A value of `true` indicates -that the mutex was acquired. - -`result`: The result being checked. - -#### Declaration - -``` -static bool SbMutexIsSuccess(SbMutexResult result) -``` - -### SbMutexRelease - -Releases `mutex` held by the current thread. The return value indicates whether -the release was successful. Releases should always be successful if `mutex` is -held by the current thread. - -`mutex`: The mutex to be released. - -#### Declaration - -``` -bool SbMutexRelease(SbMutex *mutex) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/once.md b/cobalt/site/docs/reference/starboard/modules/13/once.md deleted file mode 100644 index d77302467f8b0..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/once.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `once.h` - -Onces represent initializations that should only ever happen once per process, -in a thread-safe way. - -## Macros - -### SB_ONCE_MAX_SIZE - -Max size of the SbOnceControl type. - -## Typedefs - -### SbOnceControl - -An opaque handle to a once control type with reserved memory buffer of size -SB_ONCE_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbOnceControl SbOnceControl -``` - -### SbOnceInitRoutine - -Function pointer type for methods that can be called via the SbOnce() system. - -#### Definition - -``` -typedef void(* SbOnceInitRoutine) (void) -``` - -## Functions - -### SbOnce - -Thread-safely runs `init_routine` only once. - -* If this `once_control` has not run a function yet, this function runs - `init_routine` in a thread-safe way and then returns `true`. - -* If SbOnce() was called with `once_control` before, the function returns - `true` immediately. - -* If `once_control` or `init_routine` is invalid, the function returns - `false`. - -#### Declaration - -``` -bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/player.md b/cobalt/site/docs/reference/starboard/modules/13/player.md deleted file mode 100644 index 0dab908addc8d..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/player.md +++ /dev/null @@ -1,475 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `player.h` - -Defines an interface for controlling playback of media elementary streams. - -## Macros - -### SB_PLAYER_INITIAL_TICKET - -The value of the initial ticket held by the player before the first seek. The -player will use this ticket value to make the first call to SbPlayerStatusFunc -with kSbPlayerStateInitialized. - -### SB_PLAYER_NO_DURATION - -The value to pass into SbPlayerCreate's `duration_pts` argument for cases where -the duration is unknown, such as for live streams. - -### kSbPlayerInvalid - -Well-defined value for an invalid player. - -## Enums - -### SbPlayerDecoderState - -An indicator of whether the decoder can accept more samples. - -#### Values - -* `kSbPlayerDecoderStateNeedsData` - - The decoder is asking for one more sample. - -### SbPlayerSampleSideDataType - -Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side -data may come from multiple sources. - -#### Values - -* `kMatroskaBlockAdditional` - - The side data comes from the BlockAdditional data in the Matroska/Webm - container, as specified in [https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39](https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39)9) andnd [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional)l) - . The first 8 bytes of the data contains the value of BlockAddID in big - endian format, followed by the content of BlockAdditional. - -### SbPlayerState - -An indicator of the general playback state. - -#### Values - -* `kSbPlayerStateInitialized` - - The player has just been initialized. It is expecting an SbPlayerSeek() call - to enter the prerolling state. -* `kSbPlayerStatePrerolling` - - The player is prerolling, collecting enough data to fill the pipeline before - presentation starts. After the first preroll is completed, there should - always be a video frame to render, even if the player goes back to - Prerolling after a Seek. -* `kSbPlayerStatePresenting` - - The player is presenting media, and it is either paused or actively playing - in real-time. Note that the implementation should use this state to signal - that the preroll has been finished. -* `kSbPlayerStateEndOfStream` - - The player is presenting media, but it is paused at the end of the stream. -* `kSbPlayerStateDestroyed` - - The player has been destroyed, and will send no more callbacks. - -## Typedefs - -### SbPlayer - -An opaque handle to an implementation-private structure representing a player. - -#### Definition - -``` -typedef struct SbPlayerPrivate* SbPlayer -``` - -### SbPlayerDeallocateSampleFunc - -Callback to free the given sample buffer data. When more than one buffer are -sent in SbPlayerWriteSample(), the implementation only has to call this callback -with `sample_buffer` points to the first buffer. - -#### Definition - -``` -typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) -``` - -### SbPlayerDecoderStatusFunc - -Callback for decoder status updates, called in response to a call to -SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called -until at least one call to SbPlayerSeek has occurred. `ticket` will be set to -the ticket passed into the last received call to SbPlayerSeek() at the time this -callback was dispatched. This is to distinguish status callbacks for -interrupting seeks. These callbacks will happen on a different thread than the -calling thread, and it is not valid to call SbPlayer functions from within this -callback. After an update with kSbPlayerDecoderStateNeedsData, the user of the -player will make at most one call to SbPlayerWriteSample() or -SbPlayerWriteEndOfStream(). The player implementation should update the decoder -status again after such call to notify its user to continue writing more frames. - -#### Definition - -``` -typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) -``` - -### SbPlayerErrorFunc - -Callback for player errors, that may set a `message`. `error`: indicates the -error code. `message`: provides specific informative diagnostic message about -the error condition encountered. It is ok for the message to be an empty string -or NULL if no information is available. - -#### Definition - -``` -typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) -``` - -### SbPlayerStatusFunc - -Callback for player status updates. These callbacks will happen on a different -thread than the calling thread, and it is not valid to call SbPlayer functions -from within this callback. - -#### Definition - -``` -typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) -``` - -## Structs - -### SbPlayerCreationParam - -The playback related parameters to pass into SbPlayerCreate() and -SbPlayerGetPreferredOutputMode(). - -#### Members - -* `SbDrmSystem drm_system` - - Provides an appropriate DRM system if the media stream has encrypted - portions. It will be `kSbDrmSystemInvalid` if the stream does not have - encrypted portions. -* `SbMediaAudioSampleInfo audio_sample_info` - - Contains a populated SbMediaAudioSampleInfo if `audio_sample_info.codec` - isn't `kSbMediaAudioCodecNone`. When `audio_sample_info.codec` is - `kSbMediaAudioCodecNone`, the video doesn't have an audio track. -* `SbMediaVideoSampleInfo video_sample_info` - - Contains a populated SbMediaVideoSampleInfo if `video_sample_info.codec` - isn't `kSbMediaVideoCodecNone`. When `video_sample_info.codec` is - `kSbMediaVideoCodecNone`, the video is audio only. -* `SbPlayerOutputMode output_mode` - - Selects how the decoded video frames will be output. For example, - `kSbPlayerOutputModePunchOut` indicates that the decoded video frames will - be output to a background video layer by the platform, and - `kSbPlayerOutputDecodeToTexture` indicates that the decoded video frames - should be made available for the application to pull via calls to - SbPlayerGetCurrentFrame(). - -### SbPlayerInfo2 - -Information about the current media playback state. - -#### Members - -* `SbTime current_media_timestamp` - - The position of the playback head, as precisely as possible, in - microseconds. -* `SbTime duration` - - The known duration of the currently playing media stream, in microseconds. -* `SbTime start_date` - - The result of getStartDate for the currently playing media stream, in - microseconds since the epoch of January 1, 1601 UTC. -* `int frame_width` - - The width of the currently displayed frame, in pixels, or 0 if not provided - by this player. -* `int frame_height` - - The height of the currently displayed frame, in pixels, or 0 if not provided - by this player. -* `bool is_paused` - - Whether playback is currently paused. -* `double volume` - - The current player volume in [0, 1]. -* `int total_video_frames` - - The number of video frames sent to the player since the creation of the - player. -* `int dropped_video_frames` - - The number of video frames decoded but not displayed since the creation of - the player. -* `int corrupted_video_frames` - - The number of video frames that failed to be decoded since the creation of - the player. -* `double playback_rate` - - The rate of playback. The video is played back in a speed that is - proportional to this. By default it is 1.0 which indicates that the playback - is at normal speed. When it is greater than one, the video is played in a - faster than normal speed. When it is less than one, the video is played in a - slower than normal speed. Negative speeds are not supported. - -### SbPlayerSampleInfo - -Information about the samples to be written into SbPlayerWriteSamples(). - -#### Members - -* `SbMediaType type` -* `const void * buffer` - - Points to the buffer containing the sample data. -* `int buffer_size` - - Size of the data pointed to by `buffer`. -* `SbTime timestamp` - - The timestamp of the sample in SbTime. -* `SbPlayerSampleSideData* side_data` - - Points to an array of side data for the input, when available. -* `int side_data_count` - - The number of side data pointed by `side_data`. It should be set to 0 if - there is no side data for the input. -* `SbMediaAudioSampleInfo audio_sample_info` - - Information about an audio sample. This value can only be used when `type` - is kSbMediaTypeAudio. -* `SbMediaVideoSampleInfo video_sample_info` - - Information about a video sample. This value can only be used when `type` is - kSbMediaTypeVideo. -* `union SbPlayerSampleInfo::@0 @1` -* `constSbDrmSampleInfo* drm_info` - - The DRM system related info for the media sample. This value is required for - encrypted samples. Otherwise, it must be `NULL`. - -### SbPlayerSampleSideData - -Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data -coming from multiple sources. - -#### Members - -* `SbPlayerSampleSideDataType type` -* `const uint8_t * data` - - `data` will remain valid until SbPlayerDeallocateSampleFunc() is called on - the `SbPlayerSampleInfo::buffer` the data is associated with. -* `size_t size` - - The size of the data pointed by `data`, in bytes. - -## Functions - -### SbPlayerDestroy - -Destroys `player`, freeing all associated resources. - -* Upon calling this method, there should be one call to the player status - callback (i.e. `player_status_func` used in the creation of the player) - which indicates the player is destroyed. Note, the callback has to be in- - flight when SbPlayerDestroyed is called. - -* No more other callbacks should be issued after this function returns. - -* It is not allowed to pass `player` into any other `SbPlayer` function once - SbPlayerDestroy has been called on that player. `player`: The player to be - destroyed. Must not be `kSbPlayerInvalid`. - -#### Declaration - -``` -void SbPlayerDestroy(SbPlayer player) -``` - -### SbPlayerGetCurrentFrame - -Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, -it will return a SbDecodeTarget representing the current frame to be rasterized. -On GLES systems, this function must be called on a thread with an EGLContext -current, and specifically the EGLContext that will be used to eventually render -the frame. If this function is called with a `player` object that was created -with an output mode other than kSbPlayerOutputModeDecodeToTexture, -kSbDecodeTargetInvalid is returned. - -`player` must not be `kSbPlayerInvalid`. - -#### Declaration - -``` -SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) -``` - -### SbPlayerGetMaximumNumberOfSamplesPerWrite - -Writes a single sample of the given media type to `player`'s input stream. Its -data may be passed in via more than one buffers. The lifetime of -`sample_buffers`, `sample_buffer_sizes`, `video_sample_info`, and -`sample_drm_info` (as well as member `subsample_mapping` contained inside it) -are not guaranteed past the call to SbPlayerWriteSample. That means that before -returning, the implementation must synchronously copy any information it wants -to retain from those structures. - -`player`: The player for which the number is retrieved. `sample_type`: The type -of sample for which the number is retrieved. See the `SbMediaType` enum in -media.h. - -#### Declaration - -``` -int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) -``` - -### SbPlayerGetPreferredOutputMode - -Returns the preferred output mode of the implementation when a video described -by `creation_param` is played. It is assumed that it is okay to call -SbPlayerCreate() with the same video described by `creation_param`, with its -`output_mode` member replaced by the returned output mode. When the caller has -no preference on the output mode, it will set `creation_param->output_mode` to -`kSbPlayerOutputModeInvalid`, and the implementation can return its preferred -output mode based on the information contained in `creation_param`. The caller -can also set `creation_param->output_mode` to its preferred output mode, and the -implementation should return the same output mode if it is supported, otherwise -the implementation should return an output mode that it is supported, as if -`creation_param->output_mode` is set to `kSbPlayerOutputModeInvalid` prior to -the call. Note that it is not the responsibility of this function to verify -whether the video described by `creation_param` can be played on the platform, -and the implementation should try its best effort to return a valid output mode. -`creation_param` must not be NULL. - -#### Declaration - -``` -SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) -``` - -### SbPlayerIsValid - -Returns whether the given player handle is valid. - -#### Declaration - -``` -static bool SbPlayerIsValid(SbPlayer player) -``` - -### SbPlayerSetBounds - -Sets the player bounds to the given graphics plane coordinates. The changes do -not take effect until the next graphics frame buffer swap. The default bounds -for a player is the full screen. This function is only relevant when the -`player` is created with the kSbPlayerOutputModePunchOut output mode, and if -this is not the case then this function call can be ignored. - -This function is called on every graphics frame that changes the video bounds. -For example, if the video bounds are being animated, then this will be called at -up to 60 Hz. Since the function could be called up to once per frame, -implementors should take care to avoid related performance concerns with such -frequent calls. - -`player`: The player that is being resized. Must not be `kSbPlayerInvalid`. -`z_index`: The z-index of the player. When the bounds of multiple players are -overlapped, the one with larger z-index will be rendered on top of the ones with -smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. -`y`: The y-coordinate of the upper-left corner of the player. `width`: The width -of the player, in pixels. `height`: The height of the player, in pixels. - -#### Declaration - -``` -void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) -``` - -### SbPlayerSetPlaybackRate - -Set the playback rate of the `player`. `rate` is default to 1.0 which indicates -the playback is at its original speed. A `rate` greater than one will make the -playback faster than its original speed. For example, when `rate` is 2, the -video will be played at twice the speed as its original speed. A `rate` less -than 1.0 will make the playback slower than its original speed. When `rate` is -0, the playback will be paused. The function returns true when the playback rate -is set to `playback_rate` or to a rate that is close to `playback_rate` which -the implementation supports. It returns false when the playback rate is -unchanged, this can happen when `playback_rate` is negative or if it is too high -to support. - -`player` must not be `kSbPlayerInvalid`. - -#### Declaration - -``` -bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) -``` - -### SbPlayerSetVolume - -Sets the player's volume. - -`player`: The player in which the volume is being adjusted. Must not be -`kSbPlayerInvalid`. `volume`: The new player volume. The value must be between -`0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be -muted, and a value of `1.0` means that it should be played at full volume. - -#### Declaration - -``` -void SbPlayerSetVolume(SbPlayer player, double volume) -``` - -### SbPlayerWriteEndOfStream - -Writes a marker to `player`'s input stream of `stream_type` indicating that -there are no more samples for that media type for the remainder of this media -stream. This marker is invalidated, along with the rest of the stream's -contents, after a call to SbPlayerSeek. - -`player`: The player to which the marker is written. `stream_type`: The type of -stream for which the marker is written. - -#### Declaration - -``` -void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) -``` - -### SbPlayerWriteSample2 - -`sample_type`: The type of sample being written. See the `SbMediaType` enum in -media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with -`number_of_sample_infos` elements, each holds the data for an sample, i.e. a -sequence of whole NAL Units for video, or a complete audio frame. `sample_infos` -cannot be assumed to live past the call into SbPlayerWriteSamples(), so it must -be copied if its content will be used after SbPlayerWriteSamples() returns. -`number_of_sample_infos`: Specify the number of samples contained inside -`sample_infos`. It has to be at least one, and less than the return value of -SbPlayerGetMaximumNumberOfSamplesPerWrite(). - -#### Declaration - -``` -void SbPlayerWriteSample2(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/string.md b/cobalt/site/docs/reference/starboard/modules/13/string.md deleted file mode 100644 index 3fed809df4618..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/string.md +++ /dev/null @@ -1,174 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `string.h` - -Defines functions for interacting with c-style strings. - -## Functions - -### SbStringCompareNoCase - -Compares two strings, ignoring differences in case. The return value is: - -* `< 0` if `string1` is ASCII-betically lower than `string2`. - -* `0` if the two strings are equal. - -* `> 0` if `string1` is ASCII-betically higher than `string2`. - -This function is meant to be a drop-in replacement for `strcasecmp`. - -`string1`: The first string to compare. `string2`: The second string to compare. - -#### Declaration - -``` -int SbStringCompareNoCase(const char *string1, const char *string2) -``` - -### SbStringCompareNoCaseN - -Compares the first `count` characters of two strings, ignoring differences in -case. The return value is: - -* `< 0` if `string1` is ASCII-betically lower than `string2`. - -* `0` if the two strings are equal. - -* `> 0` if `string1` is ASCII-betically higher than `string2`. - -This function is meant to be a drop-in replacement for `strncasecmp`. - -`string1`: The first string to compare. `string2`: The second string to compare. -`count`: The number of characters to compare. - -#### Declaration - -``` -int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) -``` - -### SbStringDuplicate - -Copies `source` into a buffer that is allocated by this function and that can be -freed with SbMemoryDeallocate. This function is meant to be a drop-in -replacement for `strdup`. - -`source`: The string to be copied. - -#### Declaration - -``` -char* SbStringDuplicate(const char *source) -``` - -### SbStringFormat - -Produces a string formatted with `format` and `arguments`, placing as much of -the result that will fit into `out_buffer`. The return value specifies the -number of characters that the format would produce if `buffer_size` were -infinite. - -This function is meant to be a drop-in replacement for `vsnprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `arguments`: Variable arguments used in the string. - -#### Declaration - -``` -int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 -``` - -### SbStringFormatF - -An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This -function is meant to be a drop-in replacement for `snprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 -``` - -### SbStringFormatUnsafeF - -An inline wrapper of SbStringFormat that is meant to be a drop-in replacement -for the unsafe but commonly used `sprintf`. - -`out_buffer`: The location where the formatted string is stored. `format`: A -string that specifies how the data should be formatted. `...`: Arguments used in -the string. - -#### Declaration - -``` -static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 -``` - -### SbStringFormatWide - -This function is identical to SbStringFormat, but is for wide characters. It is -meant to be a drop-in replacement for `vswprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `arguments`: Variable arguments used in the string. - -#### Declaration - -``` -int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) -``` - -### SbStringFormatWideF - -An inline wrapper of SbStringFormatWide that converts from ellipsis to -`va_args`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) -``` - -### SbStringScan - -Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The -return value specifies the number of successfully matched items, which may be -`0`. - -This function is meant to be a drop-in replacement for `vsscanf`. - -`buffer`: The string to scan for the pattern. `pattern`: The string to search -for in `buffer`. `arguments`: Values matching `pattern` that were extracted from -`buffer`. - -#### Declaration - -``` -int SbStringScan(const char *buffer, const char *pattern, va_list arguments) -``` - -### SbStringScanF - -An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This -function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string -to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: -Values matching `pattern` that were extracted from `buffer`. - -#### Declaration - -``` -static int SbStringScanF(const char *buffer, const char *pattern,...) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/thread.md b/cobalt/site/docs/reference/starboard/modules/13/thread.md deleted file mode 100644 index 56c7898a12b43..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/thread.md +++ /dev/null @@ -1,533 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `thread.h` - -Defines functionality related to thread creation and cleanup. - -## Macros - -### kSbThreadContextInvalid - -Well-defined value for an invalid thread context. - -### kSbThreadInvalidId - -Well-defined constant value to mean "no thread ID." - -### kSbThreadLocalKeyInvalid - -Well-defined constant value to mean "no thread local key." - -### kSbThreadNoAffinity - -Well-defined constant value to mean "no affinity." - -### kSbThreadSamplerInvalid - -Well-defined value for an invalid thread sampler. - -## Enums - -### SbThreadPriority - -A spectrum of thread priorities. Platforms map them appropriately to their own -priority system. Note that scheduling is platform-specific, and what these -priorities mean, if they mean anything at all, is also platform-specific. - -In particular, several of these priority values can map to the same priority on -a given platform. The only guarantee is that each lower priority should be -treated less-than-or-equal-to a higher priority. - -#### Values - -* `kSbThreadPriorityLowest` - - The lowest thread priority available on the current platform. -* `kSbThreadPriorityLow` - - A lower-than-normal thread priority, if available on the current platform. -* `kSbThreadPriorityNormal` - - Really, what is normal? You should spend time pondering that question more - than you consider less-important things, but less than you think about more- - important things. -* `kSbThreadPriorityHigh` - - A higher-than-normal thread priority, if available on the current platform. -* `kSbThreadPriorityHighest` - - The highest thread priority available on the current platform that isn't - considered "real-time" or "time-critical," if those terms have any meaning - on the current platform. -* `kSbThreadPriorityRealTime` - - If the platform provides any kind of real-time or time-critical scheduling, - this priority will request that treatment. Real-time scheduling generally - means that the thread will have more consistency in scheduling than non- - real-time scheduled threads, often by being more deterministic in how - threads run in relation to each other. But exactly how being real-time - affects the thread scheduling is platform-specific. - - For platforms where that is not offered, or otherwise not meaningful, this - will just be the highest priority available in the platform's scheme, which - may be the same as kSbThreadPriorityHighest. -* `kSbThreadNoPriority` - - Well-defined constant value to mean "no priority." This means to use the - default priority assignment method of that platform. This may mean to - inherit the priority of the spawning thread, or it may mean a specific - default priority, or it may mean something else, depending on the platform. - -## Typedefs - -### SbThread - -An opaque handle to a thread type. - -#### Definition - -``` -typedef void* SbThread -``` - -### SbThreadAffinity - -Type for thread core affinity. This generally will be a single cpu (or core or -hyperthread) identifier. Some platforms may not support affinity, and some may -have specific rules about how it must be used. - -#### Definition - -``` -typedef int32_t SbThreadAffinity -``` - -### SbThreadContext - -A handle to the context of a frozen thread. - -#### Definition - -``` -typedef SbThreadContextPrivate* SbThreadContext -``` - -### SbThreadEntryPoint - -Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of -data passed in from the calling thread. - -#### Definition - -``` -typedef void*(* SbThreadEntryPoint) (void *context) -``` - -### SbThreadId - -An ID type that is unique per thread. - -#### Definition - -``` -typedef int32_t SbThreadId -``` - -### SbThreadLocalDestructor - -Function pointer type for Thread-Local destructors. - -#### Definition - -``` -typedef void(* SbThreadLocalDestructor) (void *value) -``` - -### SbThreadLocalKey - -A handle to a thread-local key. - -#### Definition - -``` -typedef SbThreadLocalKeyPrivate* SbThreadLocalKey -``` - -### SbThreadSampler - -A handle to a thread sampler. - -#### Definition - -``` -typedef SbThreadSamplerPrivate* SbThreadSampler -``` - -## Functions - -### SbThreadContextGetPointer - -Gets the specified pointer-type `property` from the specified `context`. Returns -`true` if successful and `out_value` has been modified, otherwise returns -`false` and `out_value` is not modified. - -#### Declaration - -``` -bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) -``` - -### SbThreadContextIsValid - -Returns whether the given thread context is valid. - -#### Declaration - -``` -static bool SbThreadContextIsValid(SbThreadContext context) -``` - -### SbThreadCreate - -Creates a new thread, which starts immediately. - -* If the function succeeds, the return value is a handle to the newly created - thread. - -* If the function fails, the return value is `kSbThreadInvalid`. - -`stack_size`: The amount of memory reserved for the thread. Set the value to `0` -to indicate that the default stack size should be used. `priority`: The thread's -priority. This value can be set to `kSbThreadNoPriority` to use the platform's -default priority. As examples, it could be set to a fixed, standard priority or -to a priority inherited from the thread that is calling SbThreadCreate(), or to -something else. `affinity`: The thread's affinity. This value can be set to -`kSbThreadNoAffinity` to use the platform's default affinity. `joinable`: -Indicates whether the thread can be joined (`true`) or should start out -"detached" (`false`). Note that for joinable threads, when you are done with the -thread handle, you must call `SbThreadJoin` to release system resources -associated with the thread. This is not necessary for detached threads, but -detached threads cannot be joined. `name`: A name used to identify the thread. -This value is used mainly for debugging, it can be `NULL`, and it might not be -used in production builds. `entry_point`: A pointer to a function that will be -executed on the newly created thread. `context`: This value will be passed to -the `entry_point` function. - -#### Declaration - -``` -SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) -``` - -### SbThreadCreateLocalKey - -Creates and returns a new, unique key for thread local data. If the function -does not succeed, the function returns `kSbThreadLocalKeyInvalid`. - -If `destructor` is specified, it will be called in the owning thread, and only -in the owning thread, when the thread exits. In that case, it is called on the -local value associated with the key in the current thread as long as the local -value is not NULL. - -`destructor`: A pointer to a function. The value may be NULL if no clean up is -needed. - -#### Declaration - -``` -SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) -``` - -### SbThreadDestroyLocalKey - -Destroys thread local data for the specified key. The function is a no-op if the -key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This -function does NOT call the destructor on any stored values. - -`key`: The key for which to destroy thread local data. - -#### Declaration - -``` -void SbThreadDestroyLocalKey(SbThreadLocalKey key) -``` - -### SbThreadDetach - -Detaches `thread`, which prevents it from being joined. This is sort of like a -non-blocking join. This function is a no-op if the thread is already detached or -if the thread is already being joined by another thread. - -`thread`: The thread to be detached. - -#### Declaration - -``` -void SbThreadDetach(SbThread thread) -``` - -### SbThreadGetCurrent - -Returns the handle of the currently executing thread. - -#### Declaration - -``` -SbThread SbThreadGetCurrent() -``` - -### SbThreadGetId - -Returns the Thread ID of the currently executing thread. - -#### Declaration - -``` -SbThreadId SbThreadGetId() -``` - -### SbThreadGetLocalValue - -Returns the pointer-sized value for `key` in the currently executing thread's -local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key -has already been destroyed. - -`key`: The key for which to return the value. - -#### Declaration - -``` -void* SbThreadGetLocalValue(SbThreadLocalKey key) -``` - -### SbThreadGetName - -Returns the debug name of the currently executing thread. - -#### Declaration - -``` -void SbThreadGetName(char *buffer, int buffer_size) -``` - -### SbThreadIsCurrent - -Returns whether `thread` is the current thread. - -`thread`: The thread to check. - -#### Declaration - -``` -static bool SbThreadIsCurrent(SbThread thread) -``` - -### SbThreadIsEqual - -Indicates whether `thread1` and `thread2` refer to the same thread. - -`thread1`: The first thread to compare. `thread2`: The second thread to compare. - -#### Declaration - -``` -bool SbThreadIsEqual(SbThread thread1, SbThread thread2) -``` - -### SbThreadIsValid - -Returns whether the given thread handle is valid. - -#### Declaration - -``` -static bool SbThreadIsValid(SbThread thread) -``` - -### SbThreadIsValidAffinity - -Returns whether the given thread affinity is valid. - -#### Declaration - -``` -static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) -``` - -### SbThreadIsValidId - -Returns whether the given thread ID is valid. - -#### Declaration - -``` -static bool SbThreadIsValidId(SbThreadId id) -``` - -### SbThreadIsValidLocalKey - -Returns whether the given thread local variable key is valid. - -#### Declaration - -``` -static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) -``` - -### SbThreadIsValidPriority - -Returns whether the given thread priority is valid. - -#### Declaration - -``` -static bool SbThreadIsValidPriority(SbThreadPriority priority) -``` - -### SbThreadJoin - -Joins the thread on which this function is called with joinable `thread`. This -function blocks the caller until the designated thread exits, and then cleans up -that thread's resources. The cleanup process essentially detaches thread. - -The return value is `true` if the function is successful and `false` if `thread` -is invalid or detached. - -Each joinable thread can only be joined once and must be joined to be fully -cleaned up. Once SbThreadJoin is called, the thread behaves as if it were -detached to all threads other than the joining thread. - -`thread`: The thread to which the current thread will be joined. The `thread` -must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, -then the SbThreadJoin function populates it with the return value of the -thread's `main` function. - -#### Declaration - -``` -bool SbThreadJoin(SbThread thread, void **out_return) -``` - -### SbThreadSamplerCreate - -Creates a new thread sampler for the specified `thread`. - -If successful, this function returns the newly created handle. If unsuccessful, -this function returns `kSbThreadSamplerInvalid`. - -#### Declaration - -``` -SbThreadSampler SbThreadSamplerCreate(SbThread thread) -``` - -### SbThreadSamplerDestroy - -Destroys the `sampler` and frees whatever resources it was using. - -#### Declaration - -``` -void SbThreadSamplerDestroy(SbThreadSampler sampler) -``` - -### SbThreadSamplerFreeze - -Suspends execution of the thread that `sampler` was created for. - -If successful, this function returns a `SbThreadContext` for the frozen thread, -from which properties may be read while the thread remains frozen. If -unsuccessful, this function returns `kSbThreadContextInvalid`. - -#### Declaration - -``` -SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) -``` - -### SbThreadSamplerIsSupported - -Whether the current platform supports thread sampling. The result of this -function must not change over the course of the program, which means that the -results of this function may be cached indefinitely. If this returns false, -`SbThreadSamplerCreate` will return an invalid sampler. - -#### Declaration - -``` -bool SbThreadSamplerIsSupported() -``` - -### SbThreadSamplerIsValid - -Returns whether the given thread sampler is valid. - -#### Declaration - -``` -static bool SbThreadSamplerIsValid(SbThreadSampler sampler) -``` - -### SbThreadSamplerThaw - -Resumes execution of the thread that `sampler` was created for. This invalidates -the context returned from `SbThreadSamplerFreeze`. - -#### Declaration - -``` -bool SbThreadSamplerThaw(SbThreadSampler sampler) -``` - -### SbThreadSetLocalValue - -Sets the pointer-sized value for `key` in the currently executing thread's local -storage. The return value indicates whether `key` is valid and has not already -been destroyed. - -`key`: The key for which to set the key value. `value`: The new pointer-sized -key value. - -#### Declaration - -``` -bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) -``` - -### SbThreadSetName - -Sets the debug name of the currently executing thread by copying the specified -name string. - -`name`: The name to assign to the thread. - -#### Declaration - -``` -void SbThreadSetName(const char *name) -``` - -### SbThreadSleep - -Sleeps the currently executing thread. - -`duration`: The minimum amount of time, in microseconds, that the currently -executing thread should sleep. The function is a no-op if this value is negative -or `0`. - -#### Declaration - -``` -void SbThreadSleep(SbTime duration) -``` - -### SbThreadYield - -Yields the currently executing thread, so another thread has a chance to run. - -#### Declaration - -``` -void SbThreadYield() -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/time.md b/cobalt/site/docs/reference/starboard/modules/13/time.md deleted file mode 100644 index a6228cc0de6ce..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/time.md +++ /dev/null @@ -1,152 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `time.h` - -Provides access to system time and timers. - -## Macros - -### kSbTimeDay - -One day in SbTime units (microseconds). - -### kSbTimeHour - -One hour in SbTime units (microseconds). - -### kSbTimeMax - -The maximum value of an SbTime. - -### kSbTimeMillisecond - -One millisecond in SbTime units (microseconds). - -### kSbTimeMinute - -One minute in SbTime units (microseconds). - -### kSbTimeNanosecondsPerMicrosecond - -How many nanoseconds in one SbTime unit (microseconds). - -### kSbTimeSecond - -One second in SbTime units (microseconds). - -### kSbTimeToPosixDelta - -A term that can be added to an SbTime to convert it into the number of -microseconds since the POSIX epoch. - -## Typedefs - -### SbTime - -The number of microseconds since the epoch of January 1, 1601 UTC, or the number -of microseconds between two times. Always microseconds, ALWAYS UTC. - -#### Definition - -``` -typedef int64_t SbTime -``` - -### SbTimeMonotonic - -A number of microseconds from some point. The main property of this time is that -it increases monotonically. It should also be as high-resolution a timer as we -can get on a platform. So, it is good for measuring the time between two calls -without worrying about a system clock adjustment. It's not good for getting the -wall clock time. - -#### Definition - -``` -typedef int64_t SbTimeMonotonic -``` - -## Functions - -### SbTimeFromPosix - -Converts microseconds from the POSIX epoch into an `SbTime`. - -`time`: A time that measures the number of microseconds since January 1, 1970, -00:00:00, UTC. - -#### Declaration - -``` -static SbTime SbTimeFromPosix(int64_t time) -``` - -### SbTimeGetMonotonicNow - -Gets a monotonically increasing time representing right now. - -#### Declaration - -``` -SbTimeMonotonic SbTimeGetMonotonicNow() -``` - -### SbTimeGetMonotonicThreadNow - -Gets a monotonically increasing time representing how long the current thread -has been in the executing state (i.e. not pre-empted nor waiting on an event). -This is not necessarily total time and is intended to allow measuring thread -execution time between two timestamps. If this is not available then -SbTimeGetMonotonicNow() should be used. - -#### Declaration - -``` -SbTimeMonotonic SbTimeGetMonotonicThreadNow() -``` - -### SbTimeGetNow - -Gets the current system time as an `SbTime`. - -#### Declaration - -``` -SbTime SbTimeGetNow() -``` - -### SbTimeIsTimeThreadNowSupported - -Returns whether the current platform supports time thread now - -#### Declaration - -``` -bool SbTimeIsTimeThreadNowSupported() -``` - -### SbTimeNarrow - -Safely narrows a number from a more precise unit to a less precise one. This -function rounds negative values toward negative infinity. - -#### Declaration - -``` -static int64_t SbTimeNarrow(int64_t time, int64_t divisor) -``` - -### SbTimeToPosix - -Converts `SbTime` into microseconds from the POSIX epoch. - -`time`: A time that is either measured in microseconds since the epoch of -January 1, 1601, UTC, or that measures the number of microseconds between two -times. - -#### Declaration - -``` -static int64_t SbTimeToPosix(SbTime time) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md deleted file mode 100644 index cb41767130058..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md +++ /dev/null @@ -1,322 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `ui_navigation.h` - -API to allow applications to take advantage of the platform's native UI engine. -This is mainly to drive the animation of visual elements and to signal which of -those elements have focus. The implementation should not render any visual -elements; instead, it will be used to guide the app in where these elements -should be drawn. - -When the application creates the user interface, it will create SbUiNavItems for -interactable elements. Additionally, the app must specify the position and size -of these navigation items. As the app's user interface changes, it will create -and destroy navigation items as appropriate. - -For each render frame, the app will query the local transform for each -SbUiNavItem in case the native UI engine moves individual items in response to -user interaction. If the navigation item is a container, then the content offset -will also be queried to determine the placement of its content items. - -## Macros - -### kSbUiNavItemInvalid - -Well-defined value for an invalid navigation item. - -## Enums - -### SbUiNavItemType - -Navigation items may be one of the following types. This must be specified upon -item creation and may not change during the item's lifespan. - -#### Values - -* `kSbUiNavItemTypeFocus` - - This is a single focusable item. -* `kSbUiNavItemTypeContainer` - - This is a container of navigation items which can also be containers - themselves or focusable items. Containers themselves cannot be focused. - -## Typedefs - -### SbUiNavItem - -An opaque handle to an implementation-private structure representing a -navigation item. - -#### Definition - -``` -typedef struct SbUiNavItemPrivate* SbUiNavItem -``` - -## Structs - -### SbUiNavCallbacks - -This structure specifies all the callbacks which the platform UI engine should -invoke for various interaction events on navigation items. These callbacks may -be invoked from any thread at any frequency. The `callback_context` is the value -that was passed on creation of the relevant SbUiNavItem. - -#### Members - -* `void(*onblur)(SbUiNavItem item, void *callback_context)` - - Invoke when an item has lost focus. This is only used with focus items. -* `void(*onfocus)(SbUiNavItem item, void *callback_context)` - - Invoke when an item has gained focus. This is only used with focus items. -* `void(*onscroll)(SbUiNavItem item, void *callback_context)` - - Invoke when an item's content offset is changed. This is only used with - container items. - -### SbUiNavInterface - -This structure declares the interface to the UI navigation implementation. All -function pointers must be specified if the platform supports UI navigation. - -#### Members - -* `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks - *callbacks, void *callback_context)` - - Create a new navigation item. When the user interacts with this item the - appropriate SbUiNavCallbacks function will be invoked with the provided - `callback_context`. An item is not interactable until it is enabled. -* `void(*destroy_item)(SbUiNavItem item)` - - Destroy the given navigation item. If this is a content of another item, - then it will first be unregistered. Additionally, if this item contains - other items, then those will be unregistered as well, but they will not be - automatically destroyed. -* `void(*set_focus)(SbUiNavItem item)` - - This is used to manually force focus on a navigation item of type - kSbUiNavItemTypeFocus. Any previously focused navigation item should receive - the blur event. If the item is not transitively a content of the root item, - then this does nothing. - - Specifying kSbUiNavItemInvalid should remove focus from the UI navigation - system. -* `void(*set_item_enabled)(SbUiNavItem item, bool enabled)` - - This is used to enable or disable user interaction with the specified - navigation item. All navigation items are disabled when created, and they - must be explicitly enabled to allow user interaction. If a container is - disabled, then all of its contents are not interactable even though they - remain enabled. If `enabled` is false, it must be guaranteed that once this - function returns, no callbacks associated with this item will be invoked - until the item is re-enabled. -* `void(*set_item_dir)(SbUiNavItem item, SbUiNavItemDir dir)` - - This specifies directionality for container items. Containers within - containers do not inherit directionality. Directionality must be specified - for each container explicitly. - - This should work even if `item` is disabled. -* `void(*set_item_focus_duration)(SbUiNavItem item, float seconds)` - - Set the minimum amount of time the focus item should remain focused once it - becomes focused. This may be used to make important focus items harder to - navigate over. Focus may still be moved before `seconds` has elapsed by - using the set_focus() function. By default, item focus duration is 0 - seconds. -* `void(*set_item_size)(SbUiNavItem item, float width, float height)` - - Set the interactable size of the specified navigation item. By default, an - item's size is (0,0). -* `void(*set_item_transform)(SbUiNavItem item, const SbUiNavMatrix2x3 - *transform)` - - Set the transform for the navigation item and its contents if the item is a - container. This specifies the placement of the item's center within its - container. The transform origin is the center of the item. Distance is - measured in pixels with the origin being the top-left of the item's - container. By default, an item's transform is identity. -* `bool(*get_item_focus_transform)(SbUiNavItem item, SbUiNavMatrix4 - *out_transform)` - - Retrieve the focus transform matrix for the navigation item. The UI engine - may translate, rotate, and/or tilt focus items to reflect user interaction. - This transform should be multiplied with the item's transform to get its - position inside its container. The transform origin is the center of the - item. Return false if the item position should not be changed (i.e. the - transform should be treated as identity). -* `bool(*get_item_focus_vector)(SbUiNavItem item, float *out_x, float *out_y)` - - Retrieve a vector representing the focus location within a focused item. - This is used to provide feedback about user input that is too small to - result in a focus change. If there is no focus vector for the navigation - item, then return false and leave `out_x` and `out_y` unchanged. Otherwise, - return true and set the output values in the range of [-1, +1] with (out_x, - out_y) of (-1, -1) being the top-left corner of the navigation item and (0, - 0) being the center. -* `void(*set_item_container_window)(SbUiNavItem item, SbWindow window)` - - This attaches the given navigation item (which must be a container) to the - specified window. Navigation items are only interactable if they are - transitively attached to a window. - - The native UI engine should never change this navigation item's content - offset. It is assumed to be used as a proxy for the system window. - - A navigation item may only have a SbUiNavItem or SbWindow as its direct - container. The navigation item hierarchy is established using - set_item_container_item() with the root container attached to a SbWindow - using set_item_container_window() to enable interaction with all enabled - items in the hierarchy. - - If `item` is already registered with a different window, then this will - unregister it from that window then attach it to the given `window`. It is - an error to register more than one navigation item with any given window. If - `window` is kSbWindowInvalid, then this will unregister the `item` from its - current window if any. Upon destruction of `item` or `window`, the `item` is - automatically unregistered from the `window`. -* `void(*set_item_container_item)(SbUiNavItem item, SbUiNavItem container)` - - A container navigation item may contain other navigation items. However, it - is an error to have circular containment or for `container` to not be of - type kSbUiNavItemTypeContainer. If `item` already has a different container, - then this first serves that connection. If `container` is - kSbUiNavItemInvalid, then this removes `item` from its current container. - Upon destruction of `item` or `container`, the `item` is automatically - removed from the `container`. - - The position of items within a container are specified relative to the - container's position. The position of these content items are further - modified by the container's "content offset". - - For example, consider item A with position (5,5) and content offset (0,0). - Given item B with position (10,10) is registered as a content of item A. - - 1) Item B should be drawn at position (15,15). - - 2) If item A's content offset is changed to (10,0), then item B should be - drawn at position (5,15). - - Essentially, content items should be drawn at: [container position] + - [content position] - [container content offset] - - Content items may overlap within a container. This can cause obscured items - to be unfocusable. The only rule that needs to be followed is that contents - which are focus items can obscure other contents which are containers, but - not vice versa. The caller must ensure that content focus items do not - overlap other content focus items and content container items do not overlap - other content container items. -* `void(*set_item_content_offset)(SbUiNavItem item, float content_offset_x, - float content_offset_y)` - - Set the current content offset for the given container. This may be used to - force scrolling to make certain content items visible. A container item's - content offset helps determine where its content items should be drawn. - Essentially, a content item should be drawn at: [container position] + - [content position] - [container content offset] If `item` is not a - container, then this does nothing. By default, the content offset is (0,0). - - This should update the values returned by get_item_content_offset() even if - the `item` is disabled. -* `void(*get_item_content_offset)(SbUiNavItem item, float - *out_content_offset_x, float *out_content_offset_y)` - - Retrieve the current content offset for the navigation item. If `item` is - not a container, then the content offset is (0,0). - - The native UI engine should not change the content offset of a container - unless one of its contents (possibly recursively) is focused. This is to - allow seamlessly disabling then re-enabling focus items without having their - containers change offsets. -* `void(*do_batch_update)(void(*update_function)(void *), void *context)` - - Call `update_function` with `context` to perform a series of UI navigation - changes atomically before returning. - -### SbUiNavItemDir - -Navigation items of type kSbUiNavItemTypeContainer have directionality. If -directionality is not specified for a container, it should default to left-to- -right and top-to-bottom. - -``` -/// For left-to-right, content offset x = 0 shows the leftmost content. -/// |<--Container Size-->| -/// +--------------------+--------------------+--------------------+ -/// | Not selectable. | Selectable. | Selectable. | -/// | Offscreen. | Onscreen. | Offscreen. | -/// | Negative position. | Positive position. | Positive position. | -/// +--------------------+--------------------+--------------------+ -/// ^ -/// Content Offset X = 0. -/// -/// For right-to-left, content offset x = 0 shows the rightmost content. -/// |<--Container Size-->| -/// +--------------------+--------------------+--------------------+ -/// | Selectable. | Selectable. | Not selectable. | -/// | Offscreen. | Onscreen. | Offscreen. | -/// | Negative position. | Positive position. | Positive position. | -/// +--------------------+--------------------+--------------------+ -/// ^ -/// Content Offset X = 0. -``` - -``` - Top-to-bottom is similar to left-to-right, but for the Y position. - Bottom-to-top is similar to right-to-left, but for the Y position. -``` - -#### Members - -* `bool is_left_to_right` -* `bool is_top_to_bottom` - -### SbUiNavMatrix2x3 - -This represents a 2x3 transform matrix in row-major order. - -``` -/// | a b tx | -/// | c d ty | -``` - -#### Members - -* `float m` - -### SbUiNavMatrix4 - -This represents a 4x4 transform matrix in row-major order. - -#### Members - -* `float m` - -## Functions - -### SbUiNavGetInterface - -Retrieve the platform's UI navigation implementation. If the platform does not -provide one, then return false without modifying `out_interface`. Otherwise, -initialize all members of `out_interface` and return true. The `out_interface` -pointer must not be NULL. - -#### Declaration - -``` -bool SbUiNavGetInterface(SbUiNavInterface *out_interface) -``` - -### SbUiNavItemIsValid - -Returns whether the given navigation item handle is valid. - -#### Declaration - -``` -static bool SbUiNavItemIsValid(SbUiNavItem item) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/13/user.md b/cobalt/site/docs/reference/starboard/modules/13/user.md deleted file mode 100644 index 309b939d066e0..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/13/user.md +++ /dev/null @@ -1,133 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `user.h` - -Defines a user management API. This module defines functions only for managing -signed-in users. Platforms that do not have users must still implement this API, -always reporting a single user that is current and signed in. - -These APIs are NOT expected to be thread-safe, so either call them from a single -thread, or perform proper synchronization around all calls. - -## Macros - -### kSbUserInvalid - -Well-defined value for an invalid user. - -## Enums - -### SbUserPropertyId - -A set of string properties that can be queried on a user. - -#### Values - -* `kSbUserPropertyAvatarUrl` - - The URL to the avatar for a user. Avatars are not provided on all platforms. -* `kSbUserPropertyHomeDirectory` - - The path to a user's home directory, if supported on this platform. -* `kSbUserPropertyUserName` - - The username of a user, which may be the same as the User ID, or it may be - friendlier. -* `kSbUserPropertyUserId` - - A unique user ID of a user. - -## Typedefs - -### SbUser - -A handle to a user. - -#### Definition - -``` -typedef SbUserPrivate* SbUser -``` - -## Functions - -### SbUserGetCurrent - -Gets the current primary user, if one exists. This is the user that is -determined, in a platform-specific way, to be the primary user controlling the -application. For example, the determination might be made because that user -launched the app, though it should be made using whatever criteria are -appropriate for the platform. - -It is expected that there will be a unique SbUser per signed-in user, and that -the referenced objects will persist for the lifetime of the app. - -#### Declaration - -``` -SbUser SbUserGetCurrent() -``` - -### SbUserGetProperty - -Retrieves the value of `property_id` for `user` and places it in `out_value`. -The function returns: - -* `true` if the property value is retrieved successfully - -* `false` if `user` is invalid; if `property_id` isn't recognized, supported, - or set for `user`; or if `value_size` is too small. - -`user`: The user for which property size data is being retrieved. `property_id`: -The property for which the data is requested. `out_value`: The retrieved -property value. `value_size`: The size of the retrieved property value. - -#### Declaration - -``` -bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) -``` - -### SbUserGetPropertySize - -Returns the size of the value of `property_id` for `user`, INCLUDING the -terminating null character. The function returns `0` if `user` is invalid or if -`property_id` is not recognized, supported, or set for the user. - -`user`: The user for which property size data is being retrieved. `property_id`: -The property for which the data is requested. - -#### Declaration - -``` -int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) -``` - -### SbUserGetSignedIn - -Gets a list of up to `users_size` signed-in users and places the results in -`out_users`. The return value identifies the actual number of signed-in users, -which may be greater or less than `users_size`. - -It is expected that there will be a unique `SbUser` per signed-in user and that -the referenced objects will persist for the lifetime of the app. - -`out_users`: Handles for the retrieved users. `users_size`: The maximum number -of signed-in users to retrieve. - -#### Declaration - -``` -int SbUserGetSignedIn(SbUser *out_users, int users_size) -``` - -### SbUserIsValid - -Returns whether the given user handle is valid. - -#### Declaration - -``` -static bool SbUserIsValid(SbUser user) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/14/accessibility.md b/cobalt/site/docs/reference/starboard/modules/14/accessibility.md index 5c66ba442803e..8f2a652445a9c 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/14/accessibility.md @@ -251,3 +251,4 @@ off (false). ``` bool SbAccessibilitySetCaptionsEnabled(bool enabled) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/atomic.md b/cobalt/site/docs/reference/starboard/modules/14/atomic.md index 0ed31cb649ec6..9653e53cecd31 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/14/atomic.md @@ -108,3 +108,4 @@ Overloaded functions for Atomic8. ``` static SbAtomic8 SbAtomicRelease_CompareAndSwap8(volatile SbAtomic8 *ptr, SbAtomic8 old_value, SbAtomic8 new_value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md b/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md index 9277c70837b06..3cb7a82958056 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md @@ -212,3 +212,4 @@ Indicates whether the given audio sink handle is valid. ``` bool SbAudioSinkIsValid(SbAudioSink audio_sink) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md index 72dc9327ed1e3..4b2cab30de3d3 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md @@ -73,3 +73,4 @@ value for which the byte order will be swapped. ``` uint64_t SbByteSwapU64(uint64_t value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md index 2d8f30b5fdce2..cd381c5e3f9eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md @@ -40,7 +40,7 @@ size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbConditionVariable SbConditionVariable +typedef union SbConditionVariable SbConditionVariable ``` ## Functions @@ -129,12 +129,13 @@ Waits for `condition`, releasing the held lock `mutex`, blocking up to if `mutex` is not held. `timeout_duration`: The maximum amount of time that function should wait for -`condition`. If the `timeout_duration` value is less than or equal to zero, the -function returns as quickly as possible with a kSbConditionVariableTimedOut -result. +`condition`, in microseconds. If the `timeout_duration` value is less than or +equal to zero, the function returns as quickly as possible with a +kSbConditionVariableTimedOut result. #### Declaration ``` -SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime timeout_duration) +SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, int64_t timeout_duration) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/configuration.md b/cobalt/site/docs/reference/starboard/modules/14/configuration.md index d0ba3c7196f89..fa3e15a4e1603 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/14/configuration.md @@ -53,12 +53,6 @@ will trigger a compiler warning when referenced. SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION - -The API version that is currently open for changes, and therefore is not stable -or frozen. Production-oriented ports should avoid declaring that they implement -the experimental Starboard API version. - ### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for @@ -71,14 +65,10 @@ header available. ### SB_HAS_64_BIT_ATOMICS -Whether the current platform has 64-bit atomic operations. - -### SB_HAS_GLES2 - -Specifies whether this platform has a performant OpenGL ES 2 implementation, -which allows client applications to use GL rendering paths. Derived from the gyp -variable `gl_type` gl_type which indicates what kind of GL implementation is -available. +SB_C_FORCE_INLINE annotation for forcing a C function to be inlined. +SB_EXPORT_PLATFORM annotates symbols as exported from shared libraries. +SB_IMPORT_PLATFORM annotates symbols as imported from shared libraries. Whether +the current platform has 64-bit atomic operations. ### SB_HAS_QUIRK(SB_FEATURE) @@ -99,7 +89,7 @@ Macro for hinting that an expression is likely to be true. ### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, -inclusive. +inclusive. The API version is not stable and is open for changes. ### SB_MINIMUM_API_VERSION @@ -111,11 +101,6 @@ inclusive. Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE - -Declares a function as overriding a virtual function on compilers that support -it. - ### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. @@ -136,7 +121,7 @@ base/compiler_specific.h) Include the platform-specific configuration. This macro is set by GN in starboard/build/config/BUILD.gn and passed in on the command line for all -targets and all configurations.Makes a pointer-typed parameter restricted so +targets and all configurations. Makes a pointer-typed parameter restricted so that the compiler can make certain optimizations because it knows the pointers are unique. diff --git a/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md index e2aa35f2bb1a2..e6e85437eb54e 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md @@ -98,7 +98,7 @@ Book: /youtube/cobalt/_book.yaml SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags + ##### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -259,3 +259,4 @@ fields in `features` are invalid. ``` bool SbCPUFeaturesGet(SbCPUFeatures *features) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/decode_target.md b/cobalt/site/docs/reference/starboard/modules/14/decode_target.md index 1e98db5db54d8..c8d38a28a294b 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/14/decode_target.md @@ -12,7 +12,7 @@ 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 +* 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 @@ -21,7 +21,7 @@ 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. -## 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 @@ -33,51 +33,7 @@ to run arbitrary code on the application's renderer thread 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(). -The primary usage is likely to be the the SbPlayer implementation on some -platforms. - -## SbDecodeTarget Example - -Let's say that we are an application and we would like to use the interface -defined in starboard/image.h to decode an imaginary "image/foo" image type. - -First, the application 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 (SbImageIsDecodeSupported("image/foo", kPreferredFormats[i])) { - format = kPreferredFormats[i]; - break; - } -} - -``` - -Now that the application 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 = SbImageDecode( - context_provider, encoded_foo_data, encoded_foo_data_size, - "image/foo", format); - -// If the decode works, you can get the texture out and render it. -SbDecodeTargetInfo info; -memset(&info, 0, sizeof(info)); -SbDecodeTargetGetInfo(target, &info); -GLuint texture = - info.planes[kSbDecodeTargetPlaneRGBA].texture; -``` +The primary usage is likely to be the SbPlayer implementation on some platforms. ## Macros @@ -127,9 +83,9 @@ premultiplied unless otherwise explicitly specified. 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 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 format with GL - platforms, it is expected that the underlying texture will be set to the + 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). Content region left/right should be specified in u/v width resolution. @@ -207,8 +163,7 @@ information about the graphics context that will be used to render SbDecodeTargets. Some Starboard implementations may need to have references to some graphics objects when creating/destroying resources used by SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects should be provided -to all Starboard functions that might create SbDecodeTargets (e.g. -SbImageDecode()). +to all Starboard functions that might create SbDecodeTargets. #### Members @@ -216,12 +171,12 @@ SbImageDecode()). 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. + `void*` in order to avoid including the EGL header files here. * `void * egl_context` 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. + including the EGL header files here. * `SbDecodeTargetGlesContextRunner gles_context_runner` The `gles_context_runner` function pointer is passed in from the application @@ -264,7 +219,7 @@ This can be queried via calls to SbDecodeTargetGetInfo(). * `SbDecodeTargetInfoPlane planes` The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY, - kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode + kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this decode target. ### SbDecodeTargetInfoContentRegion @@ -368,8 +323,7 @@ static bool SbDecodeTargetIsValid(SbDecodeTarget handle) 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. In the case where SB_HAS(GLES2), this function must be called -on a thread with the context +reference count. This function must be called on a thread with the context. #### Declaration @@ -400,3 +354,4 @@ Starboard implementations, if it is necessary. ``` static void SbDecodeTargetRunInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTargetGlesContextRunnerTarget target, void *target_context) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/directory.md b/cobalt/site/docs/reference/starboard/modules/14/directory.md index 6f845f6567a9c..1c0f904821191 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/14/directory.md @@ -115,3 +115,4 @@ that the directory could not be opened. ``` SbDirectory SbDirectoryOpen(const char *path, SbFileError *out_error) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/drm.md b/cobalt/site/docs/reference/starboard/modules/14/drm.md index f42e43bf3db71..47cf7ef55b8a8 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/14/drm.md @@ -29,7 +29,7 @@ Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. ### SbDrmKeyStatus -Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) +Status of a particular media key. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus) #### Values @@ -67,8 +67,9 @@ The status of session related operations. Used by * `kSbDrmStatusQuotaExceededError` * `kSbDrmStatusUnknownError` - 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. ## Typedefs @@ -85,7 +86,7 @@ typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void ### SbDrmSessionClosedFunc -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. #### Definition @@ -96,8 +97,15 @@ typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, c ### SbDrmSessionKeyStatusesChangedFunc 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. #### Definition @@ -119,6 +127,7 @@ context that was passed into the call to SbDrmCreateSystem(). `error_message` may contain an optional error message when `status` isn't `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. @@ -246,6 +255,50 @@ Clear any internal states/resources related to the specified `session_id`. void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` +### SbDrmCreateSystem + +Creates a new DRM system that can be used when constructing an SbPlayer or an +SbDecoder. + +This function returns `kSbDrmSystemInvalid` if `key_system` is unsupported. + +Also see the documentation of SbDrmGenerateSessionUpdateRequest() and +SbDrmUpdateSession() for more details. + +`key_system`: The DRM key system to be created. The value should be in the 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. Note the key +system will be matched case sensitive. For more details, refer to [https://w3c.github.io/encrypted-media/#dfn-key-system-s](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 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. + +#### Declaration + +``` +SbDrmSystem SbDrmCreateSystem(const char *key_system, void *context, SbDrmSessionUpdateRequestFunc update_request_callback, SbDrmSessionUpdatedFunc session_updated_callback, SbDrmSessionKeyStatusesChangedFunc key_statuses_changed_callback, SbDrmServerCertificateUpdatedFunc server_certificate_updated_callback, SbDrmSessionClosedFunc session_closed_callback) +``` + ### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and @@ -292,9 +345,12 @@ establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used. `type`: The case-sensitive type of the session update request payload. Must not -be NULL. `initialization_data`: The data for which the session update request -payload is created. Must not be NULL. `initialization_data_size`: The size of -the session update request payload. +be NULL. + +`initialization_data`: The data for which the session update request payload is +created. Must not be NULL. + +`initialization_data_size`: The size of the session update request payload. #### Declaration @@ -375,14 +431,18 @@ 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`. `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. `certificate`: Pointer to the server -certificate data. Must not be NULL. `certificate_size`: Size of the server -certificate data. +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. + +`certificate`: Pointer to the server certificate data. Must not be NULL. + +`certificate_size`: Size of the server certificate data. #### Declaration @@ -415,3 +475,4 @@ must not be NULL. ``` void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/egl.md b/cobalt/site/docs/reference/starboard/modules/14/egl.md index 4afff1aa236ef..87deff271ad91 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/14/egl.md @@ -144,3 +144,4 @@ typedef int32_t SbEglInt32 config, void *native_pixmap, const SbEglAttrib *attrib_list)` * `SbEglBoolean(*eglWaitSync)(SbEglDisplay dpy, SbEglSync sync, SbEglInt32 flags)` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/event.md b/cobalt/site/docs/reference/starboard/modules/14/event.md index 256d418b45e00..de083ffc544e1 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/event.md +++ b/cobalt/site/docs/reference/starboard/modules/14/event.md @@ -313,7 +313,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -399,5 +399,6 @@ of microseconds to wait before calling the `callback` function. Set `delay` to #### Declaration ``` -SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) +SbEventId SbEventSchedule(SbEventCallback callback, void *context, int64_t delay) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/file.md b/cobalt/site/docs/reference/starboard/modules/14/file.md index 103af475ace1b..fd9b4fbf5c216 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/file.md +++ b/cobalt/site/docs/reference/starboard/modules/14/file.md @@ -124,15 +124,15 @@ Used to hold information about a file. * `bool is_symbolic_link` Whether the file corresponds to a symbolic link. -* `SbTime last_modified` +* `int64_t last_modified` - The last modified time of a file. -* `SbTime last_accessed` + The last modified time of a file - microseconds since Windows epoch UTC. +* `int64_t last_accessed` - The last accessed time of a file. -* `SbTime creation_time` + The last accessed time of a file - microseconds since Windows epoch UTC. +* `int64_t creation_time` - The creation time of a file. + The creation time of a file - microseconds since Windows epoch UTC. ## Functions @@ -402,3 +402,4 @@ The return value identifies the number of bytes written, or `-1` on error. ``` static int SbFileWriteAll(SbFile file, const char *data, int size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/gles.md b/cobalt/site/docs/reference/starboard/modules/14/gles.md index 77bc07e71c82d..049838f80b659 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/14/gles.md @@ -459,3 +459,4 @@ typedef long int SbGlIntPtr internalformat, SbGlSizei width, SbGlSizei height, SbGlSizei depth)` * `void(*glGetInternalformativ)(SbGlEnum target, SbGlEnum internalformat, SbGlEnum pname, SbGlSizei bufSize, SbGlInt32 *params)` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/image.md b/cobalt/site/docs/reference/starboard/modules/14/image.md index 945938a099033..2cb9a716d194b 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/image.md +++ b/cobalt/site/docs/reference/starboard/modules/14/image.md @@ -26,6 +26,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +76,4 @@ indefinitely. ``` bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/input.md b/cobalt/site/docs/reference/starboard/modules/14/input.md index a858c73e3e898..d2dd2db32dc58 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/input.md +++ b/cobalt/site/docs/reference/starboard/modules/14/input.md @@ -168,3 +168,4 @@ A 2-dimensional vector used to represent points and motion vectors. * `float x` * `float y` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/key.md b/cobalt/site/docs/reference/starboard/modules/14/key.md index dd7712fd81bbb..853f820a65ad5 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/key.md +++ b/cobalt/site/docs/reference/starboard/modules/14/key.md @@ -290,3 +290,4 @@ Bit-mask of key modifiers. * `kSbKeyModifiersPointerButtonMiddle` * `kSbKeyModifiersPointerButtonBack` * `kSbKeyModifiersPointerButtonForward` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/log.md b/cobalt/site/docs/reference/starboard/modules/14/log.md index 6cf3a491a2a75..60b361d4697d2 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/log.md +++ b/cobalt/site/docs/reference/starboard/modules/14/log.md @@ -134,3 +134,4 @@ Inline wrapper of SbLogFormat to convert from ellipsis to va_args. ``` void static void static void SbLogRawFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/media.md b/cobalt/site/docs/reference/starboard/modules/14/media.md index 7328686079391..3b868b7121941 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/media.md +++ b/cobalt/site/docs/reference/starboard/modules/14/media.md @@ -180,7 +180,7 @@ output. The type of audio connector. Will be the empty `kSbMediaAudioConnectorNone` if this device cannot provide this information. -* `SbTime latency` +* `int64_t latency` The expected latency of audio over this output, in microseconds, or `0` if this device cannot provide this information. @@ -236,14 +236,13 @@ Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at The size, in bytes, of the audio_specific_config. * `const void * audio_specific_config` - 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](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. ### SbMediaColorMetadata 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](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) +luminosity than is possible with standard digital imaging. #### Members @@ -433,10 +432,12 @@ Note that neither `mime` nor `key_system` can be NULL. This function returns `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. `key_system`: A lowercase value in the form -of "com.example.somesystem" as suggested by [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system)) that can +than one codec, delimited by comma. + +`key_system`: A lowercase value in the form of "com.example.somesystem", and 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. +For more detail, refer to [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system) An implementation may choose to support `key_system` with extra attributes, separated by ';', like `com.example.somesystem; attribute_name1="value1"; @@ -448,23 +449,21 @@ 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` 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` encryptionScheme of -MediaKeySystemMediaCapability, as defined in [https://wicg.github.io/encrypted-media-encryption-scheme/,](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` kSbMediaSupportTypeNotSupported when +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. It 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` 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` kSbMediaSupportTypeProbably when +`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` 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. +`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. For more detail, refer to [https://wicg.github.io/encrypted-media-encryption-scheme](https://wicg.github.io/encrypted-media-encryption-scheme) #### Declaration @@ -534,7 +533,7 @@ When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can return 0, in which case the media stack will allocate extra memory on demand. When SbMediaGetInitialBufferCapacity and this function both return 0, the media -stack will allocate individual buffers directly using SbMemory functions. +stack will allocate individual buffers directly using malloc functions. #### Declaration @@ -544,19 +543,19 @@ int SbMediaGetBufferAllocationUnit() ### SbMediaGetBufferGarbageCollectionDurationThreshold -Specifies the duration threshold of media source garbage collection. When the -accumulated duration in a source buffer exceeds this value, the media source -implementation will try to eject existing buffers from the cache. This is -usually triggered when the video being played has a simple content and the -encoded data is small. In such case this can limit how much is allocated for the -book keeping data of the media buffers and avoid OOM of system heap. This should -return 170 seconds for most of the platforms. But it can be further reduced on -systems with extremely low memory. +Specifies the duration threshold of media source garbage collection in +microseconds. When the accumulated duration in a source buffer exceeds this +value, the media source implementation will try to eject existing buffers from +the cache. This is usually triggered when the video being played has a simple +content and the encoded data is small. In such case this can limit how much is +allocated for the book keeping data of the media buffers and avoid OOM of system +heap. This should return 170 seconds for most of the platforms. But it can be +further reduced on systems with extremely low memory. #### Declaration ``` -SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() +int64_t SbMediaGetBufferGarbageCollectionDurationThreshold() ``` ### SbMediaGetBufferPadding @@ -575,10 +574,10 @@ int SbMediaGetBufferPadding() Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored -in main memory allocated by SbMemory functions. For file storage, the media +in main memory allocated by malloc functions. For file storage, the media buffers will be stored in a temporary file in the system cache folder acquired by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when -its value is "file" the media stack will still allocate memory to cache the the +its value is "file" the media stack will still allocate memory to cache the buffers in use. #### Declaration @@ -610,10 +609,14 @@ allocation of media buffers may only fail when there is not enough memory in the system to fulfill the request, under which case the 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. +`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. #### Declaration @@ -628,10 +631,14 @@ resolution of such videos shouldn't go beyond 1080p. Its value should be less than the sum of SbMediaGetAudioBufferBudget and '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. +`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. #### Declaration @@ -647,10 +654,14 @@ being used by video buffers but will also make app less likely to re-download video data. Note that the app may experience significant difficulty if this 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. +`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. #### Declaration @@ -678,7 +689,7 @@ bool SbMediaIsBufferPoolAllocateOnDemand() ### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer -pools should be allocated on demand, as opposed to using SbMemory* functions. +pools should be allocated on demand, as opposed to using malloc functions. #### Declaration @@ -691,15 +702,16 @@ bool SbMediaIsBufferUsingMemoryPool() Communicate to the platform how far past `current_playback_position` the app will write audio samples. The app will write all samples between `current_playback_position` and `current_playback_position` + `duration`, as -soon as they are available. The app may sometimes write more samples than that, -but the app only guarantees to write `duration` past `current_playback_position` -in general. The platform is responsible for guaranteeing that when only -`duration` audio samples are written at a time, no playback issues occur (such -as transient or indefinite hanging). The platform may assume `duration` >= 0.5 -seconds. +soon as they are available (during is in microseconds). The app may sometimes +write more samples than that, but the app only guarantees to write `duration` +past `current_playback_position` in general. The platform is responsible for +guaranteeing that when only `duration` audio samples are written at a time, no +playback issues occur (such as transient or indefinite hanging). The platform +may assume `duration` >= 0.5 seconds. #### Declaration ``` -void SbMediaSetAudioWriteDuration(SbTime duration) +void SbMediaSetAudioWriteDuration(int64_t duration) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/memory.md b/cobalt/site/docs/reference/starboard/modules/14/memory.md index 0c404e36ea30c..670dc588651f0 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/14/memory.md @@ -30,8 +30,9 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. ### SbMemoryMapFlags -The bitwise OR of these flags should be passed to SbMemoryMap to indicate how -the mapped memory can be used. +TODO: Remove the definition once the memory_mapped_file.h extension is +deprecated. The bitwise OR of these flags should be passed to SbMemoryMap to +indicate how the mapped memory can be used. #### Values @@ -343,3 +344,4 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns ``` bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md index 505d2a7d03471..fa78eaa52c6fe 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md +++ b/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md @@ -104,3 +104,4 @@ SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); ``` bool SbMemorySetReporter(struct SbMemoryReporter *tracker) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/microphone.md b/cobalt/site/docs/reference/starboard/modules/14/microphone.md index bcf9e4355e65c..497cbe91cec43 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/14/microphone.md @@ -260,3 +260,4 @@ has already been read from the device is discarded. ``` int SbMicrophoneRead(SbMicrophone microphone, void *out_audio_data, int audio_data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/mutex.md b/cobalt/site/docs/reference/starboard/modules/14/mutex.md index 82ff8500ab8d8..37e2ce06bab4b 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/14/mutex.md @@ -40,7 +40,7 @@ SB_MUTEX_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbMutex SbMutex +typedef union SbMutex SbMutex ``` ## Functions @@ -125,3 +125,4 @@ held by the current thread. ``` bool SbMutexRelease(SbMutex *mutex) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/once.md b/cobalt/site/docs/reference/starboard/modules/14/once.md index d77302467f8b0..de4867461edc4 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/once.md +++ b/cobalt/site/docs/reference/starboard/modules/14/once.md @@ -22,7 +22,7 @@ SB_ONCE_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbOnceControl SbOnceControl +typedef union SbOnceControl SbOnceControl ``` ### SbOnceInitRoutine @@ -55,3 +55,4 @@ Thread-safely runs `init_routine` only once. ``` bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/player.md b/cobalt/site/docs/reference/starboard/modules/14/player.md index 0dab908addc8d..025d42e702777 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/player.md +++ b/cobalt/site/docs/reference/starboard/modules/14/player.md @@ -44,9 +44,12 @@ data may come from multiple sources. * `kMatroskaBlockAdditional` The side data comes from the BlockAdditional data in the Matroska/Webm - container, as specified in [https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39](https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39)9) andnd [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional)l) - . The first 8 bytes of the data contains the value of BlockAddID in big - endian format, followed by the content of BlockAdditional. + container. The first 8 bytes of the data contains the value of BlockAddID in + big endian format, followed by the content of BlockAdditional. See: + + [https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03](https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03) + + [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional) ### SbPlayerState @@ -122,10 +125,13 @@ typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMed ### SbPlayerErrorFunc -Callback for player errors, that may set a `message`. `error`: indicates the -error code. `message`: provides specific informative diagnostic message about -the error condition encountered. It is ok for the message to be an empty string -or NULL if no information is available. +Callback for player errors, that may set a `message`. + +`error`: indicates the error code. + +`message`: provides specific informative diagnostic message about the error +condition encountered. It is ok for the message to be an empty string or NULL if +no information is available. #### Definition @@ -184,14 +190,14 @@ Information about the current media playback state. #### Members -* `SbTime current_media_timestamp` +* `int64_t current_media_timestamp` The position of the playback head, as precisely as possible, in microseconds. -* `SbTime duration` +* `int64_t duration` The known duration of the currently playing media stream, in microseconds. -* `SbTime start_date` +* `int64_t start_date` The result of getStartDate for the currently playing media stream, in microseconds since the epoch of January 1, 1601 UTC. @@ -242,9 +248,9 @@ Information about the samples to be written into SbPlayerWriteSamples(). * `int buffer_size` Size of the data pointed to by `buffer`. -* `SbTime timestamp` +* `int64_t timestamp` - The timestamp of the sample in SbTime. + The timestamp of the sample in microseconds since Windows epoch UTC. * `SbPlayerSampleSideData* side_data` Points to an array of side data for the input, when available. @@ -284,20 +290,123 @@ coming from multiple sources. ## Functions +### SbPlayerCreate + +Creates a player that will be displayed on `window` for the specified +`video_codec` and `audio_codec`, acquiring all resources needed to operate it, +and returning an opaque handle to it. The expectation is that a new player will +be created and destroyed for every playback. + +This function returns the created player. Note the following: + +* The associated decoder of the returned player should be assumed to not be in + `kSbPlayerDecoderStateNeedsData` until SbPlayerSeek() has been called on it. + +* It is expected either that the thread that calls SbPlayerCreate is the same + thread that calls the other `SbPlayer` functions for that player, or that + there is a mutex guarding calls into each `SbPlayer` instance. + +* If there is a platform limitation on how many players can coexist + simultaneously, then calls made to this function that attempt to exceed that + limit must return `kSbPlayerInvalid`. Multiple calls to SbPlayerCreate must + not cause a crash. + +`window`: The window that will display the player. `window` can be +`kSbWindowInvalid` for platforms where video is only displayed on a particular +window that the underlying implementation already has access to. + +`video_codec`: The video codec used for the player. If `video_codec` is +`kSbMediaVideoCodecNone`, the player is an audio-only player. If `video_codec` +is any other value, the player is an audio/video decoder. This can be set to +`kSbMediaVideoCodecNone` to play a video with only an audio track. + +`audio_codec`: The audio codec used for the player. The caller must provide a +populated `audio_sample_info` if audio codec is `kSbMediaAudioCodecAac`. Can be +set to `kSbMediaAudioCodecNone` to play a video without any audio track. In such +case `audio_sample_info` must be NULL. + +`drm_system`: If the media stream has encrypted portions, then this parameter +provides an appropriate DRM system, created with `SbDrmCreateSystem()`. If the +stream does not have encrypted portions, then `drm_system` may be +`kSbDrmSystemInvalid`. + +`audio_sample_info`: Note that the caller must provide a populated +`audio_sample_info` if the audio codec is `kSbMediaAudioCodecAac`. Otherwise, +`audio_sample_info` can be NULL. See media.h for the format of the +`SbMediaAudioSampleInfo` struct. + +Note that `audio_specific_config` is a pointer and the content it points to is +no longer valid after this function returns. The implementation has to make a +copy of the content if it is needed after the function returns. + +`max_video_capabilities`: This string communicates the max video capabilities +required to the platform. The web app will not provide a video stream exceeding +the maximums described by this parameter. Allows the platform to optimize +playback pipeline for low quality video streams if it knows that it will never +adapt to higher quality streams. The string uses the same format as the string +passed in to SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to +"width=1920; height=1080; framerate=15;", the video will never adapt to +resolution higher than 1920x1080 or frame per second higher than 15 fps. When +the maximums are unknown, this will be set to NULL. + +`sample_deallocator_func`: If not `NULL`, the player calls this function on an +internal thread to free the sample buffers passed into SbPlayerWriteSample(). + +`decoder_status_func`: If not `NULL`, the decoder calls this function on an +internal thread to provide an update on the decoder's status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_status_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the playback status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_error_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the error status. This callback is +responsible for setting the media error message. + +`context`: This is passed to all callbacks and is generally used to point at a +class or struct that contains state associated with the player. + +`output_mode`: Selects how the decoded video frames will be output. For example, +kSbPlayerOutputModePunchOut indicates that the decoded video frames will be +output to a background video layer by the platform, and +kSbPlayerOutputDecodeToTexture indicates that the decoded video frames should be +made available for the application to pull via calls to +SbPlayerGetCurrentFrame(). + +`provider`: Only present in Starboard version 3 and up. If not `NULL`, then when +output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY use the +provider to create SbDecodeTargets on the renderer thread. A provider may not +always be needed by the player, but if it is needed, and the provider is not +given, the player will fail by returning `kSbPlayerInvalid`. + +If `NULL` is passed to any of the callbacks (`sample_deallocator_func`, +`decoder_status_func`, `player_status_func`, or `player_error_func` if it +applies), then `kSbPlayerInvalid` must be returned. + +#### Declaration + +``` +SbPlayer SbPlayerCreate(SbWindow window, const SbPlayerCreationParam *creation_param, SbPlayerDeallocateSampleFunc sample_deallocate_func, SbPlayerDecoderStatusFunc decoder_status_func, SbPlayerStatusFunc player_status_func, SbPlayerErrorFunc player_error_func, void *context, SbDecodeTargetGraphicsContextProvider *context_provider) +``` + ### SbPlayerDestroy Destroys `player`, freeing all associated resources. * Upon calling this method, there should be one call to the player status callback (i.e. `player_status_func` used in the creation of the player) - which indicates the player is destroyed. Note, the callback has to be in- - flight when SbPlayerDestroyed is called. + which indicates the player is destroyed. Note, the callback has to be + inflight when SbPlayerDestroyed is called. * No more other callbacks should be issued after this function returns. * It is not allowed to pass `player` into any other `SbPlayer` function once - SbPlayerDestroy has been called on that player. `player`: The player to be - destroyed. Must not be `kSbPlayerInvalid`. + SbPlayerDestroy has been called on that player. + +`player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. #### Declaration @@ -323,19 +432,36 @@ kSbDecodeTargetInvalid is returned. SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` +### SbPlayerGetInfo2 + +Gets a snapshot of the current player state and writes it to `out_player_info`. +This function may be called very frequently and is expected to be inexpensive. + +`player`: The player about which information is being retrieved. Must not be +`kSbPlayerInvalid`. + +`out_player_info`: The information retrieved for the player. + +#### Declaration + +``` +void SbPlayerGetInfo2(SbPlayer player, SbPlayerInfo2 *out_player_info2) +``` + ### SbPlayerGetMaximumNumberOfSamplesPerWrite -Writes a single sample of the given media type to `player`'s input stream. Its -data may be passed in via more than one buffers. The lifetime of -`sample_buffers`, `sample_buffer_sizes`, `video_sample_info`, and -`sample_drm_info` (as well as member `subsample_mapping` contained inside it) -are not guaranteed past the call to SbPlayerWriteSample. That means that before -returning, the implementation must synchronously copy any information it wants -to retain from those structures. +Returns the maximum number of samples that can be written in a single call to +SbPlayerWriteSamples(). Returning a value greater than one can improve +performance by allowing SbPlayerWriteSamples() to write multiple samples in one +call. -`player`: The player for which the number is retrieved. `sample_type`: The type -of sample for which the number is retrieved. See the `SbMediaType` enum in -media.h. +Note that this feature is currently disabled in Cobalt where +SbPlayerWriteSamples() will always be called with one sample. + +`player`: The player for which the number is retrieved. + +`sample_type`: The type of sample for which the number is retrieved. See the +`SbMediaType` enum in media.h. #### Declaration @@ -377,6 +503,45 @@ Returns whether the given player handle is valid. static bool SbPlayerIsValid(SbPlayer player) ``` +### SbPlayerSeek2 + +Tells the player to freeze playback (if playback has already started), reset or +flush the decoder pipeline, and go back to the Prerolling state. The player +should restart playback once it can display the frame at `seek_to_timestamp`, or +the closest it can get. (Some players can only seek to I-Frames, for example.) + +* Seek must be called before samples are sent when starting playback for the + first time, or the client never receives the + `kSbPlayerDecoderStateNeedsData` signal. + +* A call to seek may interrupt another seek. + +* After this function is called, the client should not send any more audio or + video samples until `SbPlayerDecoderStatusFunc` is called back with + `kSbPlayerDecoderStateNeedsData` for each required media type. + `SbPlayerDecoderStatusFunc` is the `decoder_status_func` callback function + that was specified when the player was created (SbPlayerCreate). + +`player`: The SbPlayer in which the seek operation is being performed. Must not +be `kSbPlayerInvalid`. + +`seek_to_timestamp`: The frame at which playback should begin. + +`ticket`: A user-supplied unique ID to be passed to all subsequent +`SbPlayerDecoderStatusFunc` calls. (That is the `decoder_status_func` callback +function specified when calling SbPlayerCreate.) + +The `ticket` value is used to filter calls that may have been in flight when +SbPlayerSeek was called. To be very specific, once SbPlayerSeek has been called +with ticket X, a client should ignore all `SbPlayerDecoderStatusFunc` calls that +do not pass in ticket X. + +#### Declaration + +``` +void SbPlayerSeek2(SbPlayer player, int64_t seek_to_timestamp, int ticket) +``` + ### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do @@ -392,11 +557,18 @@ implementors should take care to avoid related performance concerns with such frequent calls. `player`: The player that is being resized. Must not be `kSbPlayerInvalid`. + `z_index`: The z-index of the player. When the bounds of multiple players are overlapped, the one with larger z-index will be rendered on top of the ones with -smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. -`y`: The y-coordinate of the upper-left corner of the player. `width`: The width -of the player, in pixels. `height`: The height of the player, in pixels. +smaller z-index. + +`x`: The x-coordinate of the upper-left corner of the player. + +`y`: The y-coordinate of the upper-left corner of the player. + +`width`: The width of the player, in pixels. + +`height`: The height of the player, in pixels. #### Declaration @@ -430,9 +602,11 @@ bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) Sets the player's volume. `player`: The player in which the volume is being adjusted. Must not be -`kSbPlayerInvalid`. `volume`: The new player volume. The value must be between -`0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be -muted, and a value of `1.0` means that it should be played at full volume. +`kSbPlayerInvalid`. + +`volume`: The new player volume. The value must be between `0.0` and `1.0`, +inclusive. A value of `0.0` means that the audio should be muted, and a value of +`1.0` means that it should be played at full volume. #### Declaration @@ -447,8 +621,9 @@ there are no more samples for that media type for the remainder of this media stream. This marker is invalidated, along with the rest of the stream's contents, after a call to SbPlayerSeek. -`player`: The player to which the marker is written. `stream_type`: The type of -stream for which the marker is written. +`player`: The player to which the marker is written. + +`stream_type`: The type of stream for which the marker is written. #### Declaration @@ -458,14 +633,29 @@ void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ### SbPlayerWriteSample2 +Writes samples of the given media type to `player`'s input stream. The lifetime +of `sample_infos`, and the members of its elements like `buffer`, +`video_sample_info`, and `drm_info` (as well as member `subsample_mapping` +contained inside it) are not guaranteed past the call to SbPlayerWriteSamples(). +That means that before returning, the implementation must synchronously copy any +information it wants to retain from those structures. + +SbPlayerWriteSamples() allows writing of multiple samples in one call. + +`player`: The player to which the sample is written. Must not be +`kSbPlayerInvalid`. + `sample_type`: The type of sample being written. See the `SbMediaType` enum in -media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with +media.h. + +`sample_infos`: A pointer to an array of SbPlayerSampleInfo with `number_of_sample_infos` elements, each holds the data for an sample, i.e. a sequence of whole NAL Units for video, or a complete audio frame. `sample_infos` cannot be assumed to live past the call into SbPlayerWriteSamples(), so it must be copied if its content will be used after SbPlayerWriteSamples() returns. + `number_of_sample_infos`: Specify the number of samples contained inside -`sample_infos`. It has to be at least one, and less than the return value of +`sample_infos`. It has to be at least one, and at most the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). #### Declaration @@ -473,3 +663,4 @@ SbPlayerGetMaximumNumberOfSamplesPerWrite(). ``` void SbPlayerWriteSample2(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/socket.md b/cobalt/site/docs/reference/starboard/modules/14/socket.md index 744c04e3847d2..e7f4bc9e71563 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/14/socket.md @@ -540,15 +540,15 @@ Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: If set to `true`, -then `period` specifies the minimum time (SbTime) is always in microseconds) -between keep-alive packets. If set to `false`, `period` is ignored. `period`: -The time between keep-alive packets. This value is only relevant if `value` is -`true`. +then `period` specifies the minimum time in microseconds between keep-alive +packets. If set to `false`, `period` is ignored. `period`: The time in +microseconds between keep-alive packets. This value is only relevant if `value` +is `true`. #### Declaration ``` -bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) +bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, int64_t period) ``` ### SbSocketSetTcpNoDelay @@ -583,3 +583,4 @@ option. ``` bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md b/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md index f1c6bd8b9f2fa..54bc7eae0645f 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md @@ -202,15 +202,15 @@ SbSocketWaiterWakeUp() it not called by that time. The return value indicates the reason that the socket waiter exited. This function should only be called on the thread that waits on this waiter. -`duration`: The minimum amount of time after which the socket waiter should exit -if it is not woken up before then. As with SbThreadSleep() (see thread.h), this -function may wait longer than `duration`, such as if the timeout expires while a -callback is being fired. +`duration`: The minimum amount of time in microseconds after which the socket +waiter should exit if it is not woken up before then. As with SbThreadSleep() +(see thread.h), this function may wait longer than `duration`, such as if the +timeout expires while a callback is being fired. #### Declaration ``` -SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) +SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, int64_t duration) ``` ### SbSocketWaiterWakeUp @@ -235,3 +235,4 @@ next 7 times they are called. ``` void SbSocketWaiterWakeUp(SbSocketWaiter waiter) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md b/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md index 0bd6e65b63790..ea4ad46b3f87d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md @@ -49,3 +49,4 @@ when the previous utterances are complete. ``` void SbSpeechSynthesisSpeak(const char *text) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/storage.md b/cobalt/site/docs/reference/starboard/modules/14/storage.md index f20016113be16..0311c62bf10a0 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/14/storage.md @@ -156,3 +156,4 @@ after a short time, even if there is an unexpected process termination before ``` bool SbStorageWriteRecord(SbStorageRecord record, const char *data, int64_t data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/string.md b/cobalt/site/docs/reference/starboard/modules/14/string.md index 3fed809df4618..bd04c99c94192 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/string.md +++ b/cobalt/site/docs/reference/starboard/modules/14/string.md @@ -127,21 +127,6 @@ be formatted. `arguments`: Variable arguments used in the string. int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF - -An inline wrapper of SbStringFormatWide that converts from ellipsis to -`va_args`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) -``` - ### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The @@ -172,3 +157,4 @@ Values matching `pattern` that were extracted from `buffer`. ``` static int SbStringScanF(const char *buffer, const char *pattern,...) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/system.md b/cobalt/site/docs/reference/starboard/modules/14/system.md index 59e70188e05ac..6b8c7a6abcc4d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/system.md +++ b/cobalt/site/docs/reference/starboard/modules/14/system.md @@ -713,3 +713,4 @@ signal-safe on platforms that support signals. ``` bool SbSystemSymbolize(const void *address, char *out_buffer, int buffer_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/thread.md b/cobalt/site/docs/reference/starboard/modules/14/thread.md index 56c7898a12b43..e9094e39df5c7 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/14/thread.md @@ -519,7 +519,7 @@ or `0`. #### Declaration ``` -void SbThreadSleep(SbTime duration) +void SbThreadSleep(int64_t duration) ``` ### SbThreadYield @@ -531,3 +531,4 @@ Yields the currently executing thread, so another thread has a chance to run. ``` void SbThreadYield() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/time.md b/cobalt/site/docs/reference/starboard/modules/14/time.md index a6228cc0de6ce..e5c8cd2fedd07 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/time.md +++ b/cobalt/site/docs/reference/starboard/modules/14/time.md @@ -150,3 +150,4 @@ times. ``` static int64_t SbTimeToPosix(SbTime time) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/time_zone.md b/cobalt/site/docs/reference/starboard/modules/14/time_zone.md index 74d48172d63eb..c428babc2ae6d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/14/time_zone.md @@ -12,7 +12,7 @@ Provides access to the system time zone information. The number of minutes west of the Greenwich Prime Meridian, NOT including Daylight Savings Time adjustments. -For example: PST/PDT is 480 minutes (28800 seconds, 8 hours). +For example: America/Los_Angeles is 480 minutes (28800 seconds, 8 hours). #### Definition @@ -34,14 +34,15 @@ SbTimeZone SbTimeZoneGetCurrent() ### SbTimeZoneGetName -Gets a string representation of the current timezone. Note that the string -representation can either be standard or daylight saving time. The output can be -of the form: 1) A three-letter abbreviation such as "PST" or "PDT" (preferred). -2) A time zone identifier such as "America/Los_Angeles" 3) An un-abbreviated -name such as "Pacific Standard Time". +Gets a string representation of the current timezone. The format should be in +the IANA format [https://data.iana.org/time-zones/theory.html#naming](https://data.iana.org/time-zones/theory.html#naming)) . +Names normally have the form AREA/LOCATION, where AREA is a continent or ocean, +and LOCATION is a specific location within the area. Typical names are +'Africa/Cairo', 'America/New_York', and 'Pacific/Honolulu'. #### Declaration ``` const char* SbTimeZoneGetName() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md index cb41767130058..34b5114e71cd1 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md @@ -262,12 +262,13 @@ right and top-to-bottom. /// | Negative position. | Positive position. | Positive position. | /// +--------------------+--------------------+--------------------+ /// ^ -/// Content Offset X = 0. +/// Content Offset X = 0. ``` ``` Top-to-bottom is similar to left-to-right, but for the Y position. Bottom-to-top is similar to right-to-left, but for the Y position. + ``` #### Members @@ -281,7 +282,7 @@ This represents a 2x3 transform matrix in row-major order. ``` /// | a b tx | -/// | c d ty | +/// | c d ty | ``` #### Members @@ -320,3 +321,4 @@ Returns whether the given navigation item handle is valid. ``` static bool SbUiNavItemIsValid(SbUiNavItem item) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/user.md b/cobalt/site/docs/reference/starboard/modules/14/user.md index 309b939d066e0..9442ced8f9785 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/user.md +++ b/cobalt/site/docs/reference/starboard/modules/14/user.md @@ -131,3 +131,4 @@ Returns whether the given user handle is valid. ``` static bool SbUserIsValid(SbUser user) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/window.md b/cobalt/site/docs/reference/starboard/modules/14/window.md index acea84d4c7d07..af49c22be727f 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/window.md +++ b/cobalt/site/docs/reference/starboard/modules/14/window.md @@ -328,3 +328,4 @@ hidden. ``` void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/accessibility.md b/cobalt/site/docs/reference/starboard/modules/15/accessibility.md index 5c66ba442803e..8f2a652445a9c 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/15/accessibility.md @@ -251,3 +251,4 @@ off (false). ``` bool SbAccessibilitySetCaptionsEnabled(bool enabled) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/atomic.md b/cobalt/site/docs/reference/starboard/modules/15/atomic.md index 0ed31cb649ec6..9653e53cecd31 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/15/atomic.md @@ -108,3 +108,4 @@ Overloaded functions for Atomic8. ``` static SbAtomic8 SbAtomicRelease_CompareAndSwap8(volatile SbAtomic8 *ptr, SbAtomic8 old_value, SbAtomic8 new_value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md b/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md index 9277c70837b06..3cb7a82958056 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md @@ -212,3 +212,4 @@ Indicates whether the given audio sink handle is valid. ``` bool SbAudioSinkIsValid(SbAudioSink audio_sink) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md index 72dc9327ed1e3..4b2cab30de3d3 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md @@ -73,3 +73,4 @@ value for which the byte order will be swapped. ``` uint64_t SbByteSwapU64(uint64_t value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md index 2d8f30b5fdce2..cd381c5e3f9eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md @@ -40,7 +40,7 @@ size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbConditionVariable SbConditionVariable +typedef union SbConditionVariable SbConditionVariable ``` ## Functions @@ -129,12 +129,13 @@ Waits for `condition`, releasing the held lock `mutex`, blocking up to if `mutex` is not held. `timeout_duration`: The maximum amount of time that function should wait for -`condition`. If the `timeout_duration` value is less than or equal to zero, the -function returns as quickly as possible with a kSbConditionVariableTimedOut -result. +`condition`, in microseconds. If the `timeout_duration` value is less than or +equal to zero, the function returns as quickly as possible with a +kSbConditionVariableTimedOut result. #### Declaration ``` -SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime timeout_duration) +SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, int64_t timeout_duration) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/configuration.md b/cobalt/site/docs/reference/starboard/modules/15/configuration.md index d0ba3c7196f89..fa3e15a4e1603 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/15/configuration.md @@ -53,12 +53,6 @@ will trigger a compiler warning when referenced. SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION - -The API version that is currently open for changes, and therefore is not stable -or frozen. Production-oriented ports should avoid declaring that they implement -the experimental Starboard API version. - ### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for @@ -71,14 +65,10 @@ header available. ### SB_HAS_64_BIT_ATOMICS -Whether the current platform has 64-bit atomic operations. - -### SB_HAS_GLES2 - -Specifies whether this platform has a performant OpenGL ES 2 implementation, -which allows client applications to use GL rendering paths. Derived from the gyp -variable `gl_type` gl_type which indicates what kind of GL implementation is -available. +SB_C_FORCE_INLINE annotation for forcing a C function to be inlined. +SB_EXPORT_PLATFORM annotates symbols as exported from shared libraries. +SB_IMPORT_PLATFORM annotates symbols as imported from shared libraries. Whether +the current platform has 64-bit atomic operations. ### SB_HAS_QUIRK(SB_FEATURE) @@ -99,7 +89,7 @@ Macro for hinting that an expression is likely to be true. ### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, -inclusive. +inclusive. The API version is not stable and is open for changes. ### SB_MINIMUM_API_VERSION @@ -111,11 +101,6 @@ inclusive. Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE - -Declares a function as overriding a virtual function on compilers that support -it. - ### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. @@ -136,7 +121,7 @@ base/compiler_specific.h) Include the platform-specific configuration. This macro is set by GN in starboard/build/config/BUILD.gn and passed in on the command line for all -targets and all configurations.Makes a pointer-typed parameter restricted so +targets and all configurations. Makes a pointer-typed parameter restricted so that the compiler can make certain optimizations because it knows the pointers are unique. diff --git a/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md index e2aa35f2bb1a2..e6e85437eb54e 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md @@ -98,7 +98,7 @@ Book: /youtube/cobalt/_book.yaml SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags + ##### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -259,3 +259,4 @@ fields in `features` are invalid. ``` bool SbCPUFeaturesGet(SbCPUFeatures *features) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/decode_target.md b/cobalt/site/docs/reference/starboard/modules/15/decode_target.md index 1e98db5db54d8..c8d38a28a294b 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/15/decode_target.md @@ -12,7 +12,7 @@ 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 +* 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 @@ -21,7 +21,7 @@ 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. -## 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 @@ -33,51 +33,7 @@ to run arbitrary code on the application's renderer thread 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(). -The primary usage is likely to be the the SbPlayer implementation on some -platforms. - -## SbDecodeTarget Example - -Let's say that we are an application and we would like to use the interface -defined in starboard/image.h to decode an imaginary "image/foo" image type. - -First, the application 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 (SbImageIsDecodeSupported("image/foo", kPreferredFormats[i])) { - format = kPreferredFormats[i]; - break; - } -} - -``` - -Now that the application 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 = SbImageDecode( - context_provider, encoded_foo_data, encoded_foo_data_size, - "image/foo", format); - -// If the decode works, you can get the texture out and render it. -SbDecodeTargetInfo info; -memset(&info, 0, sizeof(info)); -SbDecodeTargetGetInfo(target, &info); -GLuint texture = - info.planes[kSbDecodeTargetPlaneRGBA].texture; -``` +The primary usage is likely to be the SbPlayer implementation on some platforms. ## Macros @@ -127,9 +83,9 @@ premultiplied unless otherwise explicitly specified. 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 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 format with GL - platforms, it is expected that the underlying texture will be set to the + 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). Content region left/right should be specified in u/v width resolution. @@ -207,8 +163,7 @@ information about the graphics context that will be used to render SbDecodeTargets. Some Starboard implementations may need to have references to some graphics objects when creating/destroying resources used by SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects should be provided -to all Starboard functions that might create SbDecodeTargets (e.g. -SbImageDecode()). +to all Starboard functions that might create SbDecodeTargets. #### Members @@ -216,12 +171,12 @@ SbImageDecode()). 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. + `void*` in order to avoid including the EGL header files here. * `void * egl_context` 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. + including the EGL header files here. * `SbDecodeTargetGlesContextRunner gles_context_runner` The `gles_context_runner` function pointer is passed in from the application @@ -264,7 +219,7 @@ This can be queried via calls to SbDecodeTargetGetInfo(). * `SbDecodeTargetInfoPlane planes` The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY, - kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode + kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this decode target. ### SbDecodeTargetInfoContentRegion @@ -368,8 +323,7 @@ static bool SbDecodeTargetIsValid(SbDecodeTarget handle) 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. In the case where SB_HAS(GLES2), this function must be called -on a thread with the context +reference count. This function must be called on a thread with the context. #### Declaration @@ -400,3 +354,4 @@ Starboard implementations, if it is necessary. ``` static void SbDecodeTargetRunInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTargetGlesContextRunnerTarget target, void *target_context) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/directory.md b/cobalt/site/docs/reference/starboard/modules/15/directory.md index 6f845f6567a9c..1c0f904821191 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/15/directory.md @@ -115,3 +115,4 @@ that the directory could not be opened. ``` SbDirectory SbDirectoryOpen(const char *path, SbFileError *out_error) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/drm.md b/cobalt/site/docs/reference/starboard/modules/15/drm.md index f42e43bf3db71..47cf7ef55b8a8 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/15/drm.md @@ -29,7 +29,7 @@ Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. ### SbDrmKeyStatus -Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) +Status of a particular media key. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus) #### Values @@ -67,8 +67,9 @@ The status of session related operations. Used by * `kSbDrmStatusQuotaExceededError` * `kSbDrmStatusUnknownError` - 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. ## Typedefs @@ -85,7 +86,7 @@ typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void ### SbDrmSessionClosedFunc -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. #### Definition @@ -96,8 +97,15 @@ typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, c ### SbDrmSessionKeyStatusesChangedFunc 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. #### Definition @@ -119,6 +127,7 @@ context that was passed into the call to SbDrmCreateSystem(). `error_message` may contain an optional error message when `status` isn't `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. @@ -246,6 +255,50 @@ Clear any internal states/resources related to the specified `session_id`. void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` +### SbDrmCreateSystem + +Creates a new DRM system that can be used when constructing an SbPlayer or an +SbDecoder. + +This function returns `kSbDrmSystemInvalid` if `key_system` is unsupported. + +Also see the documentation of SbDrmGenerateSessionUpdateRequest() and +SbDrmUpdateSession() for more details. + +`key_system`: The DRM key system to be created. The value should be in the 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. Note the key +system will be matched case sensitive. For more details, refer to [https://w3c.github.io/encrypted-media/#dfn-key-system-s](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 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. + +#### Declaration + +``` +SbDrmSystem SbDrmCreateSystem(const char *key_system, void *context, SbDrmSessionUpdateRequestFunc update_request_callback, SbDrmSessionUpdatedFunc session_updated_callback, SbDrmSessionKeyStatusesChangedFunc key_statuses_changed_callback, SbDrmServerCertificateUpdatedFunc server_certificate_updated_callback, SbDrmSessionClosedFunc session_closed_callback) +``` + ### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and @@ -292,9 +345,12 @@ establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used. `type`: The case-sensitive type of the session update request payload. Must not -be NULL. `initialization_data`: The data for which the session update request -payload is created. Must not be NULL. `initialization_data_size`: The size of -the session update request payload. +be NULL. + +`initialization_data`: The data for which the session update request payload is +created. Must not be NULL. + +`initialization_data_size`: The size of the session update request payload. #### Declaration @@ -375,14 +431,18 @@ 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`. `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. `certificate`: Pointer to the server -certificate data. Must not be NULL. `certificate_size`: Size of the server -certificate data. +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. + +`certificate`: Pointer to the server certificate data. Must not be NULL. + +`certificate_size`: Size of the server certificate data. #### Declaration @@ -415,3 +475,4 @@ must not be NULL. ``` void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/egl.md b/cobalt/site/docs/reference/starboard/modules/15/egl.md index 4afff1aa236ef..87deff271ad91 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/15/egl.md @@ -144,3 +144,4 @@ typedef int32_t SbEglInt32 config, void *native_pixmap, const SbEglAttrib *attrib_list)` * `SbEglBoolean(*eglWaitSync)(SbEglDisplay dpy, SbEglSync sync, SbEglInt32 flags)` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/event.md b/cobalt/site/docs/reference/starboard/modules/15/event.md index fdfa85670d1e1..d43fb140118e3 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/event.md +++ b/cobalt/site/docs/reference/starboard/modules/15/event.md @@ -313,7 +313,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -399,7 +399,7 @@ of microseconds to wait before calling the `callback` function. Set `delay` to #### Declaration ``` -SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) +SbEventId SbEventSchedule(SbEventCallback callback, void *context, int64_t delay) ``` ### SbRunStarboardMain @@ -412,3 +412,4 @@ event loop with the application event handler. ``` int SbRunStarboardMain(int argc, char **argv, SbEventHandleCallback callback) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/file.md b/cobalt/site/docs/reference/starboard/modules/15/file.md index 103af475ace1b..fd9b4fbf5c216 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/file.md +++ b/cobalt/site/docs/reference/starboard/modules/15/file.md @@ -124,15 +124,15 @@ Used to hold information about a file. * `bool is_symbolic_link` Whether the file corresponds to a symbolic link. -* `SbTime last_modified` +* `int64_t last_modified` - The last modified time of a file. -* `SbTime last_accessed` + The last modified time of a file - microseconds since Windows epoch UTC. +* `int64_t last_accessed` - The last accessed time of a file. -* `SbTime creation_time` + The last accessed time of a file - microseconds since Windows epoch UTC. +* `int64_t creation_time` - The creation time of a file. + The creation time of a file - microseconds since Windows epoch UTC. ## Functions @@ -402,3 +402,4 @@ The return value identifies the number of bytes written, or `-1` on error. ``` static int SbFileWriteAll(SbFile file, const char *data, int size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/gles.md b/cobalt/site/docs/reference/starboard/modules/15/gles.md index 77bc07e71c82d..049838f80b659 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/15/gles.md @@ -459,3 +459,4 @@ typedef long int SbGlIntPtr internalformat, SbGlSizei width, SbGlSizei height, SbGlSizei depth)` * `void(*glGetInternalformativ)(SbGlEnum target, SbGlEnum internalformat, SbGlEnum pname, SbGlSizei bufSize, SbGlInt32 *params)` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/image.md b/cobalt/site/docs/reference/starboard/modules/15/image.md index 945938a099033..2cb9a716d194b 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/image.md +++ b/cobalt/site/docs/reference/starboard/modules/15/image.md @@ -26,6 +26,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +76,4 @@ indefinitely. ``` bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/input.md b/cobalt/site/docs/reference/starboard/modules/15/input.md index a858c73e3e898..d2dd2db32dc58 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/input.md +++ b/cobalt/site/docs/reference/starboard/modules/15/input.md @@ -168,3 +168,4 @@ A 2-dimensional vector used to represent points and motion vectors. * `float x` * `float y` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/key.md b/cobalt/site/docs/reference/starboard/modules/15/key.md index ed87e531f4fcf..c07837e233c87 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/key.md +++ b/cobalt/site/docs/reference/starboard/modules/15/key.md @@ -291,3 +291,4 @@ Bit-mask of key modifiers. * `kSbKeyModifiersPointerButtonMiddle` * `kSbKeyModifiersPointerButtonBack` * `kSbKeyModifiersPointerButtonForward` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/log.md b/cobalt/site/docs/reference/starboard/modules/15/log.md index 6cf3a491a2a75..60b361d4697d2 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/log.md +++ b/cobalt/site/docs/reference/starboard/modules/15/log.md @@ -134,3 +134,4 @@ Inline wrapper of SbLogFormat to convert from ellipsis to va_args. ``` void static void static void SbLogRawFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/media.md b/cobalt/site/docs/reference/starboard/modules/15/media.md index 42871c2abda49..4aa462ab6b092 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/media.md +++ b/cobalt/site/docs/reference/starboard/modules/15/media.md @@ -187,7 +187,7 @@ output. The type of audio connector. Will be `kSbMediaAudioConnectorUnknown` if this device cannot provide this information. -* `SbTime latency` +* `int64_t latency` The expected latency of audio over this output, in microseconds, or `0` if this device cannot provide this information. @@ -209,8 +209,8 @@ The set of information required by the decoder or player for each audio sample. * `SbMediaAudioStreamInfo stream_info` The set of information of the video stream associated with this sample. -* `SbTime discarded_duration_from_front` -* `SbTime discarded_duration_from_back` +* `int64_t discarded_duration_from_front` +* `int64_t discarded_duration_from_back` ### SbMediaAudioStreamInfo @@ -240,14 +240,13 @@ The set of information required by the decoder or player for each audio stream. The size, in bytes, of the audio_specific_config. * `const void * audio_specific_config` - 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](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. ### SbMediaColorMetadata 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](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) +luminosity than is possible with standard digital imaging. #### Members @@ -447,10 +446,12 @@ Note that neither `mime` nor `key_system` can be NULL. This function returns `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. `key_system`: A lowercase value in the form -of "com.example.somesystem" as suggested by [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system)) that can +than one codec, delimited by comma. + +`key_system`: A lowercase value in the form of "com.example.somesystem", and 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. +For more detail, refer to [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system) An implementation may choose to support `key_system` with extra attributes, separated by ';', like `com.example.somesystem; attribute_name1="value1"; @@ -462,23 +463,21 @@ 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` 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` encryptionScheme of -MediaKeySystemMediaCapability, as defined in [https://wicg.github.io/encrypted-media-encryption-scheme/,](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` kSbMediaSupportTypeNotSupported when +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. It 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` 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` kSbMediaSupportTypeProbably when +`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` 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. +`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. For more detail, refer to [https://wicg.github.io/encrypted-media-encryption-scheme](https://wicg.github.io/encrypted-media-encryption-scheme) #### Declaration @@ -548,7 +547,7 @@ When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can return 0, in which case the media stack will allocate extra memory on demand. When SbMediaGetInitialBufferCapacity and this function both return 0, the media -stack will allocate individual buffers directly using SbMemory functions. +stack will allocate individual buffers directly using malloc functions. #### Declaration @@ -558,19 +557,19 @@ int SbMediaGetBufferAllocationUnit() ### SbMediaGetBufferGarbageCollectionDurationThreshold -Specifies the duration threshold of media source garbage collection. When the -accumulated duration in a source buffer exceeds this value, the media source -implementation will try to eject existing buffers from the cache. This is -usually triggered when the video being played has a simple content and the -encoded data is small. In such case this can limit how much is allocated for the -book keeping data of the media buffers and avoid OOM of system heap. This should -return 170 seconds for most of the platforms. But it can be further reduced on -systems with extremely low memory. +Specifies the duration threshold of media source garbage collection in +microseconds. When the accumulated duration in a source buffer exceeds this +value, the media source implementation will try to eject existing buffers from +the cache. This is usually triggered when the video being played has a simple +content and the encoded data is small. In such case this can limit how much is +allocated for the book keeping data of the media buffers and avoid OOM of system +heap. This should return 170 seconds for most of the platforms. But it can be +further reduced on systems with extremely low memory. #### Declaration ``` -SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() +int64_t SbMediaGetBufferGarbageCollectionDurationThreshold() ``` ### SbMediaGetBufferPadding @@ -589,7 +588,7 @@ int SbMediaGetBufferPadding() Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored -in main memory allocated by SbMemory functions. For file storage, the media +in main memory allocated by malloc functions. For file storage, the media buffers will be stored in a temporary file in the system cache folder acquired by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when its value is "file" the media stack will still allocate memory to cache the @@ -624,10 +623,14 @@ allocation of media buffers may only fail when there is not enough memory in the system to fulfill the request, under which case the 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. +`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. #### Declaration @@ -642,10 +645,14 @@ resolution of such videos shouldn't go beyond 1080p. Its value should be less than the sum of SbMediaGetAudioBufferBudget and '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. +`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. #### Declaration @@ -661,10 +668,14 @@ being used by video buffers but will also make app less likely to re-download video data. Note that the app may experience significant difficulty if this 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. +`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. #### Declaration @@ -692,10 +703,11 @@ bool SbMediaIsBufferPoolAllocateOnDemand() ### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer -pools should be allocated on demand, as opposed to using SbMemory* functions. +pools should be allocated on demand, as opposed to using malloc functions. #### Declaration ``` bool SbMediaIsBufferUsingMemoryPool() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/memory.md b/cobalt/site/docs/reference/starboard/modules/15/memory.md index 5b13119060ec9..79df85e2f02a8 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/15/memory.md @@ -30,8 +30,9 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. ### SbMemoryMapFlags -The bitwise OR of these flags should be passed to SbMemoryMap to indicate how -the mapped memory can be used. +TODO: Remove the definition once the memory_mapped_file.h extension is +deprecated. The bitwise OR of these flags should be passed to SbMemoryMap to +indicate how the mapped memory can be used. #### Values @@ -330,3 +331,4 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns ``` bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md deleted file mode 100644 index 5e49693e70bce..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -layout: doc -title: "Starboard Module Reference: memory_reporter.h" ---- - -DEPRECATED: Provides an interface for memory reporting. - -## Typedefs ## - -### SbMemoryReporterOnAlloc ### - -A function to report a memory allocation from SbMemoryAllocate(). Note that -operator new calls SbMemoryAllocate which will delegate to this callback. - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnAlloc) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnDealloc ### - -A function to report a memory deallocation from SbMemoryDeallcoate(). Note that -operator delete calls SbMemoryDeallocate which will delegate to this callback. - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnDealloc) (void *context, const void *memory) -``` - -### SbMemoryReporterOnMapMemory ### - -A function to report a memory mapping from SbMemoryMap(). - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnMapMemory) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnUnMapMemory ### - -A function to report a memory unmapping from SbMemoryUnmap(). - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnUnMapMemory) (void *context, const void *memory, size_t size) -``` - -## Structs ## - -### SbMemoryReporter ### - -SbMemoryReporter allows memory reporting via user-supplied functions. The void* -context is passed to every call back. It's strongly recommended that C-Style -struct initialization is used so that the arguments can be typed check by the -compiler. For example, SbMemoryReporter mem_reporter = { MallocCallback, .... -context }; - -#### Members #### - -* `SbMemoryReporterOnAlloc on_alloc_cb` - - Callback to report allocations. -* `SbMemoryReporterOnDealloc on_dealloc_cb` - - Callback to report deallocations. -* `SbMemoryReporterOnMapMemory on_mapmem_cb` - - Callback to report memory map. -* `SbMemoryReporterOnUnMapMemory on_unmapmem_cb` - - Callback to report memory unmap. -* `void * context` - - Optional, is passed to callbacks as first argument. - -## Functions ## - -### SbMemorySetReporter ### - -Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime -management is done internally on input pointer. - -NOTE: This module is unused starting with Starboard 15 and will be removed in -the future. - -Returns true if the memory reporter was set with no errors. If an error was -reported then check the log for why it failed. - -Note that other than a thread-barrier-write of the input pointer, there is no -thread safety guarantees with this function due to performance considerations. -It's recommended that this be called once during the lifetime of the program, or -not at all. Do not delete the supplied pointer, ever. Example (Good): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); // allow value to leak. Example (Bad): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); delete mem_reporter; // May crash. - -#### Declaration #### - -``` -bool SbMemorySetReporter(struct SbMemoryReporter *tracker) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/15/microphone.md b/cobalt/site/docs/reference/starboard/modules/15/microphone.md index bcf9e4355e65c..497cbe91cec43 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/15/microphone.md @@ -260,3 +260,4 @@ has already been read from the device is discarded. ``` int SbMicrophoneRead(SbMicrophone microphone, void *out_audio_data, int audio_data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/mutex.md b/cobalt/site/docs/reference/starboard/modules/15/mutex.md index 82ff8500ab8d8..37e2ce06bab4b 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/15/mutex.md @@ -40,7 +40,7 @@ SB_MUTEX_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbMutex SbMutex +typedef union SbMutex SbMutex ``` ## Functions @@ -125,3 +125,4 @@ held by the current thread. ``` bool SbMutexRelease(SbMutex *mutex) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/once.md b/cobalt/site/docs/reference/starboard/modules/15/once.md index d77302467f8b0..de4867461edc4 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/once.md +++ b/cobalt/site/docs/reference/starboard/modules/15/once.md @@ -22,7 +22,7 @@ SB_ONCE_MAX_SIZE and aligned at void pointer type. #### Definition ``` -typedef union SbOnceControl SbOnceControl +typedef union SbOnceControl SbOnceControl ``` ### SbOnceInitRoutine @@ -55,3 +55,4 @@ Thread-safely runs `init_routine` only once. ``` bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/player.md b/cobalt/site/docs/reference/starboard/modules/15/player.md index 0382642a35fe9..837dd941d1ea6 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/player.md +++ b/cobalt/site/docs/reference/starboard/modules/15/player.md @@ -52,9 +52,12 @@ data may come from multiple sources. * `kMatroskaBlockAdditional` The side data comes from the BlockAdditional data in the Matroska/Webm - container, as specified in [https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39](https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39)9) andnd [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional)l) - . The first 8 bytes of the data contains the value of BlockAddID in big - endian format, followed by the content of BlockAdditional. + container. The first 8 bytes of the data contains the value of BlockAddID in + big endian format, followed by the content of BlockAdditional. See: + + [https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03](https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03) + + [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional) ### SbPlayerState @@ -130,10 +133,13 @@ typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMed ### SbPlayerErrorFunc -Callback for player errors, that may set a `message`. `error`: indicates the -error code. `message`: provides specific informative diagnostic message about -the error condition encountered. It is ok for the message to be an empty string -or NULL if no information is available. +Callback for player errors, that may set a `message`. + +`error`: indicates the error code. + +`message`: provides specific informative diagnostic message about the error +condition encountered. It is ok for the message to be an empty string or NULL if +no information is available. #### Definition @@ -192,14 +198,14 @@ Information about the current media playback state. #### Members -* `SbTime current_media_timestamp` +* `int64_t current_media_timestamp` The position of the playback head, as precisely as possible, in microseconds. -* `SbTime duration` +* `int64_t duration` The known duration of the currently playing media stream, in microseconds. -* `SbTime start_date` +* `int64_t start_date` The result of getStartDate for the currently playing media stream, in microseconds since the epoch of January 1, 1601 UTC. @@ -250,9 +256,9 @@ Information about the samples to be written into SbPlayerWriteSamples(). * `int buffer_size` Size of the data pointed to by `buffer`. -* `SbTime timestamp` +* `int64_t timestamp` - The timestamp of the sample in SbTime. + The timestamp of the sample in microseconds since Windows epoch UTC. * `SbPlayerSampleSideData* side_data` Points to an array of side data for the input, when available. @@ -292,20 +298,123 @@ coming from multiple sources. ## Functions +### SbPlayerCreate + +Creates a player that will be displayed on `window` for the specified +`video_codec` and `audio_codec`, acquiring all resources needed to operate it, +and returning an opaque handle to it. The expectation is that a new player will +be created and destroyed for every playback. + +This function returns the created player. Note the following: + +* The associated decoder of the returned player should be assumed to not be in + `kSbPlayerDecoderStateNeedsData` until SbPlayerSeek() has been called on it. + +* It is expected either that the thread that calls SbPlayerCreate is the same + thread that calls the other `SbPlayer` functions for that player, or that + there is a mutex guarding calls into each `SbPlayer` instance. + +* If there is a platform limitation on how many players can coexist + simultaneously, then calls made to this function that attempt to exceed that + limit must return `kSbPlayerInvalid`. Multiple calls to SbPlayerCreate must + not cause a crash. + +`window`: The window that will display the player. `window` can be +`kSbWindowInvalid` for platforms where video is only displayed on a particular +window that the underlying implementation already has access to. + +`video_codec`: The video codec used for the player. If `video_codec` is +`kSbMediaVideoCodecNone`, the player is an audio-only player. If `video_codec` +is any other value, the player is an audio/video decoder. This can be set to +`kSbMediaVideoCodecNone` to play a video with only an audio track. + +`audio_codec`: The audio codec used for the player. The caller must provide a +populated `audio_sample_info` if audio codec is `kSbMediaAudioCodecAac`. Can be +set to `kSbMediaAudioCodecNone` to play a video without any audio track. In such +case `audio_sample_info` must be NULL. + +`drm_system`: If the media stream has encrypted portions, then this parameter +provides an appropriate DRM system, created with `SbDrmCreateSystem()`. If the +stream does not have encrypted portions, then `drm_system` may be +`kSbDrmSystemInvalid`. + +`audio_sample_info`: Note that the caller must provide a populated +`audio_sample_info` if the audio codec is `kSbMediaAudioCodecAac`. Otherwise, +`audio_sample_info` can be NULL. See media.h for the format of the +`SbMediaAudioSampleInfo` struct. + +Note that `audio_specific_config` is a pointer and the content it points to is +no longer valid after this function returns. The implementation has to make a +copy of the content if it is needed after the function returns. + +`max_video_capabilities`: This string communicates the max video capabilities +required to the platform. The web app will not provide a video stream exceeding +the maximums described by this parameter. Allows the platform to optimize +playback pipeline for low quality video streams if it knows that it will never +adapt to higher quality streams. The string uses the same format as the string +passed in to SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to +"width=1920; height=1080; framerate=15;", the video will never adapt to +resolution higher than 1920x1080 or frame per second higher than 15 fps. When +the maximums are unknown, this will be set to NULL. + +`sample_deallocator_func`: If not `NULL`, the player calls this function on an +internal thread to free the sample buffers passed into SbPlayerWriteSample(). + +`decoder_status_func`: If not `NULL`, the decoder calls this function on an +internal thread to provide an update on the decoder's status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_status_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the playback status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_error_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the error status. This callback is +responsible for setting the media error message. + +`context`: This is passed to all callbacks and is generally used to point at a +class or struct that contains state associated with the player. + +`output_mode`: Selects how the decoded video frames will be output. For example, +kSbPlayerOutputModePunchOut indicates that the decoded video frames will be +output to a background video layer by the platform, and +kSbPlayerOutputDecodeToTexture indicates that the decoded video frames should be +made available for the application to pull via calls to +SbPlayerGetCurrentFrame(). + +`provider`: Only present in Starboard version 3 and up. If not `NULL`, then when +output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY use the +provider to create SbDecodeTargets on the renderer thread. A provider may not +always be needed by the player, but if it is needed, and the provider is not +given, the player will fail by returning `kSbPlayerInvalid`. + +If `NULL` is passed to any of the callbacks (`sample_deallocator_func`, +`decoder_status_func`, `player_status_func`, or `player_error_func` if it +applies), then `kSbPlayerInvalid` must be returned. + +#### Declaration + +``` +SbPlayer SbPlayerCreate(SbWindow window, const SbPlayerCreationParam *creation_param, SbPlayerDeallocateSampleFunc sample_deallocate_func, SbPlayerDecoderStatusFunc decoder_status_func, SbPlayerStatusFunc player_status_func, SbPlayerErrorFunc player_error_func, void *context, SbDecodeTargetGraphicsContextProvider *context_provider) +``` + ### SbPlayerDestroy Destroys `player`, freeing all associated resources. * Upon calling this method, there should be one call to the player status callback (i.e. `player_status_func` used in the creation of the player) - which indicates the player is destroyed. Note, the callback has to be in- - flight when SbPlayerDestroyed is called. + which indicates the player is destroyed. Note, the callback has to be + inflight when SbPlayerDestroyed is called. * No more other callbacks should be issued after this function returns. * It is not allowed to pass `player` into any other `SbPlayer` function once - SbPlayerDestroy has been called on that player. `player`: The player to be - destroyed. Must not be `kSbPlayerInvalid`. + SbPlayerDestroy has been called on that player. + +`player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. #### Declaration @@ -326,50 +435,50 @@ audio output configurations other than the ones already returned. The app will use the information returned to determine audio related behaviors, like: -Audio Write Duration: Audio write duration is how far past the current playback -position the app will write audio samples. The app will write all samples -between `current_playback_position` and `current_playback_position` + -`audio_write_duration`, as soon as they are available. - -`audio_write_duration` will be to `kSbPlayerWriteDurationLocal` -kSbPlayerWriteDurationLocal when all audio configurations linked to `player` is -local, or if there isn't any audio output. It will be set to -`kSbPlayerWriteDurationRemote` kSbPlayerWriteDurationRemote for remote or -wireless audio outputs, i.e. one of `kSbMediaAudioConnectorBluetooth` -kSbMediaAudioConnectorBluetooth or `kSbMediaAudioConnectorRemote*` -kSbMediaAudioConnectorRemote* . - -The app only guarantees to write `audio_write_duration` past -`current_playback_position`, but the app is free to write more samples than -that. So the platform shouldn't rely on this for flow control. The platform -should achieve flow control by sending `kSbPlayerDecoderStateNeedsData` -kSbPlayerDecoderStateNeedsData less frequently. - -The platform is responsible for guaranteeing that when only -`audio_write_duration` audio samples are written at a time, no playback issues -occur (such as transient or indefinite hanging). +* Audio Write Duration: Audio write duration is how far past the current + playback position the app will write audio samples. The app will write all + samples between `current_playback_position` and `current_playback_position` + + `audio_write_duration`, as soon as they are available. + +* `audio_write_duration` will be to `kSbPlayerWriteDurationLocal` when all + audio configurations linked to `player` is local, or if there isn't any + audio output. It will be set to `kSbPlayerWriteDurationRemote` for remote or + wireless audio outputs, i.e. one of `kSbMediaAudioConnectorBluetooth` or + `kSbMediaAudioConnectorRemote*`. + +* The app only guarantees to write `audio_write_duration` past + `current_playback_position`, but the app is free to write more samples than + that. So the platform shouldn't rely on this for flow control. The platform + should achieve flow control by sending `kSbPlayerDecoderStateNeedsData` less + frequently. + +* The platform is responsible for guaranteeing that when only + `audio_write_duration` audio samples are written at a time, no playback + issues occur (such as transient or indefinite hanging). The audio configurations should be available as soon as possible, and they have -to be available when the `player` is at `kSbPlayerStatePresenting` -kSbPlayerStatePresenting , unless the audio codec is `kSbMediaAudioCodecNone` or -there's no written audio inputs. +to be available when the `player` is at `kSbPlayerStatePresenting`, unless the +audio codec is `kSbMediaAudioCodecNone` or there's no written audio inputs. -The app will set `audio_write_duration` to `kSbPlayerWriteDurationLocal` -kSbPlayerWriteDurationLocal when the audio configuration isn't available (i.e. -the function returns false when index is 0). The platform has to make the audio -configuration available immediately after the SbPlayer is created, if it expects -the app to treat the platform as using wireless audio outputs. +The app will set `audio_write_duration` to `kSbPlayerWriteDurationLocal` when +the audio configuration isn't available (i.e. the function returns false when +index is 0). The platform has to make the audio configuration available +immediately after the SbPlayer is created, if it expects the app to treat the +platform as using wireless audio outputs. Once at least one audio configurations are returned, the return values and their orders shouldn't change during the life time of `player`. The platform may -inform the app of any changes by sending `kSbPlayerErrorCapabilityChanged` -kSbPlayerErrorCapabilityChanged to request a playback restart. +inform the app of any changes by sending `kSbPlayerErrorCapabilityChanged` to +request a playback restart. `player`: The player about which information is being retrieved. Must not be -`kSbPlayerInvalid`. `index`: The index of the audio output configuration. Must -be greater than or equal to 0. `out_audio_configuration`: The information about -the audio output, refer to `SbMediaAudioConfiguration` for more details. Must -not be NULL. +`kSbPlayerInvalid`. + +`index`: The index of the audio output configuration. Must be greater than or +equal to 0. + +`out_audio_configuration`: The information about the audio output, refer to +`SbMediaAudioConfiguration` for more details. Must not be NULL. #### Declaration @@ -395,19 +504,36 @@ kSbDecodeTargetInvalid is returned. SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` +### SbPlayerGetInfo + +Gets a snapshot of the current player state and writes it to `out_player_info`. +This function may be called very frequently and is expected to be inexpensive. + +`player`: The player about which information is being retrieved. Must not be +`kSbPlayerInvalid`. + +`out_player_info`: The information retrieved for the player. + +#### Declaration + +``` +void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo *out_player_info) +``` + ### SbPlayerGetMaximumNumberOfSamplesPerWrite -Writes a single sample of the given media type to `player`'s input stream. Its -data may be passed in via more than one buffers. The lifetime of -`sample_buffers`, `sample_buffer_sizes`, `video_sample_info`, and -`sample_drm_info` (as well as member `subsample_mapping` contained inside it) -are not guaranteed past the call to SbPlayerWriteSample. That means that before -returning, the implementation must synchronously copy any information it wants -to retain from those structures. +Returns the maximum number of samples that can be written in a single call to +SbPlayerWriteSamples(). Returning a value greater than one can improve +performance by allowing SbPlayerWriteSamples() to write multiple samples in one +call. -`player`: The player for which the number is retrieved. `sample_type`: The type -of sample for which the number is retrieved. See the `SbMediaType` enum in -media.h. +Note that this feature is currently disabled in Cobalt where +SbPlayerWriteSamples() will always be called with one sample. + +`player`: The player for which the number is retrieved. + +`sample_type`: The type of sample for which the number is retrieved. See the +`SbMediaType` enum in media.h. #### Declaration @@ -449,6 +575,45 @@ Returns whether the given player handle is valid. static bool SbPlayerIsValid(SbPlayer player) ``` +### SbPlayerSeek + +Tells the player to freeze playback (if playback has already started), reset or +flush the decoder pipeline, and go back to the Prerolling state. The player +should restart playback once it can display the frame at `seek_to_timestamp`, or +the closest it can get. (Some players can only seek to I-Frames, for example.) + +* Seek must be called before samples are sent when starting playback for the + first time, or the client never receives the + `kSbPlayerDecoderStateNeedsData` signal. + +* A call to seek may interrupt another seek. + +* After this function is called, the client should not send any more audio or + video samples until `SbPlayerDecoderStatusFunc` is called back with + `kSbPlayerDecoderStateNeedsData` for each required media type. + `SbPlayerDecoderStatusFunc` is the `decoder_status_func` callback function + that was specified when the player was created (SbPlayerCreate). + +`player`: The SbPlayer in which the seek operation is being performed. Must not +be `kSbPlayerInvalid`. + +`seek_to_timestamp`: The frame at which playback should begin. + +`ticket`: A user-supplied unique ID to be passed to all subsequent +`SbPlayerDecoderStatusFunc` calls. (That is the `decoder_status_func` callback +function specified when calling SbPlayerCreate.) + +The `ticket` value is used to filter calls that may have been in flight when +SbPlayerSeek was called. To be very specific, once SbPlayerSeek has been called +with ticket X, a client should ignore all `SbPlayerDecoderStatusFunc` calls that +do not pass in ticket X. + +#### Declaration + +``` +void SbPlayerSeek(SbPlayer player, int64_t seek_to_timestamp, int ticket) +``` + ### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do @@ -464,11 +629,18 @@ implementors should take care to avoid related performance concerns with such frequent calls. `player`: The player that is being resized. Must not be `kSbPlayerInvalid`. + `z_index`: The z-index of the player. When the bounds of multiple players are overlapped, the one with larger z-index will be rendered on top of the ones with -smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. -`y`: The y-coordinate of the upper-left corner of the player. `width`: The width -of the player, in pixels. `height`: The height of the player, in pixels. +smaller z-index. + +`x`: The x-coordinate of the upper-left corner of the player. + +`y`: The y-coordinate of the upper-left corner of the player. + +`width`: The width of the player, in pixels. + +`height`: The height of the player, in pixels. #### Declaration @@ -502,9 +674,11 @@ bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) Sets the player's volume. `player`: The player in which the volume is being adjusted. Must not be -`kSbPlayerInvalid`. `volume`: The new player volume. The value must be between -`0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be -muted, and a value of `1.0` means that it should be played at full volume. +`kSbPlayerInvalid`. + +`volume`: The new player volume. The value must be between `0.0` and `1.0`, +inclusive. A value of `0.0` means that the audio should be muted, and a value of +`1.0` means that it should be played at full volume. #### Declaration @@ -519,8 +693,9 @@ there are no more samples for that media type for the remainder of this media stream. This marker is invalidated, along with the rest of the stream's contents, after a call to SbPlayerSeek. -`player`: The player to which the marker is written. `stream_type`: The type of -stream for which the marker is written. +`player`: The player to which the marker is written. + +`stream_type`: The type of stream for which the marker is written. #### Declaration @@ -530,14 +705,29 @@ void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ### SbPlayerWriteSamples +Writes samples of the given media type to `player`'s input stream. The lifetime +of `sample_infos`, and the members of its elements like `buffer`, +`video_sample_info`, and `drm_info` (as well as member `subsample_mapping` +contained inside it) are not guaranteed past the call to SbPlayerWriteSamples(). +That means that before returning, the implementation must synchronously copy any +information it wants to retain from those structures. + +SbPlayerWriteSamples() allows writing of multiple samples in one call. + +`player`: The player to which the sample is written. Must not be +`kSbPlayerInvalid`. + `sample_type`: The type of sample being written. See the `SbMediaType` enum in -media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with +media.h. + +`sample_infos`: A pointer to an array of SbPlayerSampleInfo with `number_of_sample_infos` elements, each holds the data for an sample, i.e. a sequence of whole NAL Units for video, or a complete audio frame. `sample_infos` cannot be assumed to live past the call into SbPlayerWriteSamples(), so it must be copied if its content will be used after SbPlayerWriteSamples() returns. + `number_of_sample_infos`: Specify the number of samples contained inside -`sample_infos`. It has to be at least one, and less than the return value of +`sample_infos`. It has to be at least one, and at most the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). #### Declaration @@ -545,3 +735,4 @@ SbPlayerGetMaximumNumberOfSamplesPerWrite(). ``` void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/socket.md b/cobalt/site/docs/reference/starboard/modules/15/socket.md index 744c04e3847d2..e7f4bc9e71563 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/15/socket.md @@ -540,15 +540,15 @@ Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: If set to `true`, -then `period` specifies the minimum time (SbTime) is always in microseconds) -between keep-alive packets. If set to `false`, `period` is ignored. `period`: -The time between keep-alive packets. This value is only relevant if `value` is -`true`. +then `period` specifies the minimum time in microseconds between keep-alive +packets. If set to `false`, `period` is ignored. `period`: The time in +microseconds between keep-alive packets. This value is only relevant if `value` +is `true`. #### Declaration ``` -bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) +bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, int64_t period) ``` ### SbSocketSetTcpNoDelay @@ -583,3 +583,4 @@ option. ``` bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md b/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md index f1c6bd8b9f2fa..54bc7eae0645f 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md @@ -202,15 +202,15 @@ SbSocketWaiterWakeUp() it not called by that time. The return value indicates the reason that the socket waiter exited. This function should only be called on the thread that waits on this waiter. -`duration`: The minimum amount of time after which the socket waiter should exit -if it is not woken up before then. As with SbThreadSleep() (see thread.h), this -function may wait longer than `duration`, such as if the timeout expires while a -callback is being fired. +`duration`: The minimum amount of time in microseconds after which the socket +waiter should exit if it is not woken up before then. As with SbThreadSleep() +(see thread.h), this function may wait longer than `duration`, such as if the +timeout expires while a callback is being fired. #### Declaration ``` -SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) +SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, int64_t duration) ``` ### SbSocketWaiterWakeUp @@ -235,3 +235,4 @@ next 7 times they are called. ``` void SbSocketWaiterWakeUp(SbSocketWaiter waiter) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md b/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md index 0bd6e65b63790..ea4ad46b3f87d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md @@ -49,3 +49,4 @@ when the previous utterances are complete. ``` void SbSpeechSynthesisSpeak(const char *text) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/storage.md b/cobalt/site/docs/reference/starboard/modules/15/storage.md index f20016113be16..0311c62bf10a0 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/15/storage.md @@ -156,3 +156,4 @@ after a short time, even if there is an unexpected process termination before ``` bool SbStorageWriteRecord(SbStorageRecord record, const char *data, int64_t data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/string.md b/cobalt/site/docs/reference/starboard/modules/15/string.md index 3fed809df4618..bd04c99c94192 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/string.md +++ b/cobalt/site/docs/reference/starboard/modules/15/string.md @@ -127,21 +127,6 @@ be formatted. `arguments`: Variable arguments used in the string. int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF - -An inline wrapper of SbStringFormatWide that converts from ellipsis to -`va_args`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) -``` - ### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The @@ -172,3 +157,4 @@ Values matching `pattern` that were extracted from `buffer`. ``` static int SbStringScanF(const char *buffer, const char *pattern,...) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/system.md b/cobalt/site/docs/reference/starboard/modules/15/system.md index 86437a3d08041..04fceecbe83ea 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/system.md +++ b/cobalt/site/docs/reference/starboard/modules/15/system.md @@ -670,3 +670,4 @@ signal-safe on platforms that support signals. ``` bool SbSystemSymbolize(const void *address, char *out_buffer, int buffer_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/thread.md b/cobalt/site/docs/reference/starboard/modules/15/thread.md index 56c7898a12b43..e9094e39df5c7 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/15/thread.md @@ -519,7 +519,7 @@ or `0`. #### Declaration ``` -void SbThreadSleep(SbTime duration) +void SbThreadSleep(int64_t duration) ``` ### SbThreadYield @@ -531,3 +531,4 @@ Yields the currently executing thread, so another thread has a chance to run. ``` void SbThreadYield() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/time.md b/cobalt/site/docs/reference/starboard/modules/15/time.md index a6228cc0de6ce..e5c8cd2fedd07 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/time.md +++ b/cobalt/site/docs/reference/starboard/modules/15/time.md @@ -150,3 +150,4 @@ times. ``` static int64_t SbTimeToPosix(SbTime time) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/time_zone.md b/cobalt/site/docs/reference/starboard/modules/15/time_zone.md index 74d48172d63eb..c428babc2ae6d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/15/time_zone.md @@ -12,7 +12,7 @@ Provides access to the system time zone information. The number of minutes west of the Greenwich Prime Meridian, NOT including Daylight Savings Time adjustments. -For example: PST/PDT is 480 minutes (28800 seconds, 8 hours). +For example: America/Los_Angeles is 480 minutes (28800 seconds, 8 hours). #### Definition @@ -34,14 +34,15 @@ SbTimeZone SbTimeZoneGetCurrent() ### SbTimeZoneGetName -Gets a string representation of the current timezone. Note that the string -representation can either be standard or daylight saving time. The output can be -of the form: 1) A three-letter abbreviation such as "PST" or "PDT" (preferred). -2) A time zone identifier such as "America/Los_Angeles" 3) An un-abbreviated -name such as "Pacific Standard Time". +Gets a string representation of the current timezone. The format should be in +the IANA format [https://data.iana.org/time-zones/theory.html#naming](https://data.iana.org/time-zones/theory.html#naming)) . +Names normally have the form AREA/LOCATION, where AREA is a continent or ocean, +and LOCATION is a specific location within the area. Typical names are +'Africa/Cairo', 'America/New_York', and 'Pacific/Honolulu'. #### Declaration ``` const char* SbTimeZoneGetName() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md index cb41767130058..34b5114e71cd1 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md @@ -262,12 +262,13 @@ right and top-to-bottom. /// | Negative position. | Positive position. | Positive position. | /// +--------------------+--------------------+--------------------+ /// ^ -/// Content Offset X = 0. +/// Content Offset X = 0. ``` ``` Top-to-bottom is similar to left-to-right, but for the Y position. Bottom-to-top is similar to right-to-left, but for the Y position. + ``` #### Members @@ -281,7 +282,7 @@ This represents a 2x3 transform matrix in row-major order. ``` /// | a b tx | -/// | c d ty | +/// | c d ty | ``` #### Members @@ -320,3 +321,4 @@ Returns whether the given navigation item handle is valid. ``` static bool SbUiNavItemIsValid(SbUiNavItem item) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/user.md b/cobalt/site/docs/reference/starboard/modules/15/user.md index 309b939d066e0..9442ced8f9785 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/user.md +++ b/cobalt/site/docs/reference/starboard/modules/15/user.md @@ -131,3 +131,4 @@ Returns whether the given user handle is valid. ``` static bool SbUserIsValid(SbUser user) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/15/window.md b/cobalt/site/docs/reference/starboard/modules/15/window.md index acea84d4c7d07..af49c22be727f 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/window.md +++ b/cobalt/site/docs/reference/starboard/modules/15/window.md @@ -328,3 +328,4 @@ hidden. ``` void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/accessibility.md b/cobalt/site/docs/reference/starboard/modules/16/accessibility.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/accessibility.md rename to cobalt/site/docs/reference/starboard/modules/16/accessibility.md index 5c66ba442803e..8f2a652445a9c 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/16/accessibility.md @@ -251,3 +251,4 @@ off (false). ``` bool SbAccessibilitySetCaptionsEnabled(bool enabled) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/atomic.md b/cobalt/site/docs/reference/starboard/modules/16/atomic.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/atomic.md rename to cobalt/site/docs/reference/starboard/modules/16/atomic.md index 0ed31cb649ec6..9653e53cecd31 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/16/atomic.md @@ -108,3 +108,4 @@ Overloaded functions for Atomic8. ``` static SbAtomic8 SbAtomicRelease_CompareAndSwap8(volatile SbAtomic8 *ptr, SbAtomic8 old_value, SbAtomic8 new_value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/audio_sink.md b/cobalt/site/docs/reference/starboard/modules/16/audio_sink.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/audio_sink.md rename to cobalt/site/docs/reference/starboard/modules/16/audio_sink.md index 9277c70837b06..3cb7a82958056 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/16/audio_sink.md @@ -212,3 +212,4 @@ Indicates whether the given audio sink handle is valid. ``` bool SbAudioSinkIsValid(SbAudioSink audio_sink) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/configuration.md b/cobalt/site/docs/reference/starboard/modules/16/configuration.md similarity index 86% rename from cobalt/site/docs/reference/starboard/modules/13/configuration.md rename to cobalt/site/docs/reference/starboard/modules/16/configuration.md index d0ba3c7196f89..3ff1bef8b49ca 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/16/configuration.md @@ -53,11 +53,10 @@ will trigger a compiler warning when referenced. SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION +### SB_EXPORT_PLATFORM -The API version that is currently open for changes, and therefore is not stable -or frozen. Production-oriented ports should avoid declaring that they implement -the experimental Starboard API version. +SB_C_FORCE_INLINE annotation for forcing a C function to be inlined. +SB_EXPORT_PLATFORM annotates symbols as exported from shared libraries. ### SB_FUNCTION @@ -73,17 +72,14 @@ header available. Whether the current platform has 64-bit atomic operations. -### SB_HAS_GLES2 - -Specifies whether this platform has a performant OpenGL ES 2 implementation, -which allows client applications to use GL rendering paths. Derived from the gyp -variable `gl_type` gl_type which indicates what kind of GL implementation is -available. - ### SB_HAS_QUIRK(SB_FEATURE) Determines at compile-time whether this platform has a quirk. +### SB_IMPORT_PLATFORM + +SB_IMPORT_PLATFORM annotates symbols as imported from shared libraries. + ### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. @@ -99,7 +95,7 @@ Macro for hinting that an expression is likely to be true. ### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, -inclusive. +inclusive. The API version is not stable and is open for changes. ### SB_MINIMUM_API_VERSION @@ -111,11 +107,6 @@ inclusive. Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE - -Declares a function as overriding a virtual function on compilers that support -it. - ### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. @@ -136,7 +127,7 @@ base/compiler_specific.h) Include the platform-specific configuration. This macro is set by GN in starboard/build/config/BUILD.gn and passed in on the command line for all -targets and all configurations.Makes a pointer-typed parameter restricted so +targets and all configurations. Makes a pointer-typed parameter restricted so that the compiler can make certain optimizations because it knows the pointers are unique. diff --git a/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/16/configuration_constants.md similarity index 93% rename from cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md rename to cobalt/site/docs/reference/starboard/modules/16/configuration_constants.md index 012754b623bdc..3866aab20c5fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/16/configuration_constants.md @@ -9,6 +9,15 @@ runtime decisions based on per platform configurations. ## Variables +### kHasPartialAudioFramesSupport + +Platform can support partial audio frames + +### kSbCanMapExecutableMemory + +Whether this platform can map executable memory. This is required for platforms +that want to JIT. + ### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if @@ -50,10 +59,6 @@ component separator character. The string form of SB_FILE_SEP_CHAR. -### kSbHasAc3Audio - -Allow ac3 and ec3 support - ### kSbHasMediaWebmVp9Support Specifies whether this platform has webm/vp9 support. This should be set to non- @@ -67,6 +72,10 @@ Whether the current platform supports thread priorities. Determines the alignment that allocations should have on this platform. +### kSbMaxSystemPathCacheDirectorySize + +The maximum size the cache directory is allowed to use in bytes. + ### kSbMaxThreadLocalKeys The maximum number of thread local storage keys supported by this platform. This @@ -139,7 +148,3 @@ The string form of SB_PATH_SEP_CHAR. Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. - -### kSbUserMaxSignedIn - -The maximum number of users that can be signed in at the same time. diff --git a/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/16/cpu_features.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/cpu_features.md rename to cobalt/site/docs/reference/starboard/modules/16/cpu_features.md index e2aa35f2bb1a2..e6e85437eb54e 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/16/cpu_features.md @@ -98,7 +98,7 @@ Book: /youtube/cobalt/_book.yaml SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags + ##### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -259,3 +259,4 @@ fields in `features` are invalid. ``` bool SbCPUFeaturesGet(SbCPUFeatures *features) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/decode_target.md b/cobalt/site/docs/reference/starboard/modules/16/decode_target.md similarity index 84% rename from cobalt/site/docs/reference/starboard/modules/13/decode_target.md rename to cobalt/site/docs/reference/starboard/modules/16/decode_target.md index 2794d9ddfbe2f..c8d38a28a294b 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/16/decode_target.md @@ -12,7 +12,7 @@ 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 +* 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 @@ -21,7 +21,7 @@ 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. -## 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 @@ -33,51 +33,7 @@ to run arbitrary code on the application's renderer thread 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(). -The primary usage is likely to be the the SbPlayer implementation on some -platforms. - -## SbDecodeTarget Example - -Let's say that we are an application and we would like to use the interface -defined in starboard/image.h to decode an imaginary "image/foo" image type. - -First, the application 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 (SbImageIsDecodeSupported("image/foo", kPreferredFormats[i])) { - format = kPreferredFormats[i]; - break; - } -} - -``` - -Now that the application 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 = SbImageDecode( - context_provider, encoded_foo_data, encoded_foo_data_size, - "image/foo", format); - -// If the decode works, you can get the texture out and render it. -SbDecodeTargetInfo info; -memset(&info, 0, sizeof(info)); -SbDecodeTargetGetInfo(target, &info); -GLuint texture = - info.planes[kSbDecodeTargetPlaneRGBA].texture; -``` +The primary usage is likely to be the SbPlayer implementation on some platforms. ## Macros @@ -117,14 +73,19 @@ premultiplied unless otherwise explicitly specified. A decoder target format consisting of 10bit Y, U, and V planes, in that order. Each pixel is stored in 16 bits. +* `kSbDecodeTargetFormat3Plane10BitYUVI420Compact` + + A decoder target format consisting of 10bit Y, U, and V planes, in that + order. The plane data is stored in a compact format. Every three 10-bit + pixels are packed into 32 bits. * `kSbDecodeTargetFormat1PlaneUYVY` 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 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 format with GL - platforms, it is expected that the underlying texture will be set to the + 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). Content region left/right should be specified in u/v width resolution. @@ -202,8 +163,7 @@ information about the graphics context that will be used to render SbDecodeTargets. Some Starboard implementations may need to have references to some graphics objects when creating/destroying resources used by SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects should be provided -to all Starboard functions that might create SbDecodeTargets (e.g. -SbImageDecode()). +to all Starboard functions that might create SbDecodeTargets. #### Members @@ -211,12 +171,12 @@ SbImageDecode()). 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. + `void*` in order to avoid including the EGL header files here. * `void * egl_context` 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. + including the EGL header files here. * `SbDecodeTargetGlesContextRunner gles_context_runner` The `gles_context_runner` function pointer is passed in from the application @@ -259,7 +219,7 @@ This can be queried via calls to SbDecodeTargetGetInfo(). * `SbDecodeTargetInfoPlane planes` The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY, - kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode + kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this decode target. ### SbDecodeTargetInfoContentRegion @@ -363,8 +323,7 @@ static bool SbDecodeTargetIsValid(SbDecodeTarget handle) 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. In the case where SB_HAS(GLES2), this function must be called -on a thread with the context +reference count. This function must be called on a thread with the context. #### Declaration @@ -395,3 +354,4 @@ Starboard implementations, if it is necessary. ``` static void SbDecodeTargetRunInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTargetGlesContextRunnerTarget target, void *target_context) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/directory.md b/cobalt/site/docs/reference/starboard/modules/16/directory.md similarity index 80% rename from cobalt/site/docs/reference/starboard/modules/13/directory.md rename to cobalt/site/docs/reference/starboard/modules/16/directory.md index 6f845f6567a9c..748da304a3282 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/16/directory.md @@ -25,18 +25,6 @@ typedef struct SbDirectoryPrivate* SbDirectory ## Functions -### SbDirectoryCanOpen - -Indicates whether SbDirectoryOpen is allowed for the given `path`. - -`path`: The path to be checked. - -#### Declaration - -``` -bool SbDirectoryCanOpen(const char *path) -``` - ### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the @@ -50,20 +38,6 @@ directory was closed successfully. bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate - -Creates the directory `path`, assuming the parent directory already exists. This -function returns `true` if the directory now exists (even if it existed before) -and returns `false` if the directory does not exist. - -`path`: The path to be created. - -#### Declaration - -``` -bool SbDirectoryCreate(const char *path) -``` - ### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and @@ -115,3 +89,4 @@ that the directory could not be opened. ``` SbDirectory SbDirectoryOpen(const char *path, SbFileError *out_error) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/drm.md b/cobalt/site/docs/reference/starboard/modules/16/drm.md similarity index 78% rename from cobalt/site/docs/reference/starboard/modules/13/drm.md rename to cobalt/site/docs/reference/starboard/modules/16/drm.md index f42e43bf3db71..47cf7ef55b8a8 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/16/drm.md @@ -29,7 +29,7 @@ Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. ### SbDrmKeyStatus -Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) +Status of a particular media key. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus) #### Values @@ -67,8 +67,9 @@ The status of session related operations. Used by * `kSbDrmStatusQuotaExceededError` * `kSbDrmStatusUnknownError` - 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. ## Typedefs @@ -85,7 +86,7 @@ typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void ### SbDrmSessionClosedFunc -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. #### Definition @@ -96,8 +97,15 @@ typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, c ### SbDrmSessionKeyStatusesChangedFunc 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. #### Definition @@ -119,6 +127,7 @@ context that was passed into the call to SbDrmCreateSystem(). `error_message` may contain an optional error message when `status` isn't `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. @@ -246,6 +255,50 @@ Clear any internal states/resources related to the specified `session_id`. void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` +### SbDrmCreateSystem + +Creates a new DRM system that can be used when constructing an SbPlayer or an +SbDecoder. + +This function returns `kSbDrmSystemInvalid` if `key_system` is unsupported. + +Also see the documentation of SbDrmGenerateSessionUpdateRequest() and +SbDrmUpdateSession() for more details. + +`key_system`: The DRM key system to be created. The value should be in the 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. Note the key +system will be matched case sensitive. For more details, refer to [https://w3c.github.io/encrypted-media/#dfn-key-system-s](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 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. + +#### Declaration + +``` +SbDrmSystem SbDrmCreateSystem(const char *key_system, void *context, SbDrmSessionUpdateRequestFunc update_request_callback, SbDrmSessionUpdatedFunc session_updated_callback, SbDrmSessionKeyStatusesChangedFunc key_statuses_changed_callback, SbDrmServerCertificateUpdatedFunc server_certificate_updated_callback, SbDrmSessionClosedFunc session_closed_callback) +``` + ### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and @@ -292,9 +345,12 @@ establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used. `type`: The case-sensitive type of the session update request payload. Must not -be NULL. `initialization_data`: The data for which the session update request -payload is created. Must not be NULL. `initialization_data_size`: The size of -the session update request payload. +be NULL. + +`initialization_data`: The data for which the session update request payload is +created. Must not be NULL. + +`initialization_data_size`: The size of the session update request payload. #### Declaration @@ -375,14 +431,18 @@ 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`. `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. `certificate`: Pointer to the server -certificate data. Must not be NULL. `certificate_size`: Size of the server -certificate data. +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. + +`certificate`: Pointer to the server certificate data. Must not be NULL. + +`certificate_size`: Size of the server certificate data. #### Declaration @@ -415,3 +475,4 @@ must not be NULL. ``` void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/egl.md b/cobalt/site/docs/reference/starboard/modules/16/egl.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/egl.md rename to cobalt/site/docs/reference/starboard/modules/16/egl.md index 4afff1aa236ef..87deff271ad91 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/16/egl.md @@ -144,3 +144,4 @@ typedef int32_t SbEglInt32 config, void *native_pixmap, const SbEglAttrib *attrib_list)` * `SbEglBoolean(*eglWaitSync)(SbEglDisplay dpy, SbEglSync sync, SbEglInt32 flags)` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/event.md b/cobalt/site/docs/reference/starboard/modules/16/event.md similarity index 95% rename from cobalt/site/docs/reference/starboard/modules/13/event.md rename to cobalt/site/docs/reference/starboard/modules/16/event.md index 256d418b45e00..1f61995e9c1d8 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/event.md +++ b/cobalt/site/docs/reference/starboard/modules/16/event.md @@ -236,16 +236,9 @@ the type of the value pointed to by that data argument, if any. triggered by the application have tickets passed in via SbWindowBlurOnScreenKeyboard. System-triggered events have ticket value kSbEventOnScreenKeyboardInvalidTicket. -* `kSbEventTypeOnScreenKeyboardSuggestionsUpdated` - - The platform has updated the on screen keyboard suggestions. This event is - triggered by the system or by the application's OnScreenKeyboard update - suggestions method. The event has int data representing a ticket. The ticket - is used by the application to mark individual calls to the update - suggestions method as successfully completed. Events triggered by the - application have tickets passed in via - SbWindowUpdateOnScreenKeyboardSuggestions. System-triggered events have - ticket value kSbEventOnScreenKeyboardInvalidTicket. +* `kSbEventTypeReserved1` + + Reserved for deprecated events. * `kSbEventTypeAccessibilityCaptionSettingsChanged` One or more of the fields returned by SbAccessibilityGetCaptionSettings has @@ -313,7 +306,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -372,7 +365,7 @@ just dispatch it over to another thread. #### Declaration ``` -SB_IMPORT void SbEventHandle(const SbEvent *event) +SB_EXPORT_PLATFORM void SbEventHandle(const SbEvent *event) ``` ### SbEventIsIdValid @@ -399,5 +392,17 @@ of microseconds to wait before calling the `callback` function. Set `delay` to #### Declaration ``` -SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) +SbEventId SbEventSchedule(SbEventCallback callback, void *context, int64_t delay) ``` + +### SbRunStarboardMain + +Serves as the entry point in the Starboard library for running the Starboard +event loop with the application event handler. + +#### Declaration + +``` +int SbRunStarboardMain(int argc, char **argv, SbEventHandleCallback callback) +``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/export.md b/cobalt/site/docs/reference/starboard/modules/16/export.md similarity index 100% rename from cobalt/site/docs/reference/starboard/modules/13/export.md rename to cobalt/site/docs/reference/starboard/modules/16/export.md diff --git a/cobalt/site/docs/reference/starboard/modules/13/file.md b/cobalt/site/docs/reference/starboard/modules/16/file.md similarity index 96% rename from cobalt/site/docs/reference/starboard/modules/13/file.md rename to cobalt/site/docs/reference/starboard/modules/16/file.md index 103af475ace1b..5371e0324ade1 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/file.md +++ b/cobalt/site/docs/reference/starboard/modules/16/file.md @@ -124,15 +124,15 @@ Used to hold information about a file. * `bool is_symbolic_link` Whether the file corresponds to a symbolic link. -* `SbTime last_modified` +* `int64_t last_modified` - The last modified time of a file. -* `SbTime last_accessed` + The last modified time of a file - microseconds since Windows epoch UTC. +* `int64_t last_accessed` - The last accessed time of a file. -* `SbTime creation_time` + The last accessed time of a file - microseconds since Windows epoch UTC. +* `int64_t creation_time` - The creation time of a file. + The creation time of a file - microseconds since Windows epoch UTC. ## Functions @@ -192,18 +192,6 @@ fails if the file in question is being held open. bool SbFileDelete(const char *path) ``` -### SbFileExists - -Indicates whether a file or directory exists at `path`. - -`path`: The absolute path of the file or directory being checked. - -#### Declaration - -``` -bool SbFileExists(const char *path) -``` - ### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not @@ -402,3 +390,4 @@ The return value identifies the number of bytes written, or `-1` on error. ``` static int SbFileWriteAll(SbFile file, const char *data, int size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/gles.md b/cobalt/site/docs/reference/starboard/modules/16/gles.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/gles.md rename to cobalt/site/docs/reference/starboard/modules/16/gles.md index 77bc07e71c82d..049838f80b659 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/16/gles.md @@ -459,3 +459,4 @@ typedef long int SbGlIntPtr internalformat, SbGlSizei width, SbGlSizei height, SbGlSizei depth)` * `void(*glGetInternalformativ)(SbGlEnum target, SbGlEnum internalformat, SbGlEnum pname, SbGlSizei bufSize, SbGlInt32 *params)` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/input.md b/cobalt/site/docs/reference/starboard/modules/16/input.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/input.md rename to cobalt/site/docs/reference/starboard/modules/16/input.md index a858c73e3e898..d2dd2db32dc58 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/input.md +++ b/cobalt/site/docs/reference/starboard/modules/16/input.md @@ -168,3 +168,4 @@ A 2-dimensional vector used to represent points and motion vectors. * `float x` * `float y` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/key.md b/cobalt/site/docs/reference/starboard/modules/16/key.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/key.md rename to cobalt/site/docs/reference/starboard/modules/16/key.md index dd7712fd81bbb..c07837e233c87 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/key.md +++ b/cobalt/site/docs/reference/starboard/modules/16/key.md @@ -196,6 +196,7 @@ virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windo * `kSbKeyGreen` * `kSbKeyYellow` * `kSbKeyBlue` +* `kSbKeyRecord` * `kSbKeyChannelUp` * `kSbKeyChannelDown` * `kSbKeySubtitle` @@ -290,3 +291,4 @@ Bit-mask of key modifiers. * `kSbKeyModifiersPointerButtonMiddle` * `kSbKeyModifiersPointerButtonBack` * `kSbKeyModifiersPointerButtonForward` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/log.md b/cobalt/site/docs/reference/starboard/modules/16/log.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/log.md rename to cobalt/site/docs/reference/starboard/modules/16/log.md index 6cf3a491a2a75..60b361d4697d2 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/log.md +++ b/cobalt/site/docs/reference/starboard/modules/16/log.md @@ -134,3 +134,4 @@ Inline wrapper of SbLogFormat to convert from ellipsis to va_args. ``` void static void static void SbLogRawFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/media.md b/cobalt/site/docs/reference/starboard/modules/16/media.md similarity index 75% rename from cobalt/site/docs/reference/starboard/modules/13/media.md rename to cobalt/site/docs/reference/starboard/modules/16/media.md index acf95ee1ef9ab..408b757390592 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/media.md +++ b/cobalt/site/docs/reference/starboard/modules/16/media.md @@ -30,6 +30,10 @@ Types of audio elementary streams that can be supported. * `kSbMediaAudioCodecEac3` * `kSbMediaAudioCodecOpus` * `kSbMediaAudioCodecVorbis` +* `kSbMediaAudioCodecMp3` +* `kSbMediaAudioCodecFlac` +* `kSbMediaAudioCodecPcm` +* `kSbMediaAudioCodecIamf` ### SbMediaAudioCodingType @@ -55,11 +59,20 @@ Possible audio connector types. #### Values -* `kSbMediaAudioConnectorNone` +* `kSbMediaAudioConnectorUnknown` * `kSbMediaAudioConnectorAnalog` * `kSbMediaAudioConnectorBluetooth` +* `kSbMediaAudioConnectorBuiltIn` * `kSbMediaAudioConnectorHdmi` -* `kSbMediaAudioConnectorNetwork` +* `kSbMediaAudioConnectorRemoteWired` + + A wired remote audio output, like a remote speaker via Ethernet. +* `kSbMediaAudioConnectorRemoteWireless` + + A wireless remote audio output, like a remote speaker via Wi-Fi. +* `kSbMediaAudioConnectorRemoteOther` + + A remote audio output cannot be classified into other existing types. * `kSbMediaAudioConnectorSpdif` * `kSbMediaAudioConnectorUsb` @@ -170,14 +183,11 @@ output. #### Members -* `int index` - - The platform-defined index of the associated audio output. * `SbMediaAudioConnector connector` - The type of audio connector. Will be the empty `kSbMediaAudioConnectorNone` - if this device cannot provide this information. -* `SbTime latency` + The type of audio connector. Will be `kSbMediaAudioConnectorUnknown` if this + device cannot provide this information. +* `int64_t latency` The expected latency of audio over this output, in microseconds, or `0` if this device cannot provide this information. @@ -192,13 +202,19 @@ output. ### SbMediaAudioSampleInfo -An audio sample info, which is a description of a given audio sample. This acts -as a set of instructions to the audio decoder. +The set of information required by the decoder or player for each audio sample. + +#### Members + +* `SbMediaAudioStreamInfo stream_info` -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](http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx)x) . + The set of information of the video stream associated with this sample. +* `int64_t discarded_duration_from_front` +* `int64_t discarded_duration_from_back` + +### SbMediaAudioStreamInfo + +The set of information required by the decoder or player for each audio stream. #### Members @@ -210,21 +226,12 @@ Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at 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. -* `uint16_t format_tag` - - The waveform-audio format type code. * `uint16_t number_of_channels` The number of audio channels in this format. `1` for mono, `2` for stereo. * `uint32_t samples_per_second` The sampling rate. -* `uint32_t average_bytes_per_second` - - The number of bytes per second expected with this format. -* `uint16_t block_alignment` - - Byte block alignment, e.g., 4. * `uint16_t bits_per_sample` The bit depth for the stream this represents, e.g. `8` or `16`. @@ -233,14 +240,13 @@ Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at The size, in bytes, of the audio_specific_config. * `const void * audio_specific_config` - 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](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. ### SbMediaColorMetadata 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](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) +luminosity than is possible with standard digital imaging. #### Members @@ -373,6 +379,20 @@ The set of information required by the decoder or player for each video sample. #### Members +* `SbMediaVideoStreamInfo stream_info` + + The set of information of the video stream associated with this sample. +* `bool is_key_frame` + + Indicates whether the associated sample is a key frame (I-frame). Avc video + key frames must always start with SPS and PPS NAL units. + +### SbMediaVideoStreamInfo + +The set of information required by the decoder or player for each video stream. + +#### Members + * `SbMediaVideoCodec codec` The video codec of this sample. @@ -393,10 +413,6 @@ The set of information required by the decoder or player for each video sample. second higher than 15 fps. When the maximums are unknown, this will be set to an empty string. It can only be set to NULL when `codec` is kSbMediaVideoCodecNone. -* `bool is_key_frame` - - Indicates whether the associated sample is a key frame (I-frame). Video key - frames must always start with SPS and PPS NAL units. * `int frame_width` The frame width of this sample, in pixels. Also could be parsed from the @@ -430,10 +446,12 @@ Note that neither `mime` nor `key_system` can be NULL. This function returns `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. `key_system`: A lowercase value in the form -of "com.example.somesystem" as suggested by [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system)) that can +than one codec, delimited by comma. + +`key_system`: A lowercase value in the form of "com.example.somesystem", and 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. +For more detail, refer to [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system) An implementation may choose to support `key_system` with extra attributes, separated by ';', like `com.example.somesystem; attribute_name1="value1"; @@ -445,23 +463,21 @@ 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` 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` encryptionScheme of -MediaKeySystemMediaCapability, as defined in [https://wicg.github.io/encrypted-media-encryption-scheme/,](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` kSbMediaSupportTypeNotSupported when +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. It 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` 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` kSbMediaSupportTypeProbably when +`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` 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. +`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. For more detail, refer to [https://wicg.github.io/encrypted-media-encryption-scheme](https://wicg.github.io/encrypted-media-encryption-scheme) #### Declaration @@ -514,25 +530,15 @@ least stereo. int SbMediaGetAudioOutputCount() ``` -### SbMediaGetBufferAlignment - -The media buffer will be allocated using the returned alignment. Set this to a -larger value may increase the memory consumption of media buffers.`type`: the -media type of the stream (audio or video). - -#### Declaration - -``` -int SbMediaGetBufferAlignment(SbMediaType type) -``` - ### SbMediaGetBufferAllocationUnit -When the media stack needs more memory to store media buffers, it will allocate -extra memory in units returned by SbMediaGetBufferAllocationUnit. This can -return 0, in which case the media stack will allocate extra memory on demand. -When SbMediaGetInitialBufferCapacity and this function both return 0, the media -stack will allocate individual buffers directly using SbMemory functions. +The media buffer will be allocated using the returned alignment. Set this to a +larger value may increase the memory consumption of media buffers. When the +media stack needs more memory to store media buffers, it will allocate extra +memory in units returned by SbMediaGetBufferAllocationUnit. This can return 0, +in which case the media stack will allocate extra memory on demand. When +SbMediaGetInitialBufferCapacity and this function both return 0, the media stack +will allocate individual buffers directly using malloc functions. #### Declaration @@ -542,47 +548,31 @@ int SbMediaGetBufferAllocationUnit() ### SbMediaGetBufferGarbageCollectionDurationThreshold -Specifies the duration threshold of media source garbage collection. When the -accumulated duration in a source buffer exceeds this value, the media source -implementation will try to eject existing buffers from the cache. This is -usually triggered when the video being played has a simple content and the -encoded data is small. In such case this can limit how much is allocated for the -book keeping data of the media buffers and avoid OOM of system heap. This should -return 170 seconds for most of the platforms. But it can be further reduced on -systems with extremely low memory. +Specifies the duration threshold of media source garbage collection in +microseconds. When the accumulated duration in a source buffer exceeds this +value, the media source implementation will try to eject existing buffers from +the cache. This is usually triggered when the video being played has a simple +content and the encoded data is small. In such case this can limit how much is +allocated for the book keeping data of the media buffers and avoid OOM of system +heap. This should return 170 seconds for most of the platforms. But it can be +further reduced on systems with extremely low memory. #### Declaration ``` -SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() +int64_t SbMediaGetBufferGarbageCollectionDurationThreshold() ``` ### SbMediaGetBufferPadding Extra bytes allocated at the end of a media buffer to ensure that the buffer can be use optimally by specific instructions like SIMD. Set to 0 to remove any -padding.`type`: the media type of the stream (audio or video). - -#### Declaration - -``` -int SbMediaGetBufferPadding(SbMediaType type) -``` - -### SbMediaGetBufferStorageType - -Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or -`SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored -in main memory allocated by SbMemory functions. For file storage, the media -buffers will be stored in a temporary file in the system cache folder acquired -by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when -its value is "file" the media stack will still allocate memory to cache the the -buffers in use. +padding. #### Declaration ``` -SbMediaBufferStorageType SbMediaGetBufferStorageType() +int SbMediaGetBufferPadding() ``` ### SbMediaGetInitialBufferCapacity @@ -608,10 +598,14 @@ allocation of media buffers may only fail when there is not enough memory in the system to fulfill the request, under which case the 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. +`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. #### Declaration @@ -626,10 +620,14 @@ resolution of such videos shouldn't go beyond 1080p. Its value should be less than the sum of SbMediaGetAudioBufferBudget and '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. +`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. #### Declaration @@ -645,10 +643,14 @@ being used by video buffers but will also make app less likely to re-download video data. Note that the app may experience significant difficulty if this 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. +`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. #### Declaration @@ -676,7 +678,7 @@ bool SbMediaIsBufferPoolAllocateOnDemand() ### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer -pools should be allocated on demand, as opposed to using SbMemory* functions. +pools should be allocated on demand, as opposed to using malloc functions. #### Declaration @@ -684,20 +686,3 @@ pools should be allocated on demand, as opposed to using SbMemory* functions. bool SbMediaIsBufferUsingMemoryPool() ``` -### SbMediaSetAudioWriteDuration - -Communicate to the platform how far past `current_playback_position` the app -will write audio samples. The app will write all samples between -`current_playback_position` and `current_playback_position` + `duration`, as -soon as they are available. The app may sometimes write more samples than that, -but the app only guarantees to write `duration` past `current_playback_position` -in general. The platform is responsible for guaranteeing that when only -`duration` audio samples are written at a time, no playback issues occur (such -as transient or indefinite hanging). The platform may assume `duration` >= 0.5 -seconds. - -#### Declaration - -``` -void SbMediaSetAudioWriteDuration(SbTime duration) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/16/memory.md b/cobalt/site/docs/reference/starboard/modules/16/memory.md new file mode 100644 index 0000000000000..2a78fa580a672 --- /dev/null +++ b/cobalt/site/docs/reference/starboard/modules/16/memory.md @@ -0,0 +1,47 @@ +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory.h` + +Defines functions for memory allocation, alignment, copying, and comparing. + +## Porters + +All of the "Unchecked" and "Free" functions must be implemented, but they should +not be called directly. The Starboard platform wraps them with extra accounting +under certain circumstances. + +## Porters and Application Developers + +Nobody should call the "Checked", "Unchecked" or "Free" functions directly +because that evades Starboard's memory tracking. In both port implementations +and Starboard client application code, you should always call SbMemoryAllocate +and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. + +* The "checked" functions are SbMemoryAllocateChecked(), + SbMemoryReallocateChecked(), and SbMemoryAllocateAlignedChecked(). + +* The "unchecked" functions are SbMemoryAllocateUnchecked(), + SbMemoryReallocateUnchecked(), and SbMemoryAllocateAlignedUnchecked(). + +* The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). + +## Enums + +### SbMemoryMapFlags + +TODO: Remove the definition once the memory_mapped_file.h extension is +deprecated. The bitwise OR of these flags should be passed to SbMemoryMap to +indicate how the mapped memory can be used. + +#### Values + +* `kSbMemoryMapProtectReserved` + + No flags set: Reserves virtual address space. SbMemoryProtect() can later + make it accessible. +* `kSbMemoryMapProtectRead` +* `kSbMemoryMapProtectWrite` +* `kSbMemoryMapProtectExec` +* `kSbMemoryMapProtectReadWrite` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/microphone.md b/cobalt/site/docs/reference/starboard/modules/16/microphone.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/microphone.md rename to cobalt/site/docs/reference/starboard/modules/16/microphone.md index bcf9e4355e65c..497cbe91cec43 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/16/microphone.md @@ -260,3 +260,4 @@ has already been read from the device is discarded. ``` int SbMicrophoneRead(SbMicrophone microphone, void *out_audio_data, int audio_data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/16/player.md b/cobalt/site/docs/reference/starboard/modules/16/player.md new file mode 100644 index 0000000000000..837dd941d1ea6 --- /dev/null +++ b/cobalt/site/docs/reference/starboard/modules/16/player.md @@ -0,0 +1,738 @@ +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `player.h` + +Defines an interface for controlling playback of media elementary streams. + +## Macros + +### SB_PLAYER_INITIAL_TICKET + +The value of the initial ticket held by the player before the first seek. The +player will use this ticket value to make the first call to SbPlayerStatusFunc +with kSbPlayerStateInitialized. + +### SB_PLAYER_NO_DURATION + +The value to pass into SbPlayerCreate's `duration_pts` argument for cases where +the duration is unknown, such as for live streams. + +### kSbPlayerInvalid + +Well-defined value for an invalid player. + +### kSbPlayerWriteDurationLocal + +The audio write duration when all the audio connectors are local. + +### kSbPlayerWriteDurationRemote + +The audio write duration when at least one of the audio connectors are remote. + +## Enums + +### SbPlayerDecoderState + +An indicator of whether the decoder can accept more samples. + +#### Values + +* `kSbPlayerDecoderStateNeedsData` + + The decoder is asking for one more sample. + +### SbPlayerSampleSideDataType + +Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side +data may come from multiple sources. + +#### Values + +* `kMatroskaBlockAdditional` + + The side data comes from the BlockAdditional data in the Matroska/Webm + container. The first 8 bytes of the data contains the value of BlockAddID in + big endian format, followed by the content of BlockAdditional. See: + + [https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03](https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03) + + [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional) + +### SbPlayerState + +An indicator of the general playback state. + +#### Values + +* `kSbPlayerStateInitialized` + + The player has just been initialized. It is expecting an SbPlayerSeek() call + to enter the prerolling state. +* `kSbPlayerStatePrerolling` + + The player is prerolling, collecting enough data to fill the pipeline before + presentation starts. After the first preroll is completed, there should + always be a video frame to render, even if the player goes back to + Prerolling after a Seek. +* `kSbPlayerStatePresenting` + + The player is presenting media, and it is either paused or actively playing + in real-time. Note that the implementation should use this state to signal + that the preroll has been finished. +* `kSbPlayerStateEndOfStream` + + The player is presenting media, but it is paused at the end of the stream. +* `kSbPlayerStateDestroyed` + + The player has been destroyed, and will send no more callbacks. + +## Typedefs + +### SbPlayer + +An opaque handle to an implementation-private structure representing a player. + +#### Definition + +``` +typedef struct SbPlayerPrivate* SbPlayer +``` + +### SbPlayerDeallocateSampleFunc + +Callback to free the given sample buffer data. When more than one buffer are +sent in SbPlayerWriteSample(), the implementation only has to call this callback +with `sample_buffer` points to the first buffer. + +#### Definition + +``` +typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) +``` + +### SbPlayerDecoderStatusFunc + +Callback for decoder status updates, called in response to a call to +SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called +until at least one call to SbPlayerSeek has occurred. `ticket` will be set to +the ticket passed into the last received call to SbPlayerSeek() at the time this +callback was dispatched. This is to distinguish status callbacks for +interrupting seeks. These callbacks will happen on a different thread than the +calling thread, and it is not valid to call SbPlayer functions from within this +callback. After an update with kSbPlayerDecoderStateNeedsData, the user of the +player will make at most one call to SbPlayerWriteSample() or +SbPlayerWriteEndOfStream(). The player implementation should update the decoder +status again after such call to notify its user to continue writing more frames. + +#### Definition + +``` +typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) +``` + +### SbPlayerErrorFunc + +Callback for player errors, that may set a `message`. + +`error`: indicates the error code. + +`message`: provides specific informative diagnostic message about the error +condition encountered. It is ok for the message to be an empty string or NULL if +no information is available. + +#### Definition + +``` +typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) +``` + +### SbPlayerStatusFunc + +Callback for player status updates. These callbacks will happen on a different +thread than the calling thread, and it is not valid to call SbPlayer functions +from within this callback. + +#### Definition + +``` +typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) +``` + +## Structs + +### SbPlayerCreationParam + +The playback related parameters to pass into SbPlayerCreate() and +SbPlayerGetPreferredOutputMode(). + +#### Members + +* `SbDrmSystem drm_system` + + Provides an appropriate DRM system if the media stream has encrypted + portions. It will be `kSbDrmSystemInvalid` if the stream does not have + encrypted portions. +* `SbMediaAudioStreamInfo audio_stream_info` + + Contains a populated SbMediaAudioStreamInfo if `audio_stream_info.codec` + isn't `kSbMediaAudioCodecNone`. When `audio_stream_info.codec` is + `kSbMediaAudioCodecNone`, the video doesn't have an audio track. +* `SbMediaVideoStreamInfo video_stream_info` + + Contains a populated SbMediaVideoStreamInfo if `video_stream_info.codec` + isn't `kSbMediaVideoCodecNone`. When `video_stream_info.codec` is + `kSbMediaVideoCodecNone`, the video is audio only. +* `SbPlayerOutputMode output_mode` + + Selects how the decoded video frames will be output. For example, + `kSbPlayerOutputModePunchOut` indicates that the decoded video frames will + be output to a background video layer by the platform, and + `kSbPlayerOutputDecodeToTexture` indicates that the decoded video frames + should be made available for the application to pull via calls to + SbPlayerGetCurrentFrame(). + +### SbPlayerInfo + +Information about the current media playback state. + +#### Members + +* `int64_t current_media_timestamp` + + The position of the playback head, as precisely as possible, in + microseconds. +* `int64_t duration` + + The known duration of the currently playing media stream, in microseconds. +* `int64_t start_date` + + The result of getStartDate for the currently playing media stream, in + microseconds since the epoch of January 1, 1601 UTC. +* `int frame_width` + + The width of the currently displayed frame, in pixels, or 0 if not provided + by this player. +* `int frame_height` + + The height of the currently displayed frame, in pixels, or 0 if not provided + by this player. +* `bool is_paused` + + Whether playback is currently paused. +* `double volume` + + The current player volume in [0, 1]. +* `int total_video_frames` + + The number of video frames sent to the player since the creation of the + player. +* `int dropped_video_frames` + + The number of video frames decoded but not displayed since the creation of + the player. +* `int corrupted_video_frames` + + The number of video frames that failed to be decoded since the creation of + the player. +* `double playback_rate` + + The rate of playback. The video is played back in a speed that is + proportional to this. By default it is 1.0 which indicates that the playback + is at normal speed. When it is greater than one, the video is played in a + faster than normal speed. When it is less than one, the video is played in a + slower than normal speed. Negative speeds are not supported. + +### SbPlayerSampleInfo + +Information about the samples to be written into SbPlayerWriteSamples(). + +#### Members + +* `SbMediaType type` +* `const void * buffer` + + Points to the buffer containing the sample data. +* `int buffer_size` + + Size of the data pointed to by `buffer`. +* `int64_t timestamp` + + The timestamp of the sample in microseconds since Windows epoch UTC. +* `SbPlayerSampleSideData* side_data` + + Points to an array of side data for the input, when available. +* `int side_data_count` + + The number of side data pointed by `side_data`. It should be set to 0 if + there is no side data for the input. +* `SbMediaAudioSampleInfo audio_sample_info` + + Information about an audio sample. This value can only be used when `type` + is kSbMediaTypeAudio. +* `SbMediaVideoSampleInfo video_sample_info` + + Information about a video sample. This value can only be used when `type` is + kSbMediaTypeVideo. +* `union SbPlayerSampleInfo::@0 @1` +* `constSbDrmSampleInfo* drm_info` + + The DRM system related info for the media sample. This value is required for + encrypted samples. Otherwise, it must be `NULL`. + +### SbPlayerSampleSideData + +Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data +coming from multiple sources. + +#### Members + +* `SbPlayerSampleSideDataType type` +* `const uint8_t * data` + + `data` will remain valid until SbPlayerDeallocateSampleFunc() is called on + the `SbPlayerSampleInfo::buffer` the data is associated with. +* `size_t size` + + The size of the data pointed by `data`, in bytes. + +## Functions + +### SbPlayerCreate + +Creates a player that will be displayed on `window` for the specified +`video_codec` and `audio_codec`, acquiring all resources needed to operate it, +and returning an opaque handle to it. The expectation is that a new player will +be created and destroyed for every playback. + +This function returns the created player. Note the following: + +* The associated decoder of the returned player should be assumed to not be in + `kSbPlayerDecoderStateNeedsData` until SbPlayerSeek() has been called on it. + +* It is expected either that the thread that calls SbPlayerCreate is the same + thread that calls the other `SbPlayer` functions for that player, or that + there is a mutex guarding calls into each `SbPlayer` instance. + +* If there is a platform limitation on how many players can coexist + simultaneously, then calls made to this function that attempt to exceed that + limit must return `kSbPlayerInvalid`. Multiple calls to SbPlayerCreate must + not cause a crash. + +`window`: The window that will display the player. `window` can be +`kSbWindowInvalid` for platforms where video is only displayed on a particular +window that the underlying implementation already has access to. + +`video_codec`: The video codec used for the player. If `video_codec` is +`kSbMediaVideoCodecNone`, the player is an audio-only player. If `video_codec` +is any other value, the player is an audio/video decoder. This can be set to +`kSbMediaVideoCodecNone` to play a video with only an audio track. + +`audio_codec`: The audio codec used for the player. The caller must provide a +populated `audio_sample_info` if audio codec is `kSbMediaAudioCodecAac`. Can be +set to `kSbMediaAudioCodecNone` to play a video without any audio track. In such +case `audio_sample_info` must be NULL. + +`drm_system`: If the media stream has encrypted portions, then this parameter +provides an appropriate DRM system, created with `SbDrmCreateSystem()`. If the +stream does not have encrypted portions, then `drm_system` may be +`kSbDrmSystemInvalid`. + +`audio_sample_info`: Note that the caller must provide a populated +`audio_sample_info` if the audio codec is `kSbMediaAudioCodecAac`. Otherwise, +`audio_sample_info` can be NULL. See media.h for the format of the +`SbMediaAudioSampleInfo` struct. + +Note that `audio_specific_config` is a pointer and the content it points to is +no longer valid after this function returns. The implementation has to make a +copy of the content if it is needed after the function returns. + +`max_video_capabilities`: This string communicates the max video capabilities +required to the platform. The web app will not provide a video stream exceeding +the maximums described by this parameter. Allows the platform to optimize +playback pipeline for low quality video streams if it knows that it will never +adapt to higher quality streams. The string uses the same format as the string +passed in to SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to +"width=1920; height=1080; framerate=15;", the video will never adapt to +resolution higher than 1920x1080 or frame per second higher than 15 fps. When +the maximums are unknown, this will be set to NULL. + +`sample_deallocator_func`: If not `NULL`, the player calls this function on an +internal thread to free the sample buffers passed into SbPlayerWriteSample(). + +`decoder_status_func`: If not `NULL`, the decoder calls this function on an +internal thread to provide an update on the decoder's status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_status_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the playback status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_error_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the error status. This callback is +responsible for setting the media error message. + +`context`: This is passed to all callbacks and is generally used to point at a +class or struct that contains state associated with the player. + +`output_mode`: Selects how the decoded video frames will be output. For example, +kSbPlayerOutputModePunchOut indicates that the decoded video frames will be +output to a background video layer by the platform, and +kSbPlayerOutputDecodeToTexture indicates that the decoded video frames should be +made available for the application to pull via calls to +SbPlayerGetCurrentFrame(). + +`provider`: Only present in Starboard version 3 and up. If not `NULL`, then when +output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY use the +provider to create SbDecodeTargets on the renderer thread. A provider may not +always be needed by the player, but if it is needed, and the provider is not +given, the player will fail by returning `kSbPlayerInvalid`. + +If `NULL` is passed to any of the callbacks (`sample_deallocator_func`, +`decoder_status_func`, `player_status_func`, or `player_error_func` if it +applies), then `kSbPlayerInvalid` must be returned. + +#### Declaration + +``` +SbPlayer SbPlayerCreate(SbWindow window, const SbPlayerCreationParam *creation_param, SbPlayerDeallocateSampleFunc sample_deallocate_func, SbPlayerDecoderStatusFunc decoder_status_func, SbPlayerStatusFunc player_status_func, SbPlayerErrorFunc player_error_func, void *context, SbDecodeTargetGraphicsContextProvider *context_provider) +``` + +### SbPlayerDestroy + +Destroys `player`, freeing all associated resources. + +* Upon calling this method, there should be one call to the player status + callback (i.e. `player_status_func` used in the creation of the player) + which indicates the player is destroyed. Note, the callback has to be + inflight when SbPlayerDestroyed is called. + +* No more other callbacks should be issued after this function returns. + +* It is not allowed to pass `player` into any other `SbPlayer` function once + SbPlayerDestroy has been called on that player. + +`player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. + +#### Declaration + +``` +void SbPlayerDestroy(SbPlayer player) +``` + +### SbPlayerGetAudioConfiguration + +Returns the audio configurations used by `player`. + +Returns true when `out_audio_configuration` is filled with the information of +the configuration of the audio output devices used by `player`. Returns false +for `index` 0 to indicate that there is no audio output for this `player`. +Returns false for `index` greater than 0 to indicate that there are no more +audio output configurations other than the ones already returned. + +The app will use the information returned to determine audio related behaviors, +like: + +* Audio Write Duration: Audio write duration is how far past the current + playback position the app will write audio samples. The app will write all + samples between `current_playback_position` and `current_playback_position` + + `audio_write_duration`, as soon as they are available. + +* `audio_write_duration` will be to `kSbPlayerWriteDurationLocal` when all + audio configurations linked to `player` is local, or if there isn't any + audio output. It will be set to `kSbPlayerWriteDurationRemote` for remote or + wireless audio outputs, i.e. one of `kSbMediaAudioConnectorBluetooth` or + `kSbMediaAudioConnectorRemote*`. + +* The app only guarantees to write `audio_write_duration` past + `current_playback_position`, but the app is free to write more samples than + that. So the platform shouldn't rely on this for flow control. The platform + should achieve flow control by sending `kSbPlayerDecoderStateNeedsData` less + frequently. + +* The platform is responsible for guaranteeing that when only + `audio_write_duration` audio samples are written at a time, no playback + issues occur (such as transient or indefinite hanging). + +The audio configurations should be available as soon as possible, and they have +to be available when the `player` is at `kSbPlayerStatePresenting`, unless the +audio codec is `kSbMediaAudioCodecNone` or there's no written audio inputs. + +The app will set `audio_write_duration` to `kSbPlayerWriteDurationLocal` when +the audio configuration isn't available (i.e. the function returns false when +index is 0). The platform has to make the audio configuration available +immediately after the SbPlayer is created, if it expects the app to treat the +platform as using wireless audio outputs. + +Once at least one audio configurations are returned, the return values and their +orders shouldn't change during the life time of `player`. The platform may +inform the app of any changes by sending `kSbPlayerErrorCapabilityChanged` to +request a playback restart. + +`player`: The player about which information is being retrieved. Must not be +`kSbPlayerInvalid`. + +`index`: The index of the audio output configuration. Must be greater than or +equal to 0. + +`out_audio_configuration`: The information about the audio output, refer to +`SbMediaAudioConfiguration` for more details. Must not be NULL. + +#### Declaration + +``` +bool SbPlayerGetAudioConfiguration(SbPlayer player, int index, SbMediaAudioConfiguration *out_audio_configuration) +``` + +### SbPlayerGetCurrentFrame + +Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, +it will return a SbDecodeTarget representing the current frame to be rasterized. +On GLES systems, this function must be called on a thread with an EGLContext +current, and specifically the EGLContext that will be used to eventually render +the frame. If this function is called with a `player` object that was created +with an output mode other than kSbPlayerOutputModeDecodeToTexture, +kSbDecodeTargetInvalid is returned. + +`player` must not be `kSbPlayerInvalid`. + +#### Declaration + +``` +SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) +``` + +### SbPlayerGetInfo + +Gets a snapshot of the current player state and writes it to `out_player_info`. +This function may be called very frequently and is expected to be inexpensive. + +`player`: The player about which information is being retrieved. Must not be +`kSbPlayerInvalid`. + +`out_player_info`: The information retrieved for the player. + +#### Declaration + +``` +void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo *out_player_info) +``` + +### SbPlayerGetMaximumNumberOfSamplesPerWrite + +Returns the maximum number of samples that can be written in a single call to +SbPlayerWriteSamples(). Returning a value greater than one can improve +performance by allowing SbPlayerWriteSamples() to write multiple samples in one +call. + +Note that this feature is currently disabled in Cobalt where +SbPlayerWriteSamples() will always be called with one sample. + +`player`: The player for which the number is retrieved. + +`sample_type`: The type of sample for which the number is retrieved. See the +`SbMediaType` enum in media.h. + +#### Declaration + +``` +int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) +``` + +### SbPlayerGetPreferredOutputMode + +Returns the preferred output mode of the implementation when a video described +by `creation_param` is played. It is assumed that it is okay to call +SbPlayerCreate() with the same video described by `creation_param`, with its +`output_mode` member replaced by the returned output mode. When the caller has +no preference on the output mode, it will set `creation_param->output_mode` to +`kSbPlayerOutputModeInvalid`, and the implementation can return its preferred +output mode based on the information contained in `creation_param`. The caller +can also set `creation_param->output_mode` to its preferred output mode, and the +implementation should return the same output mode if it is supported, otherwise +the implementation should return an output mode that it is supported, as if +`creation_param->output_mode` is set to `kSbPlayerOutputModeInvalid` prior to +the call. Note that it is not the responsibility of this function to verify +whether the video described by `creation_param` can be played on the platform, +and the implementation should try its best effort to return a valid output mode. +`creation_param` must not be NULL. + +#### Declaration + +``` +SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) +``` + +### SbPlayerIsValid + +Returns whether the given player handle is valid. + +#### Declaration + +``` +static bool SbPlayerIsValid(SbPlayer player) +``` + +### SbPlayerSeek + +Tells the player to freeze playback (if playback has already started), reset or +flush the decoder pipeline, and go back to the Prerolling state. The player +should restart playback once it can display the frame at `seek_to_timestamp`, or +the closest it can get. (Some players can only seek to I-Frames, for example.) + +* Seek must be called before samples are sent when starting playback for the + first time, or the client never receives the + `kSbPlayerDecoderStateNeedsData` signal. + +* A call to seek may interrupt another seek. + +* After this function is called, the client should not send any more audio or + video samples until `SbPlayerDecoderStatusFunc` is called back with + `kSbPlayerDecoderStateNeedsData` for each required media type. + `SbPlayerDecoderStatusFunc` is the `decoder_status_func` callback function + that was specified when the player was created (SbPlayerCreate). + +`player`: The SbPlayer in which the seek operation is being performed. Must not +be `kSbPlayerInvalid`. + +`seek_to_timestamp`: The frame at which playback should begin. + +`ticket`: A user-supplied unique ID to be passed to all subsequent +`SbPlayerDecoderStatusFunc` calls. (That is the `decoder_status_func` callback +function specified when calling SbPlayerCreate.) + +The `ticket` value is used to filter calls that may have been in flight when +SbPlayerSeek was called. To be very specific, once SbPlayerSeek has been called +with ticket X, a client should ignore all `SbPlayerDecoderStatusFunc` calls that +do not pass in ticket X. + +#### Declaration + +``` +void SbPlayerSeek(SbPlayer player, int64_t seek_to_timestamp, int ticket) +``` + +### SbPlayerSetBounds + +Sets the player bounds to the given graphics plane coordinates. The changes do +not take effect until the next graphics frame buffer swap. The default bounds +for a player is the full screen. This function is only relevant when the +`player` is created with the kSbPlayerOutputModePunchOut output mode, and if +this is not the case then this function call can be ignored. + +This function is called on every graphics frame that changes the video bounds. +For example, if the video bounds are being animated, then this will be called at +up to 60 Hz. Since the function could be called up to once per frame, +implementors should take care to avoid related performance concerns with such +frequent calls. + +`player`: The player that is being resized. Must not be `kSbPlayerInvalid`. + +`z_index`: The z-index of the player. When the bounds of multiple players are +overlapped, the one with larger z-index will be rendered on top of the ones with +smaller z-index. + +`x`: The x-coordinate of the upper-left corner of the player. + +`y`: The y-coordinate of the upper-left corner of the player. + +`width`: The width of the player, in pixels. + +`height`: The height of the player, in pixels. + +#### Declaration + +``` +void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) +``` + +### SbPlayerSetPlaybackRate + +Set the playback rate of the `player`. `rate` is default to 1.0 which indicates +the playback is at its original speed. A `rate` greater than one will make the +playback faster than its original speed. For example, when `rate` is 2, the +video will be played at twice the speed as its original speed. A `rate` less +than 1.0 will make the playback slower than its original speed. When `rate` is +0, the playback will be paused. The function returns true when the playback rate +is set to `playback_rate` or to a rate that is close to `playback_rate` which +the implementation supports. It returns false when the playback rate is +unchanged, this can happen when `playback_rate` is negative or if it is too high +to support. + +`player` must not be `kSbPlayerInvalid`. + +#### Declaration + +``` +bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) +``` + +### SbPlayerSetVolume + +Sets the player's volume. + +`player`: The player in which the volume is being adjusted. Must not be +`kSbPlayerInvalid`. + +`volume`: The new player volume. The value must be between `0.0` and `1.0`, +inclusive. A value of `0.0` means that the audio should be muted, and a value of +`1.0` means that it should be played at full volume. + +#### Declaration + +``` +void SbPlayerSetVolume(SbPlayer player, double volume) +``` + +### SbPlayerWriteEndOfStream + +Writes a marker to `player`'s input stream of `stream_type` indicating that +there are no more samples for that media type for the remainder of this media +stream. This marker is invalidated, along with the rest of the stream's +contents, after a call to SbPlayerSeek. + +`player`: The player to which the marker is written. + +`stream_type`: The type of stream for which the marker is written. + +#### Declaration + +``` +void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) +``` + +### SbPlayerWriteSamples + +Writes samples of the given media type to `player`'s input stream. The lifetime +of `sample_infos`, and the members of its elements like `buffer`, +`video_sample_info`, and `drm_info` (as well as member `subsample_mapping` +contained inside it) are not guaranteed past the call to SbPlayerWriteSamples(). +That means that before returning, the implementation must synchronously copy any +information it wants to retain from those structures. + +SbPlayerWriteSamples() allows writing of multiple samples in one call. + +`player`: The player to which the sample is written. Must not be +`kSbPlayerInvalid`. + +`sample_type`: The type of sample being written. See the `SbMediaType` enum in +media.h. + +`sample_infos`: A pointer to an array of SbPlayerSampleInfo with +`number_of_sample_infos` elements, each holds the data for an sample, i.e. a +sequence of whole NAL Units for video, or a complete audio frame. `sample_infos` +cannot be assumed to live past the call into SbPlayerWriteSamples(), so it must +be copied if its content will be used after SbPlayerWriteSamples() returns. + +`number_of_sample_infos`: Specify the number of samples contained inside +`sample_infos`. It has to be at least one, and at most the return value of +SbPlayerGetMaximumNumberOfSamplesPerWrite(). + +#### Declaration + +``` +void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) +``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/socket.md b/cobalt/site/docs/reference/starboard/modules/16/socket.md similarity index 98% rename from cobalt/site/docs/reference/starboard/modules/13/socket.md rename to cobalt/site/docs/reference/starboard/modules/16/socket.md index 744c04e3847d2..e7f4bc9e71563 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/16/socket.md @@ -540,15 +540,15 @@ Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: If set to `true`, -then `period` specifies the minimum time (SbTime) is always in microseconds) -between keep-alive packets. If set to `false`, `period` is ignored. `period`: -The time between keep-alive packets. This value is only relevant if `value` is -`true`. +then `period` specifies the minimum time in microseconds between keep-alive +packets. If set to `false`, `period` is ignored. `period`: The time in +microseconds between keep-alive packets. This value is only relevant if `value` +is `true`. #### Declaration ``` -bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) +bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, int64_t period) ``` ### SbSocketSetTcpNoDelay @@ -583,3 +583,4 @@ option. ``` bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md b/cobalt/site/docs/reference/starboard/modules/16/socket_waiter.md similarity index 95% rename from cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md rename to cobalt/site/docs/reference/starboard/modules/16/socket_waiter.md index f1c6bd8b9f2fa..54bc7eae0645f 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/16/socket_waiter.md @@ -202,15 +202,15 @@ SbSocketWaiterWakeUp() it not called by that time. The return value indicates the reason that the socket waiter exited. This function should only be called on the thread that waits on this waiter. -`duration`: The minimum amount of time after which the socket waiter should exit -if it is not woken up before then. As with SbThreadSleep() (see thread.h), this -function may wait longer than `duration`, such as if the timeout expires while a -callback is being fired. +`duration`: The minimum amount of time in microseconds after which the socket +waiter should exit if it is not woken up before then. As with SbThreadSleep() +(see thread.h), this function may wait longer than `duration`, such as if the +timeout expires while a callback is being fired. #### Declaration ``` -SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) +SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, int64_t duration) ``` ### SbSocketWaiterWakeUp @@ -235,3 +235,4 @@ next 7 times they are called. ``` void SbSocketWaiterWakeUp(SbSocketWaiter waiter) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md b/cobalt/site/docs/reference/starboard/modules/16/speech_synthesis.md similarity index 99% rename from cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md rename to cobalt/site/docs/reference/starboard/modules/16/speech_synthesis.md index 0bd6e65b63790..ea4ad46b3f87d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/16/speech_synthesis.md @@ -49,3 +49,4 @@ when the previous utterances are complete. ``` void SbSpeechSynthesisSpeak(const char *text) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/storage.md b/cobalt/site/docs/reference/starboard/modules/16/storage.md similarity index 73% rename from cobalt/site/docs/reference/starboard/modules/13/storage.md rename to cobalt/site/docs/reference/starboard/modules/16/storage.md index f20016113be16..df71c579f0573 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/16/storage.md @@ -55,23 +55,22 @@ bool SbStorageCloseRecord(SbStorageRecord record) ### SbStorageDeleteRecord -Deletes the `SbStorageRecord` for `user` named `name`. The return value -indicates whether the record existed and was successfully deleted. If the record -did not exist or could not be deleted, the function returns `false`. +Deletes the `SbStorageRecord` named `name`. The return value indicates whether +the record existed and was successfully deleted. If the record did not exist or +could not be deleted, the function returns `false`. -If `name` is NULL, deletes the default storage record for the user, like what -would have been deleted with the previous version of SbStorageDeleteRecord. +If `name` is NULL, deletes the default storage record, like what would have been +deleted with the previous version of SbStorageDeleteRecord. -This function must not be called while the user's storage record is open. This -function performs blocking I/O on the calling thread. +This function must not be called while the storage record is open. This function +performs blocking I/O on the calling thread. -`user`: The user for whom the record will be deleted. `name`: The filesystem- -safe name of the record to open. +`name`: The filesystem-safe name of the record to open. #### Declaration ``` -bool SbStorageDeleteRecord(SbUser user, const char *name) +bool SbStorageDeleteRecord(const char *name) ``` ### SbStorageGetRecordSize @@ -99,22 +98,20 @@ static bool SbStorageIsValidRecord(SbStorageRecord record) ### SbStorageOpenRecord -Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on -the calling thread until the open is completed. If `user` is not a valid -`SbUser`, the function returns `kSbStorageInvalidRecord`. Will return an -`SbStorageRecord` of size zero if the record does not yet exist. Opening an -already-open `SbStorageRecord` has undefined behavior. +Opens and returns the SbStorageRecord named `name`, blocking I/O on the calling +thread until the open is completed. Will return an `SbStorageRecord` of size +zero if the record does not yet exist. Opening an already-open `SbStorageRecord` +has undefined behavior. -If `name` is NULL, opens the default storage record for the user, like what -would have been saved with the previous version of SbStorageOpenRecord. +If `name` is NULL, opens the default storage record, like what would have been +saved with the previous version of SbStorageOpenRecord. -`user`: The user for which the storage record will be opened. `name`: The -filesystem-safe name of the record to open. +`name`: The filesystem-safe name of the record to open. #### Declaration ``` -SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) +SbStorageRecord SbStorageOpenRecord(const char *name) ``` ### SbStorageReadRecord @@ -156,3 +153,4 @@ after a short time, even if there is an unexpected process termination before ``` bool SbStorageWriteRecord(SbStorageRecord record, const char *data, int64_t data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/system.md b/cobalt/site/docs/reference/starboard/modules/16/system.md similarity index 93% rename from cobalt/site/docs/reference/starboard/modules/13/system.md rename to cobalt/site/docs/reference/starboard/modules/16/system.md index d3052d1ccde12..04fceecbe83ea 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/system.md +++ b/cobalt/site/docs/reference/starboard/modules/16/system.md @@ -26,56 +26,6 @@ behavior of other APIs within the bounds of their operating range. only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call. -### SbSystemConnectionType - -Enumeration of network connection types. - -#### Values - -* `kSbSystemConnectionTypeWired` - - The system is on a wired connection. -* `kSbSystemConnectionTypeWireless` - - The system is on a wireless connection. -* `kSbSystemConnectionTypeUnknown` - - The system connection type is unknown. - -### SbSystemDeviceType - -Enumeration of device types. - -#### Values - -* `kSbSystemDeviceTypeBlueRayDiskPlayer` - - Blue-ray Disc Player (BDP). -* `kSbSystemDeviceTypeGameConsole` - - A relatively high-powered TV device used primarily for playing games. -* `kSbSystemDeviceTypeOverTheTopBox` - - Over the top (OTT) devices stream content via the Internet over another type - of network, e.g. cable or satellite. -* `kSbSystemDeviceTypeSetTopBox` - - Set top boxes (STBs) stream content primarily over cable or satellite. Some - STBs can also stream OTT content via the Internet. -* `kSbSystemDeviceTypeTV` - - A Smart TV is a TV that can directly run applications that stream OTT - content via the Internet. -* `kSbSystemDeviceTypeDesktopPC` - - Desktop PC. -* `kSbSystemDeviceTypeAndroidTV` - - An Android TV Device. -* `kSbSystemDeviceTypeUnknown` - - Unknown device. - ### SbSystemPathId Enumeration of special paths that the platform can define. @@ -106,9 +56,6 @@ Enumeration of special paths that the platform can define. * `kSbSystemPathTempDirectory` Path to a directory where temporary files can be written. -* `kSbSystemPathTestOutputDirectory` - - Path to a directory where test results can be written. * `kSbSystemPathExecutableFile` Full path to the executable file. @@ -195,6 +142,19 @@ string generation. * `kSbSystemPropertyUserAgentAuxField` A field that, if available, is appended to the user agent +* `kSbSystemPropertyAdvertisingId` + + Advertising ID or IFA, typically a 128-bit UUID Please see [https://iabtechlab.com/OTT-IFA](https://iabtechlab.com/OTT-IFA) for + details. Corresponds to 'ifa' field. Note: `ifa_type` ifa_type field is not + provided. +* `kSbSystemPropertyLimitAdTracking` + + Limit advertising tracking, treated as boolean. Set to nonzero to indicate a + true value. Corresponds to 'lmt' field. +* `kSbSystemPropertyDeviceType` + + Type of the device, e.g. such as "TV", "STB", "OTT" Please see Youtube + Technical requirements for a full list of allowed values ## Typedefs @@ -264,26 +224,6 @@ Clears the last error set by a Starboard call in the current thread. void SbSystemClearLastError() ``` -### SbSystemGetConnectionType - -Returns the device's current network connection type. - -#### Declaration - -``` -SbSystemConnectionType SbSystemGetConnectionType() -``` - -### SbSystemGetDeviceType - -Returns the type of the device. - -#### Declaration - -``` -SbSystemDeviceType SbSystemGetDeviceType() -``` - ### SbSystemGetErrorString Generates a human-readable string for an error. The return value specifies the @@ -730,3 +670,4 @@ signal-safe on platforms that support signals. ``` bool SbSystemSymbolize(const void *address, char *out_buffer, int buffer_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/16/thread.md b/cobalt/site/docs/reference/starboard/modules/16/thread.md new file mode 100644 index 0000000000000..0a3d3701be5b4 --- /dev/null +++ b/cobalt/site/docs/reference/starboard/modules/16/thread.md @@ -0,0 +1,250 @@ +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `thread.h` + +Defines functionality related to thread creation and cleanup. + +## Macros + +### kSbThreadContextInvalid + +Well-defined value for an invalid thread context. + +### kSbThreadInvalidId + +Well-defined constant value to mean "no thread ID." + +### kSbThreadSamplerInvalid + +Well-defined value for an invalid thread sampler. + +## Enums + +### SbThreadPriority + +A spectrum of thread priorities. Platforms map them appropriately to their own +priority system. Note that scheduling is platform-specific, and what these +priorities mean, if they mean anything at all, is also platform-specific. + +In particular, several of these priority values can map to the same priority on +a given platform. The only guarantee is that each lower priority should be +treated less-than-or-equal-to a higher priority. + +#### Values + +* `kSbThreadPriorityLowest` + + The lowest thread priority available on the current platform. +* `kSbThreadPriorityLow` + + A lower-than-normal thread priority, if available on the current platform. +* `kSbThreadPriorityNormal` + + Really, what is normal? You should spend time pondering that question more + than you consider less-important things, but less than you think about more- + important things. +* `kSbThreadPriorityHigh` + + A higher-than-normal thread priority, if available on the current platform. +* `kSbThreadPriorityHighest` + + The highest thread priority available on the current platform that isn't + considered "real-time" or "time-critical," if those terms have any meaning + on the current platform. +* `kSbThreadPriorityRealTime` + + If the platform provides any kind of real-time or time-critical scheduling, + this priority will request that treatment. Real-time scheduling generally + means that the thread will have more consistency in scheduling than non- + real-time scheduled threads, often by being more deterministic in how + threads run in relation to each other. But exactly how being real-time + affects the thread scheduling is platform-specific. + + For platforms where that is not offered, or otherwise not meaningful, this + will just be the highest priority available in the platform's scheme, which + may be the same as kSbThreadPriorityHighest. +* `kSbThreadNoPriority` + + Well-defined constant value to mean "no priority." This means to use the + default priority assignment method of that platform. This may mean to + inherit the priority of the spawning thread, or it may mean a specific + default priority, or it may mean something else, depending on the platform. + +## Typedefs + +### SbThreadContext + +A handle to the context of a frozen thread. + +#### Definition + +``` +typedef SbThreadContextPrivate* SbThreadContext +``` + +### SbThreadId + +An ID type that is unique per thread. + +#### Definition + +``` +typedef int32_t SbThreadId +``` + +### SbThreadSampler + +A handle to a thread sampler. + +#### Definition + +``` +typedef SbThreadSamplerPrivate* SbThreadSampler +``` + +## Functions + +### SbThreadContextGetPointer + +Gets the specified pointer-type `property` from the specified `context`. Returns +`true` if successful and `out_value` has been modified, otherwise returns +`false` and `out_value` is not modified. + +#### Declaration + +``` +bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) +``` + +### SbThreadContextIsValid + +Returns whether the given thread context is valid. + +#### Declaration + +``` +static bool SbThreadContextIsValid(SbThreadContext context) +``` + +### SbThreadGetId + +Returns the Thread ID of the currently executing thread. + +#### Declaration + +``` +SbThreadId SbThreadGetId() +``` + +### SbThreadGetPriority + +Get the thread priority of the current thread. + +#### Declaration + +``` +bool SbThreadGetPriority(SbThreadPriority *priority) +``` + +### SbThreadIsValidId + +Returns whether the given thread ID is valid. + +#### Declaration + +``` +static bool SbThreadIsValidId(SbThreadId id) +``` + +### SbThreadIsValidPriority + +Returns whether the given thread priority is valid. + +#### Declaration + +``` +static bool SbThreadIsValidPriority(SbThreadPriority priority) +``` + +### SbThreadSamplerCreate + +Creates a new thread sampler for the specified `thread`. + +If successful, this function returns the newly created handle. If unsuccessful, +this function returns `kSbThreadSamplerInvalid`. + +#### Declaration + +``` +SbThreadSampler SbThreadSamplerCreate(pthread_t thread) +``` + +### SbThreadSamplerDestroy + +Destroys the `sampler` and frees whatever resources it was using. + +#### Declaration + +``` +void SbThreadSamplerDestroy(SbThreadSampler sampler) +``` + +### SbThreadSamplerFreeze + +Suspends execution of the thread that `sampler` was created for. + +If successful, this function returns a `SbThreadContext` for the frozen thread, +from which properties may be read while the thread remains frozen. If +unsuccessful, this function returns `kSbThreadContextInvalid`. + +#### Declaration + +``` +SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) +``` + +### SbThreadSamplerIsSupported + +Whether the current platform supports thread sampling. The result of this +function must not change over the course of the program, which means that the +results of this function may be cached indefinitely. If this returns false, +`SbThreadSamplerCreate` will return an invalid sampler. + +#### Declaration + +``` +bool SbThreadSamplerIsSupported() +``` + +### SbThreadSamplerIsValid + +Returns whether the given thread sampler is valid. + +#### Declaration + +``` +static bool SbThreadSamplerIsValid(SbThreadSampler sampler) +``` + +### SbThreadSamplerThaw + +Resumes execution of the thread that `sampler` was created for. This invalidates +the context returned from `SbThreadSamplerFreeze`. + +#### Declaration + +``` +bool SbThreadSamplerThaw(SbThreadSampler sampler) +``` + +### SbThreadSetPriority + +Set the thread priority of the current thread. + +#### Declaration + +``` +bool SbThreadSetPriority(SbThreadPriority priority) +``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/time_zone.md b/cobalt/site/docs/reference/starboard/modules/16/time_zone.md similarity index 54% rename from cobalt/site/docs/reference/starboard/modules/13/time_zone.md rename to cobalt/site/docs/reference/starboard/modules/16/time_zone.md index 74d48172d63eb..c428babc2ae6d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/16/time_zone.md @@ -12,7 +12,7 @@ Provides access to the system time zone information. The number of minutes west of the Greenwich Prime Meridian, NOT including Daylight Savings Time adjustments. -For example: PST/PDT is 480 minutes (28800 seconds, 8 hours). +For example: America/Los_Angeles is 480 minutes (28800 seconds, 8 hours). #### Definition @@ -34,14 +34,15 @@ SbTimeZone SbTimeZoneGetCurrent() ### SbTimeZoneGetName -Gets a string representation of the current timezone. Note that the string -representation can either be standard or daylight saving time. The output can be -of the form: 1) A three-letter abbreviation such as "PST" or "PDT" (preferred). -2) A time zone identifier such as "America/Los_Angeles" 3) An un-abbreviated -name such as "Pacific Standard Time". +Gets a string representation of the current timezone. The format should be in +the IANA format [https://data.iana.org/time-zones/theory.html#naming](https://data.iana.org/time-zones/theory.html#naming)) . +Names normally have the form AREA/LOCATION, where AREA is a continent or ocean, +and LOCATION is a specific location within the area. Typical names are +'Africa/Cairo', 'America/New_York', and 'Pacific/Honolulu'. #### Declaration ``` const char* SbTimeZoneGetName() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/types.md b/cobalt/site/docs/reference/starboard/modules/16/types.md similarity index 100% rename from cobalt/site/docs/reference/starboard/modules/13/types.md rename to cobalt/site/docs/reference/starboard/modules/16/types.md diff --git a/cobalt/site/docs/reference/starboard/modules/13/window.md b/cobalt/site/docs/reference/starboard/modules/16/window.md similarity index 52% rename from cobalt/site/docs/reference/starboard/modules/13/window.md rename to cobalt/site/docs/reference/starboard/modules/16/window.md index acea84d4c7d07..6e5ee0e262764 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/window.md +++ b/cobalt/site/docs/reference/starboard/modules/16/window.md @@ -7,11 +7,6 @@ Provides functionality to handle Window creation and management. ## Macros -### kSbEventOnScreenKeyboardInvalidTicket - -System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. - ### kSbWindowInvalid Well-defined value for an invalid window handle. @@ -48,18 +43,6 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect - -Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This -structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. - -#### Members - -* `float x` -* `float y` -* `float width` -* `float height` - ### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of @@ -95,20 +78,6 @@ that would be created to back that window. ## Functions -### SbWindowBlurOnScreenKeyboard - -Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred. -kSbEventTypeOnScreenKeyboardBlurred has data `ticket`. Calling -SbWindowBlurOnScreenKeyboard() when the keyboard is already blurred is -permitted. Calling SbWindowBlurOnScreenKeyboard while the on screen keyboard is -not showing does nothing and does not fire any event. - -#### Declaration - -``` -void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket) -``` - ### SbWindowCreate Creates and returns a new system window with the given `options`, which may be @@ -149,20 +118,6 @@ Destroys `window`, reclaiming associated resources. bool SbWindowDestroy(SbWindow window) ``` -### SbWindowFocusOnScreenKeyboard - -Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused. -kSbEventTypeOnScreenKeyboardFocused has data `ticket`. Calling -SbWindowFocusOnScreenKeyboard() when the keyboard is already focused is -permitted. Calling SbWindowFocusOnScreenKeyboard while the on screen keyboard is -not showing does nothing and does not fire any event. - -#### Declaration - -``` -void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket) -``` - ### SbWindowGetDiagonalSizeInInches Gets the size of the diagonal between two opposing screen corners. @@ -176,18 +131,6 @@ is. float SbWindowGetDiagonalSizeInInches(SbWindow window) ``` -### SbWindowGetOnScreenKeyboardBoundingRect - -Get the rectangle of the on screen keyboard in screen pixel coordinates. Return -`true` if successful. Return `false` if the on screen keyboard is not showing. -If the function returns `false`, then `rect` will not have been modified. - -#### Declaration - -``` -bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect) -``` - ### SbWindowGetPlatformHandle Gets the platform-specific handle for `window`, which can be passed as an @@ -216,29 +159,6 @@ then `size` will not have been modified. bool SbWindowGetSize(SbWindow window, SbWindowSize *size) ``` -### SbWindowHideOnScreenKeyboard - -Hide the on screen keyboard. Fire kSbEventTypeWindowSizeChange and -kSbEventTypeOnScreenKeyboardHidden if necessary. -kSbEventTypeOnScreenKeyboardHidden has data `ticket`. Calling -SbWindowHideOnScreenKeyboard() when the keyboard is already hidden is permitted. - -#### Declaration - -``` -void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket) -``` - -### SbWindowIsOnScreenKeyboardShown - -Determine if the on screen keyboard is shown. - -#### Declaration - -``` -bool SbWindowIsOnScreenKeyboardShown(SbWindow window) -``` - ### SbWindowIsValid Returns whether the given window handle is valid. @@ -249,28 +169,6 @@ Returns whether the given window handle is valid. static bool SbWindowIsValid(SbWindow window) ``` -### SbWindowOnScreenKeyboardIsSupported - -Return whether the current platform supports an on screen keyboard - -#### Declaration - -``` -bool SbWindowOnScreenKeyboardIsSupported() -``` - -### SbWindowOnScreenKeyboardSuggestionsSupported - -Determine if the on screen keyboard has suggestions implemented. If this returns -false, then calling SbWindowUpdateOnScreenKeyboardSuggestions() will be -undefined. - -#### Declaration - -``` -bool SbWindowOnScreenKeyboardSuggestionsSupported(SbWindow window) -``` - ### SbWindowSetDefaultOptions Sets the default options for system windows. @@ -284,47 +182,3 @@ Sets the default options for system windows. void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` -### SbWindowSetOnScreenKeyboardKeepFocus - -Notify the system that `keepFocus` has been set for the OnScreenKeyboard. -`keepFocus` true indicates that the user may not navigate focus off of the -OnScreenKeyboard via input; focus may only be moved via events sent by the app. -`keepFocus` false indicates that the user may navigate focus off of the -OnScreenKeyboard via input. `keepFocus` is initialized to false in the -OnScreenKeyboard constructor. - -#### Declaration - -``` -void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus) -``` - -### SbWindowShowOnScreenKeyboard - -Show the on screen keyboard and populate the input with text `input_text`. Fire -kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary. -kSbEventTypeOnScreenKeyboardShown has data `ticket`. The passed in `input_text` -will never be NULL, but may be an empty string. Calling -SbWindowShowOnScreenKeyboard() when the keyboard is already shown is permitted, -and the input will be replaced with `input_text`. Showing the on screen keyboard -does not give it focus. - -#### Declaration - -``` -void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket) -``` - -### SbWindowUpdateOnScreenKeyboardSuggestions - -Update the on screen keyboard custom suggestions. Fire -kSbEventTypeOnScreenKeyboardSuggestionsUpdated. -kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data `ticket`. The -suggestions should remain up-to-date when the keyboard is shown after being -hidden. - -#### Declaration - -``` -void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/accessibility.md b/cobalt/site/docs/reference/starboard/modules/accessibility.md index 5c66ba442803e..8f2a652445a9c 100644 --- a/cobalt/site/docs/reference/starboard/modules/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/accessibility.md @@ -251,3 +251,4 @@ off (false). ``` bool SbAccessibilitySetCaptionsEnabled(bool enabled) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/atomic.md b/cobalt/site/docs/reference/starboard/modules/atomic.md index 0ed31cb649ec6..9653e53cecd31 100644 --- a/cobalt/site/docs/reference/starboard/modules/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/atomic.md @@ -108,3 +108,4 @@ Overloaded functions for Atomic8. ``` static SbAtomic8 SbAtomicRelease_CompareAndSwap8(volatile SbAtomic8 *ptr, SbAtomic8 old_value, SbAtomic8 new_value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/audio_sink.md b/cobalt/site/docs/reference/starboard/modules/audio_sink.md index 9277c70837b06..3cb7a82958056 100644 --- a/cobalt/site/docs/reference/starboard/modules/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/audio_sink.md @@ -212,3 +212,4 @@ Indicates whether the given audio sink handle is valid. ``` bool SbAudioSinkIsValid(SbAudioSink audio_sink) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/byte_swap.md deleted file mode 100644 index 72dc9327ed1e3..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/byte_swap.md +++ /dev/null @@ -1,75 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `byte_swap.h` - -Specifies functions for swapping byte order. These functions are used to deal -with endianness when performing I/O. - -## Functions - -### SbByteSwapS16 - -Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int16_t SbByteSwapS16(int16_t value) -``` - -### SbByteSwapS32 - -Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int32_t SbByteSwapS32(int32_t value) -``` - -### SbByteSwapS64 - -Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -int64_t SbByteSwapS64(int64_t value) -``` - -### SbByteSwapU16 - -Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint16_t SbByteSwapU16(uint16_t value) -``` - -### SbByteSwapU32 - -Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint32_t SbByteSwapU32(uint32_t value) -``` - -### SbByteSwapU64 - -Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The -value for which the byte order will be swapped. - -#### Declaration - -``` -uint64_t SbByteSwapU64(uint64_t value) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/condition_variable.md deleted file mode 100644 index 2d8f30b5fdce2..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/condition_variable.md +++ /dev/null @@ -1,140 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `condition_variable.h` - -Defines an interface for condition variables. - -## Macros - -### SB_CONDITION_VARIABLE_MAX_SIZE - -Max size of the SbConditionVariable type. - -## Enums - -### SbConditionVariableResult - -Enumeration of possible results from waiting on a condvar. - -#### Values - -* `kSbConditionVariableSignaled` - - The wait completed because the condition variable was signaled. -* `kSbConditionVariableTimedOut` - - The wait completed because it timed out, and was not signaled. -* `kSbConditionVariableFailed` - - The wait failed, either because a parameter wasn't valid, or the condition - variable has already been destroyed, or something similar. - -## Typedefs - -### SbConditionVariable - -An opaque handle to a condition variable type with reserved memory buffer of -size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbConditionVariable SbConditionVariable -``` - -## Functions - -### SbConditionVariableBroadcast - -Broadcasts to all current waiters of `condition` to stop waiting. This function -wakes all of the threads waiting on `condition` while SbConditionVariableSignal -wakes a single thread. - -`condition`: The condition that should no longer be waited for. - -#### Declaration - -``` -bool SbConditionVariableBroadcast(SbConditionVariable *condition) -``` - -### SbConditionVariableCreate - -Creates a new condition variable to work with `opt_mutex`, which may be null, -placing the newly created condition variable in `out_condition`. - -The return value indicates whether the condition variable could be created. - -#### Declaration - -``` -bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) -``` - -### SbConditionVariableDestroy - -Destroys the specified SbConditionVariable . The return value indicates whether -the destruction was successful. The behavior is undefined if other threads are -currently waiting on this condition variable. - -`condition`: The SbConditionVariable to be destroyed. This invalidates the -condition variable. - -#### Declaration - -``` -bool SbConditionVariableDestroy(SbConditionVariable *condition) -``` - -### SbConditionVariableIsSignaled - -Returns whether the given result is a success. - -#### Declaration - -``` -static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) -``` - -### SbConditionVariableSignal - -Signals the next waiter of `condition` to stop waiting. This function wakes a -single thread waiting on `condition` while SbConditionVariableBroadcast wakes -all threads waiting on it. - -`condition`: The condition that the waiter should stop waiting for. - -#### Declaration - -``` -bool SbConditionVariableSignal(SbConditionVariable *condition) -``` - -### SbConditionVariableWait - -Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, -and returning the result. Behavior is undefined if `mutex` is not held. - -#### Declaration - -``` -SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) -``` - -### SbConditionVariableWaitTimed - -Waits for `condition`, releasing the held lock `mutex`, blocking up to -`timeout_duration`, and returning the acquisition result. Behavior is undefined -if `mutex` is not held. - -`timeout_duration`: The maximum amount of time that function should wait for -`condition`. If the `timeout_duration` value is less than or equal to zero, the -function returns as quickly as possible with a kSbConditionVariableTimedOut -result. - -#### Declaration - -``` -SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime timeout_duration) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/configuration.md b/cobalt/site/docs/reference/starboard/modules/configuration.md index 1a3502e270aca..3ff1bef8b49ca 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration.md @@ -53,6 +53,11 @@ will trigger a compiler warning when referenced. SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. +### SB_EXPORT_PLATFORM + +SB_C_FORCE_INLINE annotation for forcing a C function to be inlined. +SB_EXPORT_PLATFORM annotates symbols as exported from shared libraries. + ### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for @@ -71,6 +76,10 @@ Whether the current platform has 64-bit atomic operations. Determines at compile-time whether this platform has a quirk. +### SB_IMPORT_PLATFORM + +SB_IMPORT_PLATFORM annotates symbols as imported from shared libraries. + ### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. @@ -86,7 +95,7 @@ Macro for hinting that an expression is likely to be true. ### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, -inclusive. +inclusive. The API version is not stable and is open for changes. ### SB_MINIMUM_API_VERSION @@ -98,11 +107,6 @@ inclusive. Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE - -Declares a function as overriding a virtual function on compilers that support -it. - ### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. @@ -123,7 +127,7 @@ base/compiler_specific.h) Include the platform-specific configuration. This macro is set by GN in starboard/build/config/BUILD.gn and passed in on the command line for all -targets and all configurations.Makes a pointer-typed parameter restricted so +targets and all configurations. Makes a pointer-typed parameter restricted so that the compiler can make certain optimizations because it knows the pointers are unique. diff --git a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md index 18af4bc2945ce..3866aab20c5fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md @@ -9,6 +9,15 @@ runtime decisions based on per platform configurations. ## Variables +### kHasPartialAudioFramesSupport + +Platform can support partial audio frames + +### kSbCanMapExecutableMemory + +Whether this platform can map executable memory. This is required for platforms +that want to JIT. + ### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if @@ -139,7 +148,3 @@ The string form of SB_PATH_SEP_CHAR. Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. - -### kSbUserMaxSignedIn - -The maximum number of users that can be signed in at the same time. diff --git a/cobalt/site/docs/reference/starboard/modules/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/cpu_features.md index e2aa35f2bb1a2..e6e85437eb54e 100644 --- a/cobalt/site/docs/reference/starboard/modules/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/cpu_features.md @@ -98,7 +98,7 @@ Book: /youtube/cobalt/_book.yaml SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags + ##### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -259,3 +259,4 @@ fields in `features` are invalid. ``` bool SbCPUFeaturesGet(SbCPUFeatures *features) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/decode_target.md b/cobalt/site/docs/reference/starboard/modules/decode_target.md index 6df175b6ba9ae..c8d38a28a294b 100644 --- a/cobalt/site/docs/reference/starboard/modules/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/decode_target.md @@ -12,7 +12,7 @@ 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 +* 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 @@ -21,7 +21,7 @@ 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. -## 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 @@ -33,51 +33,7 @@ to run arbitrary code on the application's renderer thread 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(). -The primary usage is likely to be the the SbPlayer implementation on some -platforms. - -## SbDecodeTarget Example - -Let's say that we are an application and we would like to use the interface -defined in starboard/image.h to decode an imaginary "image/foo" image type. - -First, the application 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 (SbImageIsDecodeSupported("image/foo", kPreferredFormats[i])) { - format = kPreferredFormats[i]; - break; - } -} - -``` - -Now that the application 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 = SbImageDecode( - context_provider, encoded_foo_data, encoded_foo_data_size, - "image/foo", format); - -// If the decode works, you can get the texture out and render it. -SbDecodeTargetInfo info; -memset(&info, 0, sizeof(info)); -SbDecodeTargetGetInfo(target, &info); -GLuint texture = - info.planes[kSbDecodeTargetPlaneRGBA].texture; -``` +The primary usage is likely to be the SbPlayer implementation on some platforms. ## Macros @@ -127,9 +83,9 @@ premultiplied unless otherwise explicitly specified. 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 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 format with GL - platforms, it is expected that the underlying texture will be set to the + 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). Content region left/right should be specified in u/v width resolution. @@ -207,8 +163,7 @@ information about the graphics context that will be used to render SbDecodeTargets. Some Starboard implementations may need to have references to some graphics objects when creating/destroying resources used by SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects should be provided -to all Starboard functions that might create SbDecodeTargets (e.g. -SbImageDecode()). +to all Starboard functions that might create SbDecodeTargets. #### Members @@ -216,12 +171,12 @@ SbImageDecode()). 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. + `void*` in order to avoid including the EGL header files here. * `void * egl_context` 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. + including the EGL header files here. * `SbDecodeTargetGlesContextRunner gles_context_runner` The `gles_context_runner` function pointer is passed in from the application @@ -264,7 +219,7 @@ This can be queried via calls to SbDecodeTargetGetInfo(). * `SbDecodeTargetInfoPlane planes` The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY, - kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode + kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this decode target. ### SbDecodeTargetInfoContentRegion @@ -368,7 +323,7 @@ static bool SbDecodeTargetIsValid(SbDecodeTarget handle) 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 +reference count. This function must be called on a thread with the context. #### Declaration @@ -399,3 +354,4 @@ Starboard implementations, if it is necessary. ``` static void SbDecodeTargetRunInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTargetGlesContextRunnerTarget target, void *target_context) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/directory.md b/cobalt/site/docs/reference/starboard/modules/directory.md index 6f845f6567a9c..748da304a3282 100644 --- a/cobalt/site/docs/reference/starboard/modules/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/directory.md @@ -25,18 +25,6 @@ typedef struct SbDirectoryPrivate* SbDirectory ## Functions -### SbDirectoryCanOpen - -Indicates whether SbDirectoryOpen is allowed for the given `path`. - -`path`: The path to be checked. - -#### Declaration - -``` -bool SbDirectoryCanOpen(const char *path) -``` - ### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the @@ -50,20 +38,6 @@ directory was closed successfully. bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate - -Creates the directory `path`, assuming the parent directory already exists. This -function returns `true` if the directory now exists (even if it existed before) -and returns `false` if the directory does not exist. - -`path`: The path to be created. - -#### Declaration - -``` -bool SbDirectoryCreate(const char *path) -``` - ### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and @@ -115,3 +89,4 @@ that the directory could not be opened. ``` SbDirectory SbDirectoryOpen(const char *path, SbFileError *out_error) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/drm.md b/cobalt/site/docs/reference/starboard/modules/drm.md index f42e43bf3db71..47cf7ef55b8a8 100644 --- a/cobalt/site/docs/reference/starboard/modules/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/drm.md @@ -29,7 +29,7 @@ Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. ### SbDrmKeyStatus -Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) +Status of a particular media key. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus) #### Values @@ -67,8 +67,9 @@ The status of session related operations. Used by * `kSbDrmStatusQuotaExceededError` * `kSbDrmStatusUnknownError` - 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. ## Typedefs @@ -85,7 +86,7 @@ typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void ### SbDrmSessionClosedFunc -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. #### Definition @@ -96,8 +97,15 @@ typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, c ### SbDrmSessionKeyStatusesChangedFunc 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. #### Definition @@ -119,6 +127,7 @@ context that was passed into the call to SbDrmCreateSystem(). `error_message` may contain an optional error message when `status` isn't `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. @@ -246,6 +255,50 @@ Clear any internal states/resources related to the specified `session_id`. void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` +### SbDrmCreateSystem + +Creates a new DRM system that can be used when constructing an SbPlayer or an +SbDecoder. + +This function returns `kSbDrmSystemInvalid` if `key_system` is unsupported. + +Also see the documentation of SbDrmGenerateSessionUpdateRequest() and +SbDrmUpdateSession() for more details. + +`key_system`: The DRM key system to be created. The value should be in the 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. Note the key +system will be matched case sensitive. For more details, refer to [https://w3c.github.io/encrypted-media/#dfn-key-system-s](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 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. + +#### Declaration + +``` +SbDrmSystem SbDrmCreateSystem(const char *key_system, void *context, SbDrmSessionUpdateRequestFunc update_request_callback, SbDrmSessionUpdatedFunc session_updated_callback, SbDrmSessionKeyStatusesChangedFunc key_statuses_changed_callback, SbDrmServerCertificateUpdatedFunc server_certificate_updated_callback, SbDrmSessionClosedFunc session_closed_callback) +``` + ### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and @@ -292,9 +345,12 @@ establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used. `type`: The case-sensitive type of the session update request payload. Must not -be NULL. `initialization_data`: The data for which the session update request -payload is created. Must not be NULL. `initialization_data_size`: The size of -the session update request payload. +be NULL. + +`initialization_data`: The data for which the session update request payload is +created. Must not be NULL. + +`initialization_data_size`: The size of the session update request payload. #### Declaration @@ -375,14 +431,18 @@ 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`. `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. `certificate`: Pointer to the server -certificate data. Must not be NULL. `certificate_size`: Size of the server -certificate data. +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. + +`certificate`: Pointer to the server certificate data. Must not be NULL. + +`certificate_size`: Size of the server certificate data. #### Declaration @@ -415,3 +475,4 @@ must not be NULL. ``` void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/egl.md b/cobalt/site/docs/reference/starboard/modules/egl.md index 4afff1aa236ef..87deff271ad91 100644 --- a/cobalt/site/docs/reference/starboard/modules/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/egl.md @@ -144,3 +144,4 @@ typedef int32_t SbEglInt32 config, void *native_pixmap, const SbEglAttrib *attrib_list)` * `SbEglBoolean(*eglWaitSync)(SbEglDisplay dpy, SbEglSync sync, SbEglInt32 flags)` + diff --git a/cobalt/site/docs/reference/starboard/modules/event.md b/cobalt/site/docs/reference/starboard/modules/event.md index b8005a5d6c368..1f61995e9c1d8 100644 --- a/cobalt/site/docs/reference/starboard/modules/event.md +++ b/cobalt/site/docs/reference/starboard/modules/event.md @@ -236,6 +236,9 @@ the type of the value pointed to by that data argument, if any. triggered by the application have tickets passed in via SbWindowBlurOnScreenKeyboard. System-triggered events have ticket value kSbEventOnScreenKeyboardInvalidTicket. +* `kSbEventTypeReserved1` + + Reserved for deprecated events. * `kSbEventTypeAccessibilityCaptionSettingsChanged` One or more of the fields returned by SbAccessibilityGetCaptionSettings has @@ -303,7 +306,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -389,7 +392,7 @@ of microseconds to wait before calling the `callback` function. Set `delay` to #### Declaration ``` -SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) +SbEventId SbEventSchedule(SbEventCallback callback, void *context, int64_t delay) ``` ### SbRunStarboardMain @@ -402,3 +405,4 @@ event loop with the application event handler. ``` int SbRunStarboardMain(int argc, char **argv, SbEventHandleCallback callback) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/file.md b/cobalt/site/docs/reference/starboard/modules/file.md index 103af475ace1b..5371e0324ade1 100644 --- a/cobalt/site/docs/reference/starboard/modules/file.md +++ b/cobalt/site/docs/reference/starboard/modules/file.md @@ -124,15 +124,15 @@ Used to hold information about a file. * `bool is_symbolic_link` Whether the file corresponds to a symbolic link. -* `SbTime last_modified` +* `int64_t last_modified` - The last modified time of a file. -* `SbTime last_accessed` + The last modified time of a file - microseconds since Windows epoch UTC. +* `int64_t last_accessed` - The last accessed time of a file. -* `SbTime creation_time` + The last accessed time of a file - microseconds since Windows epoch UTC. +* `int64_t creation_time` - The creation time of a file. + The creation time of a file - microseconds since Windows epoch UTC. ## Functions @@ -192,18 +192,6 @@ fails if the file in question is being held open. bool SbFileDelete(const char *path) ``` -### SbFileExists - -Indicates whether a file or directory exists at `path`. - -`path`: The absolute path of the file or directory being checked. - -#### Declaration - -``` -bool SbFileExists(const char *path) -``` - ### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not @@ -402,3 +390,4 @@ The return value identifies the number of bytes written, or `-1` on error. ``` static int SbFileWriteAll(SbFile file, const char *data, int size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/gles.md b/cobalt/site/docs/reference/starboard/modules/gles.md index 77bc07e71c82d..049838f80b659 100644 --- a/cobalt/site/docs/reference/starboard/modules/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/gles.md @@ -459,3 +459,4 @@ typedef long int SbGlIntPtr internalformat, SbGlSizei width, SbGlSizei height, SbGlSizei depth)` * `void(*glGetInternalformativ)(SbGlEnum target, SbGlEnum internalformat, SbGlEnum pname, SbGlSizei bufSize, SbGlInt32 *params)` + diff --git a/cobalt/site/docs/reference/starboard/modules/image.md b/cobalt/site/docs/reference/starboard/modules/image.md deleted file mode 100644 index 945938a099033..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/image.md +++ /dev/null @@ -1,77 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `image.h` - -API for hardware accelerated image decoding. This module allows for the client -to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It -also provides an interface for the client to query what combinations of encoded -image formats and SbDecodeTargetFormats are supported or not. - -All functions in this module are safe to call from any thread at any point in -time. - -## SbImageIsDecodeSupported and SbImageDecode Example - -``` -SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); -void* data = GetCompressedJPEGFromSomewhere(); -int data_size = GetCompressedJPEGSizeFromSomewhere(); -const char* mime_type = "image/jpeg"; -SbDecodeTargetFormat format = kSbDecodeTargetFormat1PlaneRGBA; - -if (!SbImageIsDecodeSupported(mime_type, format)) { - return; -} - -SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, - mime_type, format); -``` - -## Functions - -### SbImageDecode - -Attempt to decode encoded `mime_type` image data `data` of size `data_size` into -an SbDecodeTarget of SbDecodeFormatType `format`, possibly using -SbDecodeTargetProvider `provider`, if it is non-null. Thus, four following -scenarios regarding the provider may happen: - -1. The provider is required by the `SbImageDecode` implementation and no - provider is given. The implementation should gracefully fail by immediately - returning kSbDecodeTargetInvalid. - -1. The provider is required and is passed in. The implementation will proceed - forward, using the SbDecodeTarget from the provider. - -1. The provider is not required and is passed in. The provider will NOT be - called, and the implementation will proceed to decoding however it desires. - -1. The provider is not required and is not passed in. The implementation will - proceed forward. The `data` pointer must not be NULL. The `mime_type` string - must not be NULL. Thus, it is NOT safe for clients of this API to assume - that the `provider` it passes in will be called. Finally, if the decode - succeeds, a new SbDecodeTarget will be allocated. If `mime_type` image - decoding for the requested format is not supported or the decode fails, - kSbDecodeTargetInvalid will be returned, with any intermediate allocations - being cleaned up in the implementation. - -#### Declaration - -``` -SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) -``` - -### SbImageIsDecodeSupported - -Whether the current platform supports hardware accelerated decoding an image of -mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must -not be NULL. The result of this function must not change over the course of the -program, which means that the results of this function may be cached -indefinitely. - -#### Declaration - -``` -bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/input.md b/cobalt/site/docs/reference/starboard/modules/input.md index a858c73e3e898..d2dd2db32dc58 100644 --- a/cobalt/site/docs/reference/starboard/modules/input.md +++ b/cobalt/site/docs/reference/starboard/modules/input.md @@ -168,3 +168,4 @@ A 2-dimensional vector used to represent points and motion vectors. * `float x` * `float y` + diff --git a/cobalt/site/docs/reference/starboard/modules/key.md b/cobalt/site/docs/reference/starboard/modules/key.md index ed87e531f4fcf..c07837e233c87 100644 --- a/cobalt/site/docs/reference/starboard/modules/key.md +++ b/cobalt/site/docs/reference/starboard/modules/key.md @@ -291,3 +291,4 @@ Bit-mask of key modifiers. * `kSbKeyModifiersPointerButtonMiddle` * `kSbKeyModifiersPointerButtonBack` * `kSbKeyModifiersPointerButtonForward` + diff --git a/cobalt/site/docs/reference/starboard/modules/log.md b/cobalt/site/docs/reference/starboard/modules/log.md index 6cf3a491a2a75..60b361d4697d2 100644 --- a/cobalt/site/docs/reference/starboard/modules/log.md +++ b/cobalt/site/docs/reference/starboard/modules/log.md @@ -134,3 +134,4 @@ Inline wrapper of SbLogFormat to convert from ellipsis to va_args. ``` void static void static void SbLogRawFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/media.md b/cobalt/site/docs/reference/starboard/modules/media.md index 0619503f46f67..408b757390592 100644 --- a/cobalt/site/docs/reference/starboard/modules/media.md +++ b/cobalt/site/docs/reference/starboard/modules/media.md @@ -187,7 +187,7 @@ output. The type of audio connector. Will be `kSbMediaAudioConnectorUnknown` if this device cannot provide this information. -* `SbTime latency` +* `int64_t latency` The expected latency of audio over this output, in microseconds, or `0` if this device cannot provide this information. @@ -209,8 +209,8 @@ The set of information required by the decoder or player for each audio sample. * `SbMediaAudioStreamInfo stream_info` The set of information of the video stream associated with this sample. -* `SbTime discarded_duration_from_front` -* `SbTime discarded_duration_from_back` +* `int64_t discarded_duration_from_front` +* `int64_t discarded_duration_from_back` ### SbMediaAudioStreamInfo @@ -240,14 +240,13 @@ The set of information required by the decoder or player for each audio stream. The size, in bytes, of the audio_specific_config. * `const void * audio_specific_config` - 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](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. ### SbMediaColorMetadata 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](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) +luminosity than is possible with standard digital imaging. #### Members @@ -447,10 +446,12 @@ Note that neither `mime` nor `key_system` can be NULL. This function returns `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. `key_system`: A lowercase value in the form -of "com.example.somesystem" as suggested by [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system)) that can +than one codec, delimited by comma. + +`key_system`: A lowercase value in the form of "com.example.somesystem", and 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. +For more detail, refer to [https://w3c.github.io/encrypted-media/#key-system](https://w3c.github.io/encrypted-media/#key-system) An implementation may choose to support `key_system` with extra attributes, separated by ';', like `com.example.somesystem; attribute_name1="value1"; @@ -462,23 +463,21 @@ 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` 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` encryptionScheme of -MediaKeySystemMediaCapability, as defined in [https://wicg.github.io/encrypted-media-encryption-scheme/,](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` kSbMediaSupportTypeNotSupported when +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. It 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` 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` kSbMediaSupportTypeProbably when +`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` 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. +`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. For more detail, refer to [https://wicg.github.io/encrypted-media-encryption-scheme](https://wicg.github.io/encrypted-media-encryption-scheme) #### Declaration @@ -533,11 +532,13 @@ int SbMediaGetAudioOutputCount() ### SbMediaGetBufferAllocationUnit -When the media stack needs more memory to store media buffers, it will allocate -extra memory in units returned by SbMediaGetBufferAllocationUnit. This can -return 0, in which case the media stack will allocate extra memory on demand. -When SbMediaGetInitialBufferCapacity and this function both return 0, the media -stack will allocate individual buffers directly using SbMemory functions. +The media buffer will be allocated using the returned alignment. Set this to a +larger value may increase the memory consumption of media buffers. When the +media stack needs more memory to store media buffers, it will allocate extra +memory in units returned by SbMediaGetBufferAllocationUnit. This can return 0, +in which case the media stack will allocate extra memory on demand. When +SbMediaGetInitialBufferCapacity and this function both return 0, the media stack +will allocate individual buffers directly using malloc functions. #### Declaration @@ -547,19 +548,19 @@ int SbMediaGetBufferAllocationUnit() ### SbMediaGetBufferGarbageCollectionDurationThreshold -Specifies the duration threshold of media source garbage collection. When the -accumulated duration in a source buffer exceeds this value, the media source -implementation will try to eject existing buffers from the cache. This is -usually triggered when the video being played has a simple content and the -encoded data is small. In such case this can limit how much is allocated for the -book keeping data of the media buffers and avoid OOM of system heap. This should -return 170 seconds for most of the platforms. But it can be further reduced on -systems with extremely low memory. +Specifies the duration threshold of media source garbage collection in +microseconds. When the accumulated duration in a source buffer exceeds this +value, the media source implementation will try to eject existing buffers from +the cache. This is usually triggered when the video being played has a simple +content and the encoded data is small. In such case this can limit how much is +allocated for the book keeping data of the media buffers and avoid OOM of system +heap. This should return 170 seconds for most of the platforms. But it can be +further reduced on systems with extremely low memory. #### Declaration ``` -SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() +int64_t SbMediaGetBufferGarbageCollectionDurationThreshold() ``` ### SbMediaGetBufferPadding @@ -574,22 +575,6 @@ padding. int SbMediaGetBufferPadding() ``` -### SbMediaGetBufferStorageType - -Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or -`SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored -in main memory allocated by SbMemory functions. For file storage, the media -buffers will be stored in a temporary file in the system cache folder acquired -by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when -its value is "file" the media stack will still allocate memory to cache the -buffers in use. - -#### Declaration - -``` -SbMediaBufferStorageType SbMediaGetBufferStorageType() -``` - ### SbMediaGetInitialBufferCapacity The amount of memory that will be used to store media buffers allocated during @@ -613,10 +598,14 @@ allocation of media buffers may only fail when there is not enough memory in the system to fulfill the request, under which case the 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. +`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. #### Declaration @@ -631,10 +620,14 @@ resolution of such videos shouldn't go beyond 1080p. Its value should be less than the sum of SbMediaGetAudioBufferBudget and '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. +`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. #### Declaration @@ -650,10 +643,14 @@ being used by video buffers but will also make app less likely to re-download video data. Note that the app may experience significant difficulty if this 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. +`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. #### Declaration @@ -681,10 +678,11 @@ bool SbMediaIsBufferPoolAllocateOnDemand() ### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer -pools should be allocated on demand, as opposed to using SbMemory* functions. +pools should be allocated on demand, as opposed to using malloc functions. #### Declaration ``` bool SbMediaIsBufferUsingMemoryPool() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/memory.md b/cobalt/site/docs/reference/starboard/modules/memory.md index 5b13119060ec9..2a78fa580a672 100644 --- a/cobalt/site/docs/reference/starboard/modules/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/memory.md @@ -30,8 +30,9 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. ### SbMemoryMapFlags -The bitwise OR of these flags should be passed to SbMemoryMap to indicate how -the mapped memory can be used. +TODO: Remove the definition once the memory_mapped_file.h extension is +deprecated. The bitwise OR of these flags should be passed to SbMemoryMap to +indicate how the mapped memory can be used. #### Values @@ -44,289 +45,3 @@ the mapped memory can be used. * `kSbMemoryMapProtectExec` * `kSbMemoryMapProtectReadWrite` -## Functions - -### SbMemoryAllocate - -Allocates and returns a chunk of memory of at least `size` bytes. This function -should be called from the client codebase. It is intended to be a drop-in -replacement for `malloc`. - -Note that this function returns `NULL` if it is unable to allocate the memory. - -`size`: The amount of memory to be allocated. If `size` is 0, the function may -return `NULL` or it may return a unique pointer value that can be passed to -SbMemoryDeallocate. - -#### Declaration - -``` -void* SbMemoryAllocate(size_t size) -``` - -### SbMemoryAllocateAligned - -Allocates and returns a chunk of memory of at least `size` bytes, aligned to -`alignment`. This function should be called from the client codebase. It is -meant to be a drop-in replacement for `memalign`. - -The function returns `NULL` if it cannot allocate the memory. In addition, the -function's behavior is undefined if `alignment` is not a power of two. - -`alignment`: The way that data is arranged and accessed in memory. The value -must be a power of two. `size`: The size of the memory to be allocated. If -`size` is `0`, the function may return `NULL` or it may return a unique aligned -pointer value that can be passed to SbMemoryDeallocateAligned. - -#### Declaration - -``` -void* SbMemoryAllocateAligned(size_t alignment, size_t size) -``` - -### SbMemoryAllocateAlignedChecked - -Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an -allocation failure. - -DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) -``` - -### SbMemoryAllocateAlignedUnchecked - -This is the implementation of SbMemoryAllocateAligned that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) -``` - -### SbMemoryAllocateChecked - -Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation -failure. - -DO NOT CALL. Call SbMemoryAllocate(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateChecked(size_t size) -``` - -### SbMemoryAllocateNoReport - -DEPRECATED: Same as SbMemoryAllocate(). - -#### Declaration - -``` -void* SbMemoryAllocateNoReport(size_t size) -``` - -### SbMemoryAllocateUnchecked - -This is the implementation of SbMemoryAllocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryAllocate(...) instead. - -#### Declaration - -``` -void* SbMemoryAllocateUnchecked(size_t size) -``` - -### SbMemoryCalloc - -A wrapper that implements a drop-in replacement for `calloc`, which is used in -some packages. - -#### Declaration - -``` -static void* SbMemoryCalloc(size_t count, size_t size) -``` - -### SbMemoryDeallocate - -Frees a previously allocated chunk of memory. If `memory` is NULL, then the -operation is a no-op. This function should be called from the client codebase. -It is meant to be a drop-in replacement for `free`. - -`memory`: The chunk of memory to be freed. - -#### Declaration - -``` -void SbMemoryDeallocate(void *memory) -``` - -### SbMemoryDeallocateAligned - -`memory`: The chunk of memory to be freed. If `memory` is NULL, then the -function is a no-op. - -#### Declaration - -``` -void SbMemoryDeallocateAligned(void *memory) -``` - -### SbMemoryDeallocateNoReport - -DEPRECATED: Same as SbMemoryDeallocate() - -#### Declaration - -``` -void SbMemoryDeallocateNoReport(void *memory) -``` - -### SbMemoryFlush - -Flushes any data in the given virtual address range that is cached locally in -the current processor core to physical memory, ensuring that data and -instruction caches are cleared. This is required to be called on executable -memory that has been written to and might be executed in the future. - -#### Declaration - -``` -void SbMemoryFlush(void *virtual_address, int64_t size_bytes) -``` - -### SbMemoryFree - -This is the implementation of SbMemoryDeallocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryDeallocate(...) instead. - -#### Declaration - -``` -void SbMemoryFree(void *memory) -``` - -### SbMemoryFreeAligned - -This is the implementation of SbMemoryFreeAligned that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. - -#### Declaration - -``` -void SbMemoryFreeAligned(void *memory) -``` - -### SbMemoryMap - -Allocates `size_bytes` worth of physical memory pages and maps them into an -available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on -failure. `NULL` is a valid return value. - -`size_bytes`: The amount of physical memory pages to be allocated. `flags`: The -bitwise OR of the protection flags for the mapped memory as specified in -`SbMemoryMapFlags`. Allocating executable memory is not allowed and will fail. -If executable memory is needed, map non-executable memory first and then switch -access to executable using SbMemoryProtect. When kSbMemoryMapProtectReserved is -used, the address space will not be accessible and, if possible, the platform -should not count it against any memory budget. `name`: A value that appears in -the debugger on some platforms. The value can be up to 32 bytes. - -#### Declaration - -``` -void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) -``` - -### SbMemoryProtect - -Change the protection of `size_bytes` of memory regions, starting from -`virtual_address`, to `flags`, returning `true` on success. - -#### Declaration - -``` -bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) -``` - -### SbMemoryReallocate - -Attempts to resize `memory` to be at least `size` bytes, without touching the -contents of memory. - -* If the function cannot perform the fast resize, it allocates a new chunk of - memory, copies the contents over, and frees the previous chunk, returning a - pointer to the new chunk. - -* If the function cannot perform the slow resize, it returns `NULL`, leaving - the given memory chunk unchanged. - -This function should be called from the client codebase. It is meant to be a -drop-in replacement for `realloc`. - -`memory`: The chunk of memory to be resized. `memory` may be NULL, in which case -it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which -`memory` will be resized. If `size` is `0`, the function may return `NULL` or it -may return a unique pointer value that can be passed to SbMemoryDeallocate. - -#### Declaration - -``` -void* SbMemoryReallocate(void *memory, size_t size) -``` - -### SbMemoryReallocateChecked - -Same as SbMemoryReallocateUnchecked, but will abort() in the case of an -allocation failure. - -DO NOT CALL. Call SbMemoryReallocate(...) instead. - -#### Declaration - -``` -void* SbMemoryReallocateChecked(void *memory, size_t size) -``` - -### SbMemoryReallocateUnchecked - -This is the implementation of SbMemoryReallocate that must be provided by -Starboard ports. - -DO NOT CALL. Call SbMemoryReallocate(...) instead. - -#### Declaration - -``` -void* SbMemoryReallocateUnchecked(void *memory, size_t size) -``` - -### SbMemoryUnmap - -Unmap `size_bytes` of physical pages starting from `virtual_address`, returning -`true` on success. After this function completes, [virtual_address, -virtual_address + size_bytes) will not be read/writable. This function can unmap -multiple contiguous regions that were mapped with separate calls to -SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns -`(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns -`(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. - -#### Declaration - -``` -bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/memory_reporter.md deleted file mode 100644 index 5e49693e70bce..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/memory_reporter.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -layout: doc -title: "Starboard Module Reference: memory_reporter.h" ---- - -DEPRECATED: Provides an interface for memory reporting. - -## Typedefs ## - -### SbMemoryReporterOnAlloc ### - -A function to report a memory allocation from SbMemoryAllocate(). Note that -operator new calls SbMemoryAllocate which will delegate to this callback. - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnAlloc) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnDealloc ### - -A function to report a memory deallocation from SbMemoryDeallcoate(). Note that -operator delete calls SbMemoryDeallocate which will delegate to this callback. - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnDealloc) (void *context, const void *memory) -``` - -### SbMemoryReporterOnMapMemory ### - -A function to report a memory mapping from SbMemoryMap(). - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnMapMemory) (void *context, const void *memory, size_t size) -``` - -### SbMemoryReporterOnUnMapMemory ### - -A function to report a memory unmapping from SbMemoryUnmap(). - -#### Definition #### - -``` -typedef void(* SbMemoryReporterOnUnMapMemory) (void *context, const void *memory, size_t size) -``` - -## Structs ## - -### SbMemoryReporter ### - -SbMemoryReporter allows memory reporting via user-supplied functions. The void* -context is passed to every call back. It's strongly recommended that C-Style -struct initialization is used so that the arguments can be typed check by the -compiler. For example, SbMemoryReporter mem_reporter = { MallocCallback, .... -context }; - -#### Members #### - -* `SbMemoryReporterOnAlloc on_alloc_cb` - - Callback to report allocations. -* `SbMemoryReporterOnDealloc on_dealloc_cb` - - Callback to report deallocations. -* `SbMemoryReporterOnMapMemory on_mapmem_cb` - - Callback to report memory map. -* `SbMemoryReporterOnUnMapMemory on_unmapmem_cb` - - Callback to report memory unmap. -* `void * context` - - Optional, is passed to callbacks as first argument. - -## Functions ## - -### SbMemorySetReporter ### - -Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime -management is done internally on input pointer. - -NOTE: This module is unused starting with Starboard 15 and will be removed in -the future. - -Returns true if the memory reporter was set with no errors. If an error was -reported then check the log for why it failed. - -Note that other than a thread-barrier-write of the input pointer, there is no -thread safety guarantees with this function due to performance considerations. -It's recommended that this be called once during the lifetime of the program, or -not at all. Do not delete the supplied pointer, ever. Example (Good): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); // allow value to leak. Example (Bad): -SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); -... SbMemorySetReporter(NULL); delete mem_reporter; // May crash. - -#### Declaration #### - -``` -bool SbMemorySetReporter(struct SbMemoryReporter *tracker) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/microphone.md b/cobalt/site/docs/reference/starboard/modules/microphone.md index bcf9e4355e65c..497cbe91cec43 100644 --- a/cobalt/site/docs/reference/starboard/modules/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/microphone.md @@ -260,3 +260,4 @@ has already been read from the device is discarded. ``` int SbMicrophoneRead(SbMicrophone microphone, void *out_audio_data, int audio_data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/mutex.md b/cobalt/site/docs/reference/starboard/modules/mutex.md deleted file mode 100644 index 82ff8500ab8d8..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/mutex.md +++ /dev/null @@ -1,127 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `mutex.h` - -Defines a mutually exclusive lock that can be used to coordinate with other -threads. - -## Macros - -### SB_MUTEX_MAX_SIZE - -Max size of the SbMutex type. - -## Enums - -### SbMutexResult - -Enumeration of possible results from acquiring a mutex. - -#### Values - -* `kSbMutexAcquired` - - The mutex was acquired successfully. -* `kSbMutexBusy` - - The mutex was not acquired because it was held by someone else. -* `kSbMutexDestroyed` - - The mutex has already been destroyed. - -## Typedefs - -### SbMutex - -An opaque handle to a mutex type with reserved memory buffer of size -SB_MUTEX_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbMutex SbMutex -``` - -## Functions - -### SbMutexAcquire - -Acquires `mutex`, blocking indefinitely. The return value identifies the -acquisition result. SbMutexes are not reentrant, so a recursive acquisition -blocks forever. - -`mutex`: The mutex to be acquired. - -#### Declaration - -``` -SbMutexResult SbMutexAcquire(SbMutex *mutex) -``` - -### SbMutexAcquireTry - -Acquires `mutex`, without blocking. The return value identifies the acquisition -result. SbMutexes are not reentrant, so a recursive acquisition has undefined -behavior. - -`mutex`: The mutex to be acquired. - -#### Declaration - -``` -SbMutexResult SbMutexAcquireTry(SbMutex *mutex) -``` - -### SbMutexCreate - -Creates a new mutex. The return value indicates whether the function was able to -create a new mutex. - -`out_mutex`: The handle to the newly created mutex. - -#### Declaration - -``` -bool SbMutexCreate(SbMutex *out_mutex) -``` - -### SbMutexDestroy - -Destroys a mutex. The return value indicates whether the destruction was -successful. Destroying a locked mutex results in undefined behavior. - -`mutex`: The mutex to be invalidated. - -#### Declaration - -``` -bool SbMutexDestroy(SbMutex *mutex) -``` - -### SbMutexIsSuccess - -Indicates whether the given result is a success. A value of `true` indicates -that the mutex was acquired. - -`result`: The result being checked. - -#### Declaration - -``` -static bool SbMutexIsSuccess(SbMutexResult result) -``` - -### SbMutexRelease - -Releases `mutex` held by the current thread. The return value indicates whether -the release was successful. Releases should always be successful if `mutex` is -held by the current thread. - -`mutex`: The mutex to be released. - -#### Declaration - -``` -bool SbMutexRelease(SbMutex *mutex) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/once.md b/cobalt/site/docs/reference/starboard/modules/once.md deleted file mode 100644 index d77302467f8b0..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/once.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `once.h` - -Onces represent initializations that should only ever happen once per process, -in a thread-safe way. - -## Macros - -### SB_ONCE_MAX_SIZE - -Max size of the SbOnceControl type. - -## Typedefs - -### SbOnceControl - -An opaque handle to a once control type with reserved memory buffer of size -SB_ONCE_MAX_SIZE and aligned at void pointer type. - -#### Definition - -``` -typedef union SbOnceControl SbOnceControl -``` - -### SbOnceInitRoutine - -Function pointer type for methods that can be called via the SbOnce() system. - -#### Definition - -``` -typedef void(* SbOnceInitRoutine) (void) -``` - -## Functions - -### SbOnce - -Thread-safely runs `init_routine` only once. - -* If this `once_control` has not run a function yet, this function runs - `init_routine` in a thread-safe way and then returns `true`. - -* If SbOnce() was called with `once_control` before, the function returns - `true` immediately. - -* If `once_control` or `init_routine` is invalid, the function returns - `false`. - -#### Declaration - -``` -bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/player.md b/cobalt/site/docs/reference/starboard/modules/player.md index 0382642a35fe9..837dd941d1ea6 100644 --- a/cobalt/site/docs/reference/starboard/modules/player.md +++ b/cobalt/site/docs/reference/starboard/modules/player.md @@ -52,9 +52,12 @@ data may come from multiple sources. * `kMatroskaBlockAdditional` The side data comes from the BlockAdditional data in the Matroska/Webm - container, as specified in [https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39](https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39)9) andnd [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional)l) - . The first 8 bytes of the data contains the value of BlockAddID in big - endian format, followed by the content of BlockAdditional. + container. The first 8 bytes of the data contains the value of BlockAddID in + big endian format, followed by the content of BlockAdditional. See: + + [https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03](https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03) + + [https://www.webmproject.org/docs/container/#BlockAdditional](https://www.webmproject.org/docs/container/#BlockAdditional) ### SbPlayerState @@ -130,10 +133,13 @@ typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMed ### SbPlayerErrorFunc -Callback for player errors, that may set a `message`. `error`: indicates the -error code. `message`: provides specific informative diagnostic message about -the error condition encountered. It is ok for the message to be an empty string -or NULL if no information is available. +Callback for player errors, that may set a `message`. + +`error`: indicates the error code. + +`message`: provides specific informative diagnostic message about the error +condition encountered. It is ok for the message to be an empty string or NULL if +no information is available. #### Definition @@ -192,14 +198,14 @@ Information about the current media playback state. #### Members -* `SbTime current_media_timestamp` +* `int64_t current_media_timestamp` The position of the playback head, as precisely as possible, in microseconds. -* `SbTime duration` +* `int64_t duration` The known duration of the currently playing media stream, in microseconds. -* `SbTime start_date` +* `int64_t start_date` The result of getStartDate for the currently playing media stream, in microseconds since the epoch of January 1, 1601 UTC. @@ -250,9 +256,9 @@ Information about the samples to be written into SbPlayerWriteSamples(). * `int buffer_size` Size of the data pointed to by `buffer`. -* `SbTime timestamp` +* `int64_t timestamp` - The timestamp of the sample in SbTime. + The timestamp of the sample in microseconds since Windows epoch UTC. * `SbPlayerSampleSideData* side_data` Points to an array of side data for the input, when available. @@ -292,20 +298,123 @@ coming from multiple sources. ## Functions +### SbPlayerCreate + +Creates a player that will be displayed on `window` for the specified +`video_codec` and `audio_codec`, acquiring all resources needed to operate it, +and returning an opaque handle to it. The expectation is that a new player will +be created and destroyed for every playback. + +This function returns the created player. Note the following: + +* The associated decoder of the returned player should be assumed to not be in + `kSbPlayerDecoderStateNeedsData` until SbPlayerSeek() has been called on it. + +* It is expected either that the thread that calls SbPlayerCreate is the same + thread that calls the other `SbPlayer` functions for that player, or that + there is a mutex guarding calls into each `SbPlayer` instance. + +* If there is a platform limitation on how many players can coexist + simultaneously, then calls made to this function that attempt to exceed that + limit must return `kSbPlayerInvalid`. Multiple calls to SbPlayerCreate must + not cause a crash. + +`window`: The window that will display the player. `window` can be +`kSbWindowInvalid` for platforms where video is only displayed on a particular +window that the underlying implementation already has access to. + +`video_codec`: The video codec used for the player. If `video_codec` is +`kSbMediaVideoCodecNone`, the player is an audio-only player. If `video_codec` +is any other value, the player is an audio/video decoder. This can be set to +`kSbMediaVideoCodecNone` to play a video with only an audio track. + +`audio_codec`: The audio codec used for the player. The caller must provide a +populated `audio_sample_info` if audio codec is `kSbMediaAudioCodecAac`. Can be +set to `kSbMediaAudioCodecNone` to play a video without any audio track. In such +case `audio_sample_info` must be NULL. + +`drm_system`: If the media stream has encrypted portions, then this parameter +provides an appropriate DRM system, created with `SbDrmCreateSystem()`. If the +stream does not have encrypted portions, then `drm_system` may be +`kSbDrmSystemInvalid`. + +`audio_sample_info`: Note that the caller must provide a populated +`audio_sample_info` if the audio codec is `kSbMediaAudioCodecAac`. Otherwise, +`audio_sample_info` can be NULL. See media.h for the format of the +`SbMediaAudioSampleInfo` struct. + +Note that `audio_specific_config` is a pointer and the content it points to is +no longer valid after this function returns. The implementation has to make a +copy of the content if it is needed after the function returns. + +`max_video_capabilities`: This string communicates the max video capabilities +required to the platform. The web app will not provide a video stream exceeding +the maximums described by this parameter. Allows the platform to optimize +playback pipeline for low quality video streams if it knows that it will never +adapt to higher quality streams. The string uses the same format as the string +passed in to SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to +"width=1920; height=1080; framerate=15;", the video will never adapt to +resolution higher than 1920x1080 or frame per second higher than 15 fps. When +the maximums are unknown, this will be set to NULL. + +`sample_deallocator_func`: If not `NULL`, the player calls this function on an +internal thread to free the sample buffers passed into SbPlayerWriteSample(). + +`decoder_status_func`: If not `NULL`, the decoder calls this function on an +internal thread to provide an update on the decoder's status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_status_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the playback status. No work should be +done on this thread. Rather, it should just signal the client thread interacting +with the decoder. + +`player_error_func`: If not `NULL`, the player calls this function on an +internal thread to provide an update on the error status. This callback is +responsible for setting the media error message. + +`context`: This is passed to all callbacks and is generally used to point at a +class or struct that contains state associated with the player. + +`output_mode`: Selects how the decoded video frames will be output. For example, +kSbPlayerOutputModePunchOut indicates that the decoded video frames will be +output to a background video layer by the platform, and +kSbPlayerOutputDecodeToTexture indicates that the decoded video frames should be +made available for the application to pull via calls to +SbPlayerGetCurrentFrame(). + +`provider`: Only present in Starboard version 3 and up. If not `NULL`, then when +output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY use the +provider to create SbDecodeTargets on the renderer thread. A provider may not +always be needed by the player, but if it is needed, and the provider is not +given, the player will fail by returning `kSbPlayerInvalid`. + +If `NULL` is passed to any of the callbacks (`sample_deallocator_func`, +`decoder_status_func`, `player_status_func`, or `player_error_func` if it +applies), then `kSbPlayerInvalid` must be returned. + +#### Declaration + +``` +SbPlayer SbPlayerCreate(SbWindow window, const SbPlayerCreationParam *creation_param, SbPlayerDeallocateSampleFunc sample_deallocate_func, SbPlayerDecoderStatusFunc decoder_status_func, SbPlayerStatusFunc player_status_func, SbPlayerErrorFunc player_error_func, void *context, SbDecodeTargetGraphicsContextProvider *context_provider) +``` + ### SbPlayerDestroy Destroys `player`, freeing all associated resources. * Upon calling this method, there should be one call to the player status callback (i.e. `player_status_func` used in the creation of the player) - which indicates the player is destroyed. Note, the callback has to be in- - flight when SbPlayerDestroyed is called. + which indicates the player is destroyed. Note, the callback has to be + inflight when SbPlayerDestroyed is called. * No more other callbacks should be issued after this function returns. * It is not allowed to pass `player` into any other `SbPlayer` function once - SbPlayerDestroy has been called on that player. `player`: The player to be - destroyed. Must not be `kSbPlayerInvalid`. + SbPlayerDestroy has been called on that player. + +`player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. #### Declaration @@ -326,50 +435,50 @@ audio output configurations other than the ones already returned. The app will use the information returned to determine audio related behaviors, like: -Audio Write Duration: Audio write duration is how far past the current playback -position the app will write audio samples. The app will write all samples -between `current_playback_position` and `current_playback_position` + -`audio_write_duration`, as soon as they are available. - -`audio_write_duration` will be to `kSbPlayerWriteDurationLocal` -kSbPlayerWriteDurationLocal when all audio configurations linked to `player` is -local, or if there isn't any audio output. It will be set to -`kSbPlayerWriteDurationRemote` kSbPlayerWriteDurationRemote for remote or -wireless audio outputs, i.e. one of `kSbMediaAudioConnectorBluetooth` -kSbMediaAudioConnectorBluetooth or `kSbMediaAudioConnectorRemote*` -kSbMediaAudioConnectorRemote* . - -The app only guarantees to write `audio_write_duration` past -`current_playback_position`, but the app is free to write more samples than -that. So the platform shouldn't rely on this for flow control. The platform -should achieve flow control by sending `kSbPlayerDecoderStateNeedsData` -kSbPlayerDecoderStateNeedsData less frequently. - -The platform is responsible for guaranteeing that when only -`audio_write_duration` audio samples are written at a time, no playback issues -occur (such as transient or indefinite hanging). +* Audio Write Duration: Audio write duration is how far past the current + playback position the app will write audio samples. The app will write all + samples between `current_playback_position` and `current_playback_position` + + `audio_write_duration`, as soon as they are available. + +* `audio_write_duration` will be to `kSbPlayerWriteDurationLocal` when all + audio configurations linked to `player` is local, or if there isn't any + audio output. It will be set to `kSbPlayerWriteDurationRemote` for remote or + wireless audio outputs, i.e. one of `kSbMediaAudioConnectorBluetooth` or + `kSbMediaAudioConnectorRemote*`. + +* The app only guarantees to write `audio_write_duration` past + `current_playback_position`, but the app is free to write more samples than + that. So the platform shouldn't rely on this for flow control. The platform + should achieve flow control by sending `kSbPlayerDecoderStateNeedsData` less + frequently. + +* The platform is responsible for guaranteeing that when only + `audio_write_duration` audio samples are written at a time, no playback + issues occur (such as transient or indefinite hanging). The audio configurations should be available as soon as possible, and they have -to be available when the `player` is at `kSbPlayerStatePresenting` -kSbPlayerStatePresenting , unless the audio codec is `kSbMediaAudioCodecNone` or -there's no written audio inputs. +to be available when the `player` is at `kSbPlayerStatePresenting`, unless the +audio codec is `kSbMediaAudioCodecNone` or there's no written audio inputs. -The app will set `audio_write_duration` to `kSbPlayerWriteDurationLocal` -kSbPlayerWriteDurationLocal when the audio configuration isn't available (i.e. -the function returns false when index is 0). The platform has to make the audio -configuration available immediately after the SbPlayer is created, if it expects -the app to treat the platform as using wireless audio outputs. +The app will set `audio_write_duration` to `kSbPlayerWriteDurationLocal` when +the audio configuration isn't available (i.e. the function returns false when +index is 0). The platform has to make the audio configuration available +immediately after the SbPlayer is created, if it expects the app to treat the +platform as using wireless audio outputs. Once at least one audio configurations are returned, the return values and their orders shouldn't change during the life time of `player`. The platform may -inform the app of any changes by sending `kSbPlayerErrorCapabilityChanged` -kSbPlayerErrorCapabilityChanged to request a playback restart. +inform the app of any changes by sending `kSbPlayerErrorCapabilityChanged` to +request a playback restart. `player`: The player about which information is being retrieved. Must not be -`kSbPlayerInvalid`. `index`: The index of the audio output configuration. Must -be greater than or equal to 0. `out_audio_configuration`: The information about -the audio output, refer to `SbMediaAudioConfiguration` for more details. Must -not be NULL. +`kSbPlayerInvalid`. + +`index`: The index of the audio output configuration. Must be greater than or +equal to 0. + +`out_audio_configuration`: The information about the audio output, refer to +`SbMediaAudioConfiguration` for more details. Must not be NULL. #### Declaration @@ -395,19 +504,36 @@ kSbDecodeTargetInvalid is returned. SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` +### SbPlayerGetInfo + +Gets a snapshot of the current player state and writes it to `out_player_info`. +This function may be called very frequently and is expected to be inexpensive. + +`player`: The player about which information is being retrieved. Must not be +`kSbPlayerInvalid`. + +`out_player_info`: The information retrieved for the player. + +#### Declaration + +``` +void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo *out_player_info) +``` + ### SbPlayerGetMaximumNumberOfSamplesPerWrite -Writes a single sample of the given media type to `player`'s input stream. Its -data may be passed in via more than one buffers. The lifetime of -`sample_buffers`, `sample_buffer_sizes`, `video_sample_info`, and -`sample_drm_info` (as well as member `subsample_mapping` contained inside it) -are not guaranteed past the call to SbPlayerWriteSample. That means that before -returning, the implementation must synchronously copy any information it wants -to retain from those structures. +Returns the maximum number of samples that can be written in a single call to +SbPlayerWriteSamples(). Returning a value greater than one can improve +performance by allowing SbPlayerWriteSamples() to write multiple samples in one +call. -`player`: The player for which the number is retrieved. `sample_type`: The type -of sample for which the number is retrieved. See the `SbMediaType` enum in -media.h. +Note that this feature is currently disabled in Cobalt where +SbPlayerWriteSamples() will always be called with one sample. + +`player`: The player for which the number is retrieved. + +`sample_type`: The type of sample for which the number is retrieved. See the +`SbMediaType` enum in media.h. #### Declaration @@ -449,6 +575,45 @@ Returns whether the given player handle is valid. static bool SbPlayerIsValid(SbPlayer player) ``` +### SbPlayerSeek + +Tells the player to freeze playback (if playback has already started), reset or +flush the decoder pipeline, and go back to the Prerolling state. The player +should restart playback once it can display the frame at `seek_to_timestamp`, or +the closest it can get. (Some players can only seek to I-Frames, for example.) + +* Seek must be called before samples are sent when starting playback for the + first time, or the client never receives the + `kSbPlayerDecoderStateNeedsData` signal. + +* A call to seek may interrupt another seek. + +* After this function is called, the client should not send any more audio or + video samples until `SbPlayerDecoderStatusFunc` is called back with + `kSbPlayerDecoderStateNeedsData` for each required media type. + `SbPlayerDecoderStatusFunc` is the `decoder_status_func` callback function + that was specified when the player was created (SbPlayerCreate). + +`player`: The SbPlayer in which the seek operation is being performed. Must not +be `kSbPlayerInvalid`. + +`seek_to_timestamp`: The frame at which playback should begin. + +`ticket`: A user-supplied unique ID to be passed to all subsequent +`SbPlayerDecoderStatusFunc` calls. (That is the `decoder_status_func` callback +function specified when calling SbPlayerCreate.) + +The `ticket` value is used to filter calls that may have been in flight when +SbPlayerSeek was called. To be very specific, once SbPlayerSeek has been called +with ticket X, a client should ignore all `SbPlayerDecoderStatusFunc` calls that +do not pass in ticket X. + +#### Declaration + +``` +void SbPlayerSeek(SbPlayer player, int64_t seek_to_timestamp, int ticket) +``` + ### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do @@ -464,11 +629,18 @@ implementors should take care to avoid related performance concerns with such frequent calls. `player`: The player that is being resized. Must not be `kSbPlayerInvalid`. + `z_index`: The z-index of the player. When the bounds of multiple players are overlapped, the one with larger z-index will be rendered on top of the ones with -smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. -`y`: The y-coordinate of the upper-left corner of the player. `width`: The width -of the player, in pixels. `height`: The height of the player, in pixels. +smaller z-index. + +`x`: The x-coordinate of the upper-left corner of the player. + +`y`: The y-coordinate of the upper-left corner of the player. + +`width`: The width of the player, in pixels. + +`height`: The height of the player, in pixels. #### Declaration @@ -502,9 +674,11 @@ bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) Sets the player's volume. `player`: The player in which the volume is being adjusted. Must not be -`kSbPlayerInvalid`. `volume`: The new player volume. The value must be between -`0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be -muted, and a value of `1.0` means that it should be played at full volume. +`kSbPlayerInvalid`. + +`volume`: The new player volume. The value must be between `0.0` and `1.0`, +inclusive. A value of `0.0` means that the audio should be muted, and a value of +`1.0` means that it should be played at full volume. #### Declaration @@ -519,8 +693,9 @@ there are no more samples for that media type for the remainder of this media stream. This marker is invalidated, along with the rest of the stream's contents, after a call to SbPlayerSeek. -`player`: The player to which the marker is written. `stream_type`: The type of -stream for which the marker is written. +`player`: The player to which the marker is written. + +`stream_type`: The type of stream for which the marker is written. #### Declaration @@ -530,14 +705,29 @@ void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ### SbPlayerWriteSamples +Writes samples of the given media type to `player`'s input stream. The lifetime +of `sample_infos`, and the members of its elements like `buffer`, +`video_sample_info`, and `drm_info` (as well as member `subsample_mapping` +contained inside it) are not guaranteed past the call to SbPlayerWriteSamples(). +That means that before returning, the implementation must synchronously copy any +information it wants to retain from those structures. + +SbPlayerWriteSamples() allows writing of multiple samples in one call. + +`player`: The player to which the sample is written. Must not be +`kSbPlayerInvalid`. + `sample_type`: The type of sample being written. See the `SbMediaType` enum in -media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with +media.h. + +`sample_infos`: A pointer to an array of SbPlayerSampleInfo with `number_of_sample_infos` elements, each holds the data for an sample, i.e. a sequence of whole NAL Units for video, or a complete audio frame. `sample_infos` cannot be assumed to live past the call into SbPlayerWriteSamples(), so it must be copied if its content will be used after SbPlayerWriteSamples() returns. + `number_of_sample_infos`: Specify the number of samples contained inside -`sample_infos`. It has to be at least one, and less than the return value of +`sample_infos`. It has to be at least one, and at most the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). #### Declaration @@ -545,3 +735,4 @@ SbPlayerGetMaximumNumberOfSamplesPerWrite(). ``` void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/socket.md b/cobalt/site/docs/reference/starboard/modules/socket.md index 744c04e3847d2..e7f4bc9e71563 100644 --- a/cobalt/site/docs/reference/starboard/modules/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/socket.md @@ -540,15 +540,15 @@ Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: If set to `true`, -then `period` specifies the minimum time (SbTime) is always in microseconds) -between keep-alive packets. If set to `false`, `period` is ignored. `period`: -The time between keep-alive packets. This value is only relevant if `value` is -`true`. +then `period` specifies the minimum time in microseconds between keep-alive +packets. If set to `false`, `period` is ignored. `period`: The time in +microseconds between keep-alive packets. This value is only relevant if `value` +is `true`. #### Declaration ``` -bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) +bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, int64_t period) ``` ### SbSocketSetTcpNoDelay @@ -583,3 +583,4 @@ option. ``` bool SbSocketSetTcpWindowScaling(SbSocket socket, bool value) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/socket_waiter.md b/cobalt/site/docs/reference/starboard/modules/socket_waiter.md index f1c6bd8b9f2fa..54bc7eae0645f 100644 --- a/cobalt/site/docs/reference/starboard/modules/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/socket_waiter.md @@ -202,15 +202,15 @@ SbSocketWaiterWakeUp() it not called by that time. The return value indicates the reason that the socket waiter exited. This function should only be called on the thread that waits on this waiter. -`duration`: The minimum amount of time after which the socket waiter should exit -if it is not woken up before then. As with SbThreadSleep() (see thread.h), this -function may wait longer than `duration`, such as if the timeout expires while a -callback is being fired. +`duration`: The minimum amount of time in microseconds after which the socket +waiter should exit if it is not woken up before then. As with SbThreadSleep() +(see thread.h), this function may wait longer than `duration`, such as if the +timeout expires while a callback is being fired. #### Declaration ``` -SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) +SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, int64_t duration) ``` ### SbSocketWaiterWakeUp @@ -235,3 +235,4 @@ next 7 times they are called. ``` void SbSocketWaiterWakeUp(SbSocketWaiter waiter) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md b/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md index 0bd6e65b63790..ea4ad46b3f87d 100644 --- a/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md @@ -49,3 +49,4 @@ when the previous utterances are complete. ``` void SbSpeechSynthesisSpeak(const char *text) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/storage.md b/cobalt/site/docs/reference/starboard/modules/storage.md index f20016113be16..df71c579f0573 100644 --- a/cobalt/site/docs/reference/starboard/modules/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/storage.md @@ -55,23 +55,22 @@ bool SbStorageCloseRecord(SbStorageRecord record) ### SbStorageDeleteRecord -Deletes the `SbStorageRecord` for `user` named `name`. The return value -indicates whether the record existed and was successfully deleted. If the record -did not exist or could not be deleted, the function returns `false`. +Deletes the `SbStorageRecord` named `name`. The return value indicates whether +the record existed and was successfully deleted. If the record did not exist or +could not be deleted, the function returns `false`. -If `name` is NULL, deletes the default storage record for the user, like what -would have been deleted with the previous version of SbStorageDeleteRecord. +If `name` is NULL, deletes the default storage record, like what would have been +deleted with the previous version of SbStorageDeleteRecord. -This function must not be called while the user's storage record is open. This -function performs blocking I/O on the calling thread. +This function must not be called while the storage record is open. This function +performs blocking I/O on the calling thread. -`user`: The user for whom the record will be deleted. `name`: The filesystem- -safe name of the record to open. +`name`: The filesystem-safe name of the record to open. #### Declaration ``` -bool SbStorageDeleteRecord(SbUser user, const char *name) +bool SbStorageDeleteRecord(const char *name) ``` ### SbStorageGetRecordSize @@ -99,22 +98,20 @@ static bool SbStorageIsValidRecord(SbStorageRecord record) ### SbStorageOpenRecord -Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on -the calling thread until the open is completed. If `user` is not a valid -`SbUser`, the function returns `kSbStorageInvalidRecord`. Will return an -`SbStorageRecord` of size zero if the record does not yet exist. Opening an -already-open `SbStorageRecord` has undefined behavior. +Opens and returns the SbStorageRecord named `name`, blocking I/O on the calling +thread until the open is completed. Will return an `SbStorageRecord` of size +zero if the record does not yet exist. Opening an already-open `SbStorageRecord` +has undefined behavior. -If `name` is NULL, opens the default storage record for the user, like what -would have been saved with the previous version of SbStorageOpenRecord. +If `name` is NULL, opens the default storage record, like what would have been +saved with the previous version of SbStorageOpenRecord. -`user`: The user for which the storage record will be opened. `name`: The -filesystem-safe name of the record to open. +`name`: The filesystem-safe name of the record to open. #### Declaration ``` -SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) +SbStorageRecord SbStorageOpenRecord(const char *name) ``` ### SbStorageReadRecord @@ -156,3 +153,4 @@ after a short time, even if there is an unexpected process termination before ``` bool SbStorageWriteRecord(SbStorageRecord record, const char *data, int64_t data_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/string.md b/cobalt/site/docs/reference/starboard/modules/string.md deleted file mode 100644 index 3fed809df4618..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/string.md +++ /dev/null @@ -1,174 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `string.h` - -Defines functions for interacting with c-style strings. - -## Functions - -### SbStringCompareNoCase - -Compares two strings, ignoring differences in case. The return value is: - -* `< 0` if `string1` is ASCII-betically lower than `string2`. - -* `0` if the two strings are equal. - -* `> 0` if `string1` is ASCII-betically higher than `string2`. - -This function is meant to be a drop-in replacement for `strcasecmp`. - -`string1`: The first string to compare. `string2`: The second string to compare. - -#### Declaration - -``` -int SbStringCompareNoCase(const char *string1, const char *string2) -``` - -### SbStringCompareNoCaseN - -Compares the first `count` characters of two strings, ignoring differences in -case. The return value is: - -* `< 0` if `string1` is ASCII-betically lower than `string2`. - -* `0` if the two strings are equal. - -* `> 0` if `string1` is ASCII-betically higher than `string2`. - -This function is meant to be a drop-in replacement for `strncasecmp`. - -`string1`: The first string to compare. `string2`: The second string to compare. -`count`: The number of characters to compare. - -#### Declaration - -``` -int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) -``` - -### SbStringDuplicate - -Copies `source` into a buffer that is allocated by this function and that can be -freed with SbMemoryDeallocate. This function is meant to be a drop-in -replacement for `strdup`. - -`source`: The string to be copied. - -#### Declaration - -``` -char* SbStringDuplicate(const char *source) -``` - -### SbStringFormat - -Produces a string formatted with `format` and `arguments`, placing as much of -the result that will fit into `out_buffer`. The return value specifies the -number of characters that the format would produce if `buffer_size` were -infinite. - -This function is meant to be a drop-in replacement for `vsnprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `arguments`: Variable arguments used in the string. - -#### Declaration - -``` -int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 -``` - -### SbStringFormatF - -An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This -function is meant to be a drop-in replacement for `snprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 -``` - -### SbStringFormatUnsafeF - -An inline wrapper of SbStringFormat that is meant to be a drop-in replacement -for the unsafe but commonly used `sprintf`. - -`out_buffer`: The location where the formatted string is stored. `format`: A -string that specifies how the data should be formatted. `...`: Arguments used in -the string. - -#### Declaration - -``` -static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 -``` - -### SbStringFormatWide - -This function is identical to SbStringFormat, but is for wide characters. It is -meant to be a drop-in replacement for `vswprintf`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `arguments`: Variable arguments used in the string. - -#### Declaration - -``` -int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) -``` - -### SbStringFormatWideF - -An inline wrapper of SbStringFormatWide that converts from ellipsis to -`va_args`. - -`out_buffer`: The location where the formatted string is stored. `buffer_size`: -The size of `out_buffer`. `format`: A string that specifies how the data should -be formatted. `...`: Arguments used in the string. - -#### Declaration - -``` -static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) -``` - -### SbStringScan - -Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The -return value specifies the number of successfully matched items, which may be -`0`. - -This function is meant to be a drop-in replacement for `vsscanf`. - -`buffer`: The string to scan for the pattern. `pattern`: The string to search -for in `buffer`. `arguments`: Values matching `pattern` that were extracted from -`buffer`. - -#### Declaration - -``` -int SbStringScan(const char *buffer, const char *pattern, va_list arguments) -``` - -### SbStringScanF - -An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This -function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string -to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: -Values matching `pattern` that were extracted from `buffer`. - -#### Declaration - -``` -static int SbStringScanF(const char *buffer, const char *pattern,...) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/system.md b/cobalt/site/docs/reference/starboard/modules/system.md index 86437a3d08041..04fceecbe83ea 100644 --- a/cobalt/site/docs/reference/starboard/modules/system.md +++ b/cobalt/site/docs/reference/starboard/modules/system.md @@ -670,3 +670,4 @@ signal-safe on platforms that support signals. ``` bool SbSystemSymbolize(const void *address, char *out_buffer, int buffer_size) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/thread.md b/cobalt/site/docs/reference/starboard/modules/thread.md index 56c7898a12b43..0a3d3701be5b4 100644 --- a/cobalt/site/docs/reference/starboard/modules/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/thread.md @@ -15,14 +15,6 @@ Well-defined value for an invalid thread context. Well-defined constant value to mean "no thread ID." -### kSbThreadLocalKeyInvalid - -Well-defined constant value to mean "no thread local key." - -### kSbThreadNoAffinity - -Well-defined constant value to mean "no affinity." - ### kSbThreadSamplerInvalid Well-defined value for an invalid thread sampler. @@ -81,28 +73,6 @@ treated less-than-or-equal-to a higher priority. ## Typedefs -### SbThread - -An opaque handle to a thread type. - -#### Definition - -``` -typedef void* SbThread -``` - -### SbThreadAffinity - -Type for thread core affinity. This generally will be a single cpu (or core or -hyperthread) identifier. Some platforms may not support affinity, and some may -have specific rules about how it must be used. - -#### Definition - -``` -typedef int32_t SbThreadAffinity -``` - ### SbThreadContext A handle to the context of a frozen thread. @@ -113,17 +83,6 @@ A handle to the context of a frozen thread. typedef SbThreadContextPrivate* SbThreadContext ``` -### SbThreadEntryPoint - -Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of -data passed in from the calling thread. - -#### Definition - -``` -typedef void*(* SbThreadEntryPoint) (void *context) -``` - ### SbThreadId An ID type that is unique per thread. @@ -134,26 +93,6 @@ An ID type that is unique per thread. typedef int32_t SbThreadId ``` -### SbThreadLocalDestructor - -Function pointer type for Thread-Local destructors. - -#### Definition - -``` -typedef void(* SbThreadLocalDestructor) (void *value) -``` - -### SbThreadLocalKey - -A handle to a thread-local key. - -#### Definition - -``` -typedef SbThreadLocalKeyPrivate* SbThreadLocalKey -``` - ### SbThreadSampler A handle to a thread sampler. @@ -188,95 +127,6 @@ Returns whether the given thread context is valid. static bool SbThreadContextIsValid(SbThreadContext context) ``` -### SbThreadCreate - -Creates a new thread, which starts immediately. - -* If the function succeeds, the return value is a handle to the newly created - thread. - -* If the function fails, the return value is `kSbThreadInvalid`. - -`stack_size`: The amount of memory reserved for the thread. Set the value to `0` -to indicate that the default stack size should be used. `priority`: The thread's -priority. This value can be set to `kSbThreadNoPriority` to use the platform's -default priority. As examples, it could be set to a fixed, standard priority or -to a priority inherited from the thread that is calling SbThreadCreate(), or to -something else. `affinity`: The thread's affinity. This value can be set to -`kSbThreadNoAffinity` to use the platform's default affinity. `joinable`: -Indicates whether the thread can be joined (`true`) or should start out -"detached" (`false`). Note that for joinable threads, when you are done with the -thread handle, you must call `SbThreadJoin` to release system resources -associated with the thread. This is not necessary for detached threads, but -detached threads cannot be joined. `name`: A name used to identify the thread. -This value is used mainly for debugging, it can be `NULL`, and it might not be -used in production builds. `entry_point`: A pointer to a function that will be -executed on the newly created thread. `context`: This value will be passed to -the `entry_point` function. - -#### Declaration - -``` -SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) -``` - -### SbThreadCreateLocalKey - -Creates and returns a new, unique key for thread local data. If the function -does not succeed, the function returns `kSbThreadLocalKeyInvalid`. - -If `destructor` is specified, it will be called in the owning thread, and only -in the owning thread, when the thread exits. In that case, it is called on the -local value associated with the key in the current thread as long as the local -value is not NULL. - -`destructor`: A pointer to a function. The value may be NULL if no clean up is -needed. - -#### Declaration - -``` -SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) -``` - -### SbThreadDestroyLocalKey - -Destroys thread local data for the specified key. The function is a no-op if the -key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This -function does NOT call the destructor on any stored values. - -`key`: The key for which to destroy thread local data. - -#### Declaration - -``` -void SbThreadDestroyLocalKey(SbThreadLocalKey key) -``` - -### SbThreadDetach - -Detaches `thread`, which prevents it from being joined. This is sort of like a -non-blocking join. This function is a no-op if the thread is already detached or -if the thread is already being joined by another thread. - -`thread`: The thread to be detached. - -#### Declaration - -``` -void SbThreadDetach(SbThread thread) -``` - -### SbThreadGetCurrent - -Returns the handle of the currently executing thread. - -#### Declaration - -``` -SbThread SbThreadGetCurrent() -``` - ### SbThreadGetId Returns the Thread ID of the currently executing thread. @@ -287,72 +137,14 @@ Returns the Thread ID of the currently executing thread. SbThreadId SbThreadGetId() ``` -### SbThreadGetLocalValue - -Returns the pointer-sized value for `key` in the currently executing thread's -local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key -has already been destroyed. - -`key`: The key for which to return the value. - -#### Declaration - -``` -void* SbThreadGetLocalValue(SbThreadLocalKey key) -``` - -### SbThreadGetName - -Returns the debug name of the currently executing thread. - -#### Declaration - -``` -void SbThreadGetName(char *buffer, int buffer_size) -``` - -### SbThreadIsCurrent - -Returns whether `thread` is the current thread. - -`thread`: The thread to check. - -#### Declaration - -``` -static bool SbThreadIsCurrent(SbThread thread) -``` - -### SbThreadIsEqual - -Indicates whether `thread1` and `thread2` refer to the same thread. - -`thread1`: The first thread to compare. `thread2`: The second thread to compare. - -#### Declaration - -``` -bool SbThreadIsEqual(SbThread thread1, SbThread thread2) -``` - -### SbThreadIsValid - -Returns whether the given thread handle is valid. - -#### Declaration - -``` -static bool SbThreadIsValid(SbThread thread) -``` - -### SbThreadIsValidAffinity +### SbThreadGetPriority -Returns whether the given thread affinity is valid. +Get the thread priority of the current thread. #### Declaration ``` -static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) +bool SbThreadGetPriority(SbThreadPriority *priority) ``` ### SbThreadIsValidId @@ -365,16 +157,6 @@ Returns whether the given thread ID is valid. static bool SbThreadIsValidId(SbThreadId id) ``` -### SbThreadIsValidLocalKey - -Returns whether the given thread local variable key is valid. - -#### Declaration - -``` -static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) -``` - ### SbThreadIsValidPriority Returns whether the given thread priority is valid. @@ -385,30 +167,6 @@ Returns whether the given thread priority is valid. static bool SbThreadIsValidPriority(SbThreadPriority priority) ``` -### SbThreadJoin - -Joins the thread on which this function is called with joinable `thread`. This -function blocks the caller until the designated thread exits, and then cleans up -that thread's resources. The cleanup process essentially detaches thread. - -The return value is `true` if the function is successful and `false` if `thread` -is invalid or detached. - -Each joinable thread can only be joined once and must be joined to be fully -cleaned up. Once SbThreadJoin is called, the thread behaves as if it were -detached to all threads other than the joining thread. - -`thread`: The thread to which the current thread will be joined. The `thread` -must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, -then the SbThreadJoin function populates it with the return value of the -thread's `main` function. - -#### Declaration - -``` -bool SbThreadJoin(SbThread thread, void **out_return) -``` - ### SbThreadSamplerCreate Creates a new thread sampler for the specified `thread`. @@ -419,7 +177,7 @@ this function returns `kSbThreadSamplerInvalid`. #### Declaration ``` -SbThreadSampler SbThreadSamplerCreate(SbThread thread) +SbThreadSampler SbThreadSamplerCreate(pthread_t thread) ``` ### SbThreadSamplerDestroy @@ -480,54 +238,13 @@ the context returned from `SbThreadSamplerFreeze`. bool SbThreadSamplerThaw(SbThreadSampler sampler) ``` -### SbThreadSetLocalValue - -Sets the pointer-sized value for `key` in the currently executing thread's local -storage. The return value indicates whether `key` is valid and has not already -been destroyed. +### SbThreadSetPriority -`key`: The key for which to set the key value. `value`: The new pointer-sized -key value. +Set the thread priority of the current thread. #### Declaration ``` -bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) +bool SbThreadSetPriority(SbThreadPriority priority) ``` -### SbThreadSetName - -Sets the debug name of the currently executing thread by copying the specified -name string. - -`name`: The name to assign to the thread. - -#### Declaration - -``` -void SbThreadSetName(const char *name) -``` - -### SbThreadSleep - -Sleeps the currently executing thread. - -`duration`: The minimum amount of time, in microseconds, that the currently -executing thread should sleep. The function is a no-op if this value is negative -or `0`. - -#### Declaration - -``` -void SbThreadSleep(SbTime duration) -``` - -### SbThreadYield - -Yields the currently executing thread, so another thread has a chance to run. - -#### Declaration - -``` -void SbThreadYield() -``` diff --git a/cobalt/site/docs/reference/starboard/modules/time.md b/cobalt/site/docs/reference/starboard/modules/time.md deleted file mode 100644 index a6228cc0de6ce..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/time.md +++ /dev/null @@ -1,152 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `time.h` - -Provides access to system time and timers. - -## Macros - -### kSbTimeDay - -One day in SbTime units (microseconds). - -### kSbTimeHour - -One hour in SbTime units (microseconds). - -### kSbTimeMax - -The maximum value of an SbTime. - -### kSbTimeMillisecond - -One millisecond in SbTime units (microseconds). - -### kSbTimeMinute - -One minute in SbTime units (microseconds). - -### kSbTimeNanosecondsPerMicrosecond - -How many nanoseconds in one SbTime unit (microseconds). - -### kSbTimeSecond - -One second in SbTime units (microseconds). - -### kSbTimeToPosixDelta - -A term that can be added to an SbTime to convert it into the number of -microseconds since the POSIX epoch. - -## Typedefs - -### SbTime - -The number of microseconds since the epoch of January 1, 1601 UTC, or the number -of microseconds between two times. Always microseconds, ALWAYS UTC. - -#### Definition - -``` -typedef int64_t SbTime -``` - -### SbTimeMonotonic - -A number of microseconds from some point. The main property of this time is that -it increases monotonically. It should also be as high-resolution a timer as we -can get on a platform. So, it is good for measuring the time between two calls -without worrying about a system clock adjustment. It's not good for getting the -wall clock time. - -#### Definition - -``` -typedef int64_t SbTimeMonotonic -``` - -## Functions - -### SbTimeFromPosix - -Converts microseconds from the POSIX epoch into an `SbTime`. - -`time`: A time that measures the number of microseconds since January 1, 1970, -00:00:00, UTC. - -#### Declaration - -``` -static SbTime SbTimeFromPosix(int64_t time) -``` - -### SbTimeGetMonotonicNow - -Gets a monotonically increasing time representing right now. - -#### Declaration - -``` -SbTimeMonotonic SbTimeGetMonotonicNow() -``` - -### SbTimeGetMonotonicThreadNow - -Gets a monotonically increasing time representing how long the current thread -has been in the executing state (i.e. not pre-empted nor waiting on an event). -This is not necessarily total time and is intended to allow measuring thread -execution time between two timestamps. If this is not available then -SbTimeGetMonotonicNow() should be used. - -#### Declaration - -``` -SbTimeMonotonic SbTimeGetMonotonicThreadNow() -``` - -### SbTimeGetNow - -Gets the current system time as an `SbTime`. - -#### Declaration - -``` -SbTime SbTimeGetNow() -``` - -### SbTimeIsTimeThreadNowSupported - -Returns whether the current platform supports time thread now - -#### Declaration - -``` -bool SbTimeIsTimeThreadNowSupported() -``` - -### SbTimeNarrow - -Safely narrows a number from a more precise unit to a less precise one. This -function rounds negative values toward negative infinity. - -#### Declaration - -``` -static int64_t SbTimeNarrow(int64_t time, int64_t divisor) -``` - -### SbTimeToPosix - -Converts `SbTime` into microseconds from the POSIX epoch. - -`time`: A time that is either measured in microseconds since the epoch of -January 1, 1601, UTC, or that measures the number of microseconds between two -times. - -#### Declaration - -``` -static int64_t SbTimeToPosix(SbTime time) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/time_zone.md b/cobalt/site/docs/reference/starboard/modules/time_zone.md index 74d48172d63eb..c428babc2ae6d 100644 --- a/cobalt/site/docs/reference/starboard/modules/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/time_zone.md @@ -12,7 +12,7 @@ Provides access to the system time zone information. The number of minutes west of the Greenwich Prime Meridian, NOT including Daylight Savings Time adjustments. -For example: PST/PDT is 480 minutes (28800 seconds, 8 hours). +For example: America/Los_Angeles is 480 minutes (28800 seconds, 8 hours). #### Definition @@ -34,14 +34,15 @@ SbTimeZone SbTimeZoneGetCurrent() ### SbTimeZoneGetName -Gets a string representation of the current timezone. Note that the string -representation can either be standard or daylight saving time. The output can be -of the form: 1) A three-letter abbreviation such as "PST" or "PDT" (preferred). -2) A time zone identifier such as "America/Los_Angeles" 3) An un-abbreviated -name such as "Pacific Standard Time". +Gets a string representation of the current timezone. The format should be in +the IANA format [https://data.iana.org/time-zones/theory.html#naming](https://data.iana.org/time-zones/theory.html#naming)) . +Names normally have the form AREA/LOCATION, where AREA is a continent or ocean, +and LOCATION is a specific location within the area. Typical names are +'Africa/Cairo', 'America/New_York', and 'Pacific/Honolulu'. #### Declaration ``` const char* SbTimeZoneGetName() ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/ui_navigation.md deleted file mode 100644 index cb41767130058..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/ui_navigation.md +++ /dev/null @@ -1,322 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `ui_navigation.h` - -API to allow applications to take advantage of the platform's native UI engine. -This is mainly to drive the animation of visual elements and to signal which of -those elements have focus. The implementation should not render any visual -elements; instead, it will be used to guide the app in where these elements -should be drawn. - -When the application creates the user interface, it will create SbUiNavItems for -interactable elements. Additionally, the app must specify the position and size -of these navigation items. As the app's user interface changes, it will create -and destroy navigation items as appropriate. - -For each render frame, the app will query the local transform for each -SbUiNavItem in case the native UI engine moves individual items in response to -user interaction. If the navigation item is a container, then the content offset -will also be queried to determine the placement of its content items. - -## Macros - -### kSbUiNavItemInvalid - -Well-defined value for an invalid navigation item. - -## Enums - -### SbUiNavItemType - -Navigation items may be one of the following types. This must be specified upon -item creation and may not change during the item's lifespan. - -#### Values - -* `kSbUiNavItemTypeFocus` - - This is a single focusable item. -* `kSbUiNavItemTypeContainer` - - This is a container of navigation items which can also be containers - themselves or focusable items. Containers themselves cannot be focused. - -## Typedefs - -### SbUiNavItem - -An opaque handle to an implementation-private structure representing a -navigation item. - -#### Definition - -``` -typedef struct SbUiNavItemPrivate* SbUiNavItem -``` - -## Structs - -### SbUiNavCallbacks - -This structure specifies all the callbacks which the platform UI engine should -invoke for various interaction events on navigation items. These callbacks may -be invoked from any thread at any frequency. The `callback_context` is the value -that was passed on creation of the relevant SbUiNavItem. - -#### Members - -* `void(*onblur)(SbUiNavItem item, void *callback_context)` - - Invoke when an item has lost focus. This is only used with focus items. -* `void(*onfocus)(SbUiNavItem item, void *callback_context)` - - Invoke when an item has gained focus. This is only used with focus items. -* `void(*onscroll)(SbUiNavItem item, void *callback_context)` - - Invoke when an item's content offset is changed. This is only used with - container items. - -### SbUiNavInterface - -This structure declares the interface to the UI navigation implementation. All -function pointers must be specified if the platform supports UI navigation. - -#### Members - -* `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks - *callbacks, void *callback_context)` - - Create a new navigation item. When the user interacts with this item the - appropriate SbUiNavCallbacks function will be invoked with the provided - `callback_context`. An item is not interactable until it is enabled. -* `void(*destroy_item)(SbUiNavItem item)` - - Destroy the given navigation item. If this is a content of another item, - then it will first be unregistered. Additionally, if this item contains - other items, then those will be unregistered as well, but they will not be - automatically destroyed. -* `void(*set_focus)(SbUiNavItem item)` - - This is used to manually force focus on a navigation item of type - kSbUiNavItemTypeFocus. Any previously focused navigation item should receive - the blur event. If the item is not transitively a content of the root item, - then this does nothing. - - Specifying kSbUiNavItemInvalid should remove focus from the UI navigation - system. -* `void(*set_item_enabled)(SbUiNavItem item, bool enabled)` - - This is used to enable or disable user interaction with the specified - navigation item. All navigation items are disabled when created, and they - must be explicitly enabled to allow user interaction. If a container is - disabled, then all of its contents are not interactable even though they - remain enabled. If `enabled` is false, it must be guaranteed that once this - function returns, no callbacks associated with this item will be invoked - until the item is re-enabled. -* `void(*set_item_dir)(SbUiNavItem item, SbUiNavItemDir dir)` - - This specifies directionality for container items. Containers within - containers do not inherit directionality. Directionality must be specified - for each container explicitly. - - This should work even if `item` is disabled. -* `void(*set_item_focus_duration)(SbUiNavItem item, float seconds)` - - Set the minimum amount of time the focus item should remain focused once it - becomes focused. This may be used to make important focus items harder to - navigate over. Focus may still be moved before `seconds` has elapsed by - using the set_focus() function. By default, item focus duration is 0 - seconds. -* `void(*set_item_size)(SbUiNavItem item, float width, float height)` - - Set the interactable size of the specified navigation item. By default, an - item's size is (0,0). -* `void(*set_item_transform)(SbUiNavItem item, const SbUiNavMatrix2x3 - *transform)` - - Set the transform for the navigation item and its contents if the item is a - container. This specifies the placement of the item's center within its - container. The transform origin is the center of the item. Distance is - measured in pixels with the origin being the top-left of the item's - container. By default, an item's transform is identity. -* `bool(*get_item_focus_transform)(SbUiNavItem item, SbUiNavMatrix4 - *out_transform)` - - Retrieve the focus transform matrix for the navigation item. The UI engine - may translate, rotate, and/or tilt focus items to reflect user interaction. - This transform should be multiplied with the item's transform to get its - position inside its container. The transform origin is the center of the - item. Return false if the item position should not be changed (i.e. the - transform should be treated as identity). -* `bool(*get_item_focus_vector)(SbUiNavItem item, float *out_x, float *out_y)` - - Retrieve a vector representing the focus location within a focused item. - This is used to provide feedback about user input that is too small to - result in a focus change. If there is no focus vector for the navigation - item, then return false and leave `out_x` and `out_y` unchanged. Otherwise, - return true and set the output values in the range of [-1, +1] with (out_x, - out_y) of (-1, -1) being the top-left corner of the navigation item and (0, - 0) being the center. -* `void(*set_item_container_window)(SbUiNavItem item, SbWindow window)` - - This attaches the given navigation item (which must be a container) to the - specified window. Navigation items are only interactable if they are - transitively attached to a window. - - The native UI engine should never change this navigation item's content - offset. It is assumed to be used as a proxy for the system window. - - A navigation item may only have a SbUiNavItem or SbWindow as its direct - container. The navigation item hierarchy is established using - set_item_container_item() with the root container attached to a SbWindow - using set_item_container_window() to enable interaction with all enabled - items in the hierarchy. - - If `item` is already registered with a different window, then this will - unregister it from that window then attach it to the given `window`. It is - an error to register more than one navigation item with any given window. If - `window` is kSbWindowInvalid, then this will unregister the `item` from its - current window if any. Upon destruction of `item` or `window`, the `item` is - automatically unregistered from the `window`. -* `void(*set_item_container_item)(SbUiNavItem item, SbUiNavItem container)` - - A container navigation item may contain other navigation items. However, it - is an error to have circular containment or for `container` to not be of - type kSbUiNavItemTypeContainer. If `item` already has a different container, - then this first serves that connection. If `container` is - kSbUiNavItemInvalid, then this removes `item` from its current container. - Upon destruction of `item` or `container`, the `item` is automatically - removed from the `container`. - - The position of items within a container are specified relative to the - container's position. The position of these content items are further - modified by the container's "content offset". - - For example, consider item A with position (5,5) and content offset (0,0). - Given item B with position (10,10) is registered as a content of item A. - - 1) Item B should be drawn at position (15,15). - - 2) If item A's content offset is changed to (10,0), then item B should be - drawn at position (5,15). - - Essentially, content items should be drawn at: [container position] + - [content position] - [container content offset] - - Content items may overlap within a container. This can cause obscured items - to be unfocusable. The only rule that needs to be followed is that contents - which are focus items can obscure other contents which are containers, but - not vice versa. The caller must ensure that content focus items do not - overlap other content focus items and content container items do not overlap - other content container items. -* `void(*set_item_content_offset)(SbUiNavItem item, float content_offset_x, - float content_offset_y)` - - Set the current content offset for the given container. This may be used to - force scrolling to make certain content items visible. A container item's - content offset helps determine where its content items should be drawn. - Essentially, a content item should be drawn at: [container position] + - [content position] - [container content offset] If `item` is not a - container, then this does nothing. By default, the content offset is (0,0). - - This should update the values returned by get_item_content_offset() even if - the `item` is disabled. -* `void(*get_item_content_offset)(SbUiNavItem item, float - *out_content_offset_x, float *out_content_offset_y)` - - Retrieve the current content offset for the navigation item. If `item` is - not a container, then the content offset is (0,0). - - The native UI engine should not change the content offset of a container - unless one of its contents (possibly recursively) is focused. This is to - allow seamlessly disabling then re-enabling focus items without having their - containers change offsets. -* `void(*do_batch_update)(void(*update_function)(void *), void *context)` - - Call `update_function` with `context` to perform a series of UI navigation - changes atomically before returning. - -### SbUiNavItemDir - -Navigation items of type kSbUiNavItemTypeContainer have directionality. If -directionality is not specified for a container, it should default to left-to- -right and top-to-bottom. - -``` -/// For left-to-right, content offset x = 0 shows the leftmost content. -/// |<--Container Size-->| -/// +--------------------+--------------------+--------------------+ -/// | Not selectable. | Selectable. | Selectable. | -/// | Offscreen. | Onscreen. | Offscreen. | -/// | Negative position. | Positive position. | Positive position. | -/// +--------------------+--------------------+--------------------+ -/// ^ -/// Content Offset X = 0. -/// -/// For right-to-left, content offset x = 0 shows the rightmost content. -/// |<--Container Size-->| -/// +--------------------+--------------------+--------------------+ -/// | Selectable. | Selectable. | Not selectable. | -/// | Offscreen. | Onscreen. | Offscreen. | -/// | Negative position. | Positive position. | Positive position. | -/// +--------------------+--------------------+--------------------+ -/// ^ -/// Content Offset X = 0. -``` - -``` - Top-to-bottom is similar to left-to-right, but for the Y position. - Bottom-to-top is similar to right-to-left, but for the Y position. -``` - -#### Members - -* `bool is_left_to_right` -* `bool is_top_to_bottom` - -### SbUiNavMatrix2x3 - -This represents a 2x3 transform matrix in row-major order. - -``` -/// | a b tx | -/// | c d ty | -``` - -#### Members - -* `float m` - -### SbUiNavMatrix4 - -This represents a 4x4 transform matrix in row-major order. - -#### Members - -* `float m` - -## Functions - -### SbUiNavGetInterface - -Retrieve the platform's UI navigation implementation. If the platform does not -provide one, then return false without modifying `out_interface`. Otherwise, -initialize all members of `out_interface` and return true. The `out_interface` -pointer must not be NULL. - -#### Declaration - -``` -bool SbUiNavGetInterface(SbUiNavInterface *out_interface) -``` - -### SbUiNavItemIsValid - -Returns whether the given navigation item handle is valid. - -#### Declaration - -``` -static bool SbUiNavItemIsValid(SbUiNavItem item) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/user.md b/cobalt/site/docs/reference/starboard/modules/user.md deleted file mode 100644 index 309b939d066e0..0000000000000 --- a/cobalt/site/docs/reference/starboard/modules/user.md +++ /dev/null @@ -1,133 +0,0 @@ -Project: /youtube/cobalt/_project.yaml -Book: /youtube/cobalt/_book.yaml - -# Starboard Module Reference: `user.h` - -Defines a user management API. This module defines functions only for managing -signed-in users. Platforms that do not have users must still implement this API, -always reporting a single user that is current and signed in. - -These APIs are NOT expected to be thread-safe, so either call them from a single -thread, or perform proper synchronization around all calls. - -## Macros - -### kSbUserInvalid - -Well-defined value for an invalid user. - -## Enums - -### SbUserPropertyId - -A set of string properties that can be queried on a user. - -#### Values - -* `kSbUserPropertyAvatarUrl` - - The URL to the avatar for a user. Avatars are not provided on all platforms. -* `kSbUserPropertyHomeDirectory` - - The path to a user's home directory, if supported on this platform. -* `kSbUserPropertyUserName` - - The username of a user, which may be the same as the User ID, or it may be - friendlier. -* `kSbUserPropertyUserId` - - A unique user ID of a user. - -## Typedefs - -### SbUser - -A handle to a user. - -#### Definition - -``` -typedef SbUserPrivate* SbUser -``` - -## Functions - -### SbUserGetCurrent - -Gets the current primary user, if one exists. This is the user that is -determined, in a platform-specific way, to be the primary user controlling the -application. For example, the determination might be made because that user -launched the app, though it should be made using whatever criteria are -appropriate for the platform. - -It is expected that there will be a unique SbUser per signed-in user, and that -the referenced objects will persist for the lifetime of the app. - -#### Declaration - -``` -SbUser SbUserGetCurrent() -``` - -### SbUserGetProperty - -Retrieves the value of `property_id` for `user` and places it in `out_value`. -The function returns: - -* `true` if the property value is retrieved successfully - -* `false` if `user` is invalid; if `property_id` isn't recognized, supported, - or set for `user`; or if `value_size` is too small. - -`user`: The user for which property size data is being retrieved. `property_id`: -The property for which the data is requested. `out_value`: The retrieved -property value. `value_size`: The size of the retrieved property value. - -#### Declaration - -``` -bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) -``` - -### SbUserGetPropertySize - -Returns the size of the value of `property_id` for `user`, INCLUDING the -terminating null character. The function returns `0` if `user` is invalid or if -`property_id` is not recognized, supported, or set for the user. - -`user`: The user for which property size data is being retrieved. `property_id`: -The property for which the data is requested. - -#### Declaration - -``` -int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) -``` - -### SbUserGetSignedIn - -Gets a list of up to `users_size` signed-in users and places the results in -`out_users`. The return value identifies the actual number of signed-in users, -which may be greater or less than `users_size`. - -It is expected that there will be a unique `SbUser` per signed-in user and that -the referenced objects will persist for the lifetime of the app. - -`out_users`: Handles for the retrieved users. `users_size`: The maximum number -of signed-in users to retrieve. - -#### Declaration - -``` -int SbUserGetSignedIn(SbUser *out_users, int users_size) -``` - -### SbUserIsValid - -Returns whether the given user handle is valid. - -#### Declaration - -``` -static bool SbUserIsValid(SbUser user) -``` diff --git a/cobalt/site/docs/reference/starboard/modules/window.md b/cobalt/site/docs/reference/starboard/modules/window.md index 25845315aed4f..6e5ee0e262764 100644 --- a/cobalt/site/docs/reference/starboard/modules/window.md +++ b/cobalt/site/docs/reference/starboard/modules/window.md @@ -7,11 +7,6 @@ Provides functionality to handle Window creation and management. ## Macros -### kSbEventOnScreenKeyboardInvalidTicket - -System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. - ### kSbWindowInvalid Well-defined value for an invalid window handle. @@ -48,18 +43,6 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect - -Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This -structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. - -#### Members - -* `float x` -* `float y` -* `float width` -* `float height` - ### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of @@ -198,3 +181,4 @@ Sets the default options for system windows. ``` void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` +