diff --git a/cobalt/site/docker/Dockerfile b/cobalt/site/docker/Dockerfile index b22bc09b5aa9..1acba94d9995 100644 --- a/cobalt/site/docker/Dockerfile +++ b/cobalt/site/docker/Dockerfile @@ -13,11 +13,12 @@ # limitations under the License. ARG FROM_IMAGE -FROM ${FROM_IMAGE:-gcr.io/cloud-marketplace-containers/google/debian10} +FROM ${FROM_IMAGE:-gcr.io/cloud-marketplace-containers/google/debian11} RUN apt update -qqy \ && apt install -qqy --no-install-recommends \ curl \ + ca-certificates \ doxygen \ git \ python3 \ diff --git a/cobalt/site/docs/gen/cobalt/doc/voice_search.md b/cobalt/site/docs/gen/cobalt/doc/voice_search.md index c8bfcc43ea7e..e0eabb7eb428 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 c0758069251e..c0e46b5bdb05 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 5fb5f90d6b1e..0378393248e8 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 93d3de570f02..6608dc18e205 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_overview.md b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md index 4bdc6bf19632..75f2ac78202b 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 @@ -308,8 +308,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: ``` 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 2bfc1e3b34dd..b9c3d45260a4 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/style.md b/cobalt/site/docs/gen/starboard/doc/style.md index 84c55f19efb3..22998a5babe0 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 b33e73bcbc10..02afb2f75d99 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 9c57bb9da38c..5cc4b7b0ea55 100644 --- a/cobalt/site/docs/reference/starboard/configuration-public.md +++ b/cobalt/site/docs/reference/starboard/configuration-public.md @@ -35,3 +35,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 437575c1d454..867949f67600 100644 --- a/cobalt/site/docs/reference/starboard/gn-configuration.md +++ b/cobalt/site/docs/reference/starboard/gn-configuration.md @@ -14,7 +14,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"`. | @@ -27,11 +27,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/accessibility.md b/cobalt/site/docs/reference/starboard/modules/13/accessibility.md index 5c66ba442803..8f2a652445a9 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/atomic.md index 0ed31cb649ec..9653e53cecd3 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/audio_sink.md index 9277c70837b0..3cb7a8295805 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md index 72dc9327ed1e..4b2cab30de3d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md index 2d8f30b5fdce..cd381c5e3f9e 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/configuration.md b/cobalt/site/docs/reference/starboard/modules/13/configuration.md index d0ba3c7196f8..fa3e15a4e160 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md index e2aa35f2bb1a..2057469dcd1b 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/decode_target.md index 2794d9ddfbe2..c736ee46431d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/13/decode_target.md @@ -11,8 +11,7 @@ An SbDecodeTarget can be passed into any function which decodes video or image data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. - -## SbDecodeTargetFormat +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 @@ -20,8 +19,7 @@ be easier to render. Some may take less memory. Each decoder needs to support the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. - -## 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 +31,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 @@ -202,8 +156,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 @@ -363,8 +316,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 +347,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/13/directory.md index 6f845f6567a9..1c0f90482119 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/drm.md b/cobalt/site/docs/reference/starboard/modules/13/drm.md index f42e43bf3db7..659cc3ddaefb 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/13/drm.md @@ -415,3 +415,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/13/egl.md index 4afff1aa236e..69db1b835ea8 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/13/egl.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between EGL implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## EGL Version +EGL Version This API has the ability to support EGL 1.5, however it is not required to support anything beyond EGL 1.4. The user is responsible for ensuring that the @@ -144,3 +143,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/13/event.md index 256d418b45e0..2359e6e51d7f 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/event.md +++ b/cobalt/site/docs/reference/starboard/modules/13/event.md @@ -4,8 +4,7 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `event.h` Defines the event system that wraps the Starboard main loop and entry point. - -## The Starboard Application Lifecycle +The Starboard Application Lifecycle ``` * ---------- @@ -313,7 +312,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -399,5 +398,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/13/file.md b/cobalt/site/docs/reference/starboard/modules/13/file.md index 103af475ace1..fd9b4fbf5c21 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/file.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/gles.md b/cobalt/site/docs/reference/starboard/modules/13/gles.md index 77bc07e71c82..0822c6b70a80 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/13/gles.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between GLES implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## GLES Version +GLES Version This API has the ability to support GLES 3.0, however platforms are not required to support anything beyond GLES 2.0. The caller is responsible for ensuring that @@ -459,3 +458,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/image.md b/cobalt/site/docs/reference/starboard/modules/13/image.md index 945938a09903..029a1ccfd6fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/image.md +++ b/cobalt/site/docs/reference/starboard/modules/13/image.md @@ -10,8 +10,7 @@ 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 +SbImageIsDecodeSupported and SbImageDecode Example ``` SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); @@ -26,6 +25,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +75,4 @@ indefinitely. ``` bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/input.md b/cobalt/site/docs/reference/starboard/modules/13/input.md index a858c73e3e89..d2dd2db32dc5 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/input.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/key.md index dd7712fd81bb..853f820a65ad 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/key.md +++ b/cobalt/site/docs/reference/starboard/modules/13/key.md @@ -290,3 +290,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/13/log.md index 6cf3a491a2a7..60b361d4697d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/log.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/media.md index acf95ee1ef9a..3da58a02548c 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/media.md +++ b/cobalt/site/docs/reference/starboard/modules/13/media.md @@ -177,7 +177,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. @@ -449,7 +449,7 @@ 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 +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 `encryptionscheme` is set to "". The implementation should return @@ -517,7 +517,7 @@ 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 +larger value may increase the memory consumption of media buffers. `type`: the media type of the stream (audio or video). #### Declaration @@ -532,7 +532,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 @@ -542,26 +542,26 @@ 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). +padding. `type`: the media type of the stream (audio or video). #### Declaration @@ -573,10 +573,10 @@ int SbMediaGetBufferPadding(SbMediaType type) 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 @@ -676,7 +676,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 @@ -689,15 +689,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/13/memory.md b/cobalt/site/docs/reference/starboard/modules/13/memory.md index 0c404e36ea30..e587c257ff3f 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/13/memory.md @@ -4,14 +4,12 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. - -## Porters +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 +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 @@ -30,8 +28,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 +342,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/13/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md index 505d2a7d0347..fa78eaa52c6f 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/microphone.md b/cobalt/site/docs/reference/starboard/modules/13/microphone.md index bcf9e4355e65..497cbe91cec4 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/mutex.md b/cobalt/site/docs/reference/starboard/modules/13/mutex.md index 82ff8500ab8d..37e2ce06bab4 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/once.md b/cobalt/site/docs/reference/starboard/modules/13/once.md index d77302467f8b..de4867461edc 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/once.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/player.md b/cobalt/site/docs/reference/starboard/modules/13/player.md index 0dab908addc8..56371e7705c1 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/player.md +++ b/cobalt/site/docs/reference/starboard/modules/13/player.md @@ -184,14 +184,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 +242,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. @@ -325,13 +325,13 @@ 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. +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 @@ -465,7 +465,7 @@ 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 +473,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/13/socket.md b/cobalt/site/docs/reference/starboard/modules/13/socket.md index 744c04e3847d..e7f4bc9e7156 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/socket_waiter.md index f1c6bd8b9f2f..54bc7eae0645 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/speech_synthesis.md index 0bd6e65b6379..ea4ad46b3f87 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/storage.md index f20016113be1..0311c62bf10a 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/string.md b/cobalt/site/docs/reference/starboard/modules/13/string.md index 3fed809df461..bd04c99c9419 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/string.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/system.md b/cobalt/site/docs/reference/starboard/modules/13/system.md index d3052d1ccde1..1b23325cc293 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/system.md +++ b/cobalt/site/docs/reference/starboard/modules/13/system.md @@ -730,3 +730,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/13/thread.md b/cobalt/site/docs/reference/starboard/modules/13/thread.md index 56c7898a12b4..e9094e39df5c 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/time.md b/cobalt/site/docs/reference/starboard/modules/13/time.md index a6228cc0de6c..e5c8cd2fedd0 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/time.md +++ b/cobalt/site/docs/reference/starboard/modules/13/time.md @@ -150,3 +150,4 @@ times. ``` static int64_t SbTimeToPosix(SbTime time) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/13/time_zone.md b/cobalt/site/docs/reference/starboard/modules/13/time_zone.md index 74d48172d63e..c428babc2ae6 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md index cb4176713005..34b5114e71cd 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/user.md b/cobalt/site/docs/reference/starboard/modules/13/user.md index 309b939d066e..9442ced8f978 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/user.md +++ b/cobalt/site/docs/reference/starboard/modules/13/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/13/window.md b/cobalt/site/docs/reference/starboard/modules/13/window.md index acea84d4c7d0..12e4bb2429b3 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/window.md +++ b/cobalt/site/docs/reference/starboard/modules/13/window.md @@ -10,7 +10,8 @@ Provides functionality to handle Window creation and management. ### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. +kSbEventOnScreenKeyboardInvalidTicket. TODO(b/151173891): This should be moved +to the extension header ### kSbWindowInvalid @@ -52,6 +53,7 @@ Options that can be requested at window creation time. Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. +TODO(b/151173891): This should be moved to the extension header #### Members @@ -328,3 +330,4 @@ hidden. ``` void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) ``` + diff --git a/cobalt/site/docs/reference/starboard/modules/14/accessibility.md b/cobalt/site/docs/reference/starboard/modules/14/accessibility.md index 5c66ba442803..8f2a652445a9 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 0ed31cb649ec..9653e53cecd3 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 9277c70837b0..3cb7a8295805 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 72dc9327ed1e..4b2cab30de3d 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 2d8f30b5fdce..cd381c5e3f9e 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 d0ba3c7196f8..fa3e15a4e160 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 e2aa35f2bb1a..2057469dcd1b 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 1e98db5db54d..50ae1ac7833c 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/14/decode_target.md @@ -11,8 +11,7 @@ An SbDecodeTarget can be passed into any function which decodes video or image data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. - -## SbDecodeTargetFormat +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 @@ -20,8 +19,7 @@ be easier to render. Some may take less memory. Each decoder needs to support the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. - -## 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 +31,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 @@ -207,8 +161,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 @@ -368,8 +321,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 +352,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 6f845f6567a9..1c0f90482119 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 f42e43bf3db7..659cc3ddaefb 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/14/drm.md @@ -415,3 +415,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 4afff1aa236e..69db1b835ea8 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/14/egl.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between EGL implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## EGL Version +EGL Version This API has the ability to support EGL 1.5, however it is not required to support anything beyond EGL 1.4. The user is responsible for ensuring that the @@ -144,3 +143,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 256d418b45e0..2359e6e51d7f 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/event.md +++ b/cobalt/site/docs/reference/starboard/modules/14/event.md @@ -4,8 +4,7 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `event.h` Defines the event system that wraps the Starboard main loop and entry point. - -## The Starboard Application Lifecycle +The Starboard Application Lifecycle ``` * ---------- @@ -313,7 +312,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -399,5 +398,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 103af475ace1..fd9b4fbf5c21 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 77bc07e71c82..0822c6b70a80 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/14/gles.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between GLES implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## GLES Version +GLES Version This API has the ability to support GLES 3.0, however platforms are not required to support anything beyond GLES 2.0. The caller is responsible for ensuring that @@ -459,3 +458,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 945938a09903..029a1ccfd6fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/image.md +++ b/cobalt/site/docs/reference/starboard/modules/14/image.md @@ -10,8 +10,7 @@ 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 +SbImageIsDecodeSupported and SbImageDecode Example ``` SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); @@ -26,6 +25,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +75,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 a858c73e3e89..d2dd2db32dc5 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 dd7712fd81bb..853f820a65ad 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 6cf3a491a2a7..60b361d4697d 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 732868607939..f9a3b7fa0601 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. @@ -452,7 +452,7 @@ 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 +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 `encryptionscheme` is set to "". The implementation should return @@ -534,7 +534,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 +544,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 +575,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 @@ -678,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 @@ -691,15 +691,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 0c404e36ea30..e587c257ff3f 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/14/memory.md @@ -4,14 +4,12 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. - -## Porters +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 +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 @@ -30,8 +28,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 +342,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 505d2a7d0347..fa78eaa52c6f 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 bcf9e4355e65..497cbe91cec4 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 82ff8500ab8d..37e2ce06bab4 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 d77302467f8b..de4867461edc 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 0dab908addc8..56371e7705c1 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/player.md +++ b/cobalt/site/docs/reference/starboard/modules/14/player.md @@ -184,14 +184,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 +242,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. @@ -325,13 +325,13 @@ 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. +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 @@ -465,7 +465,7 @@ 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 +473,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 744c04e3847d..e7f4bc9e7156 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 f1c6bd8b9f2f..54bc7eae0645 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 0bd6e65b6379..ea4ad46b3f87 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 f20016113be1..0311c62bf10a 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 3fed809df461..bd04c99c9419 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 59e70188e05a..6b8c7a6abcc4 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 56c7898a12b4..e9094e39df5c 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 a6228cc0de6c..e5c8cd2fedd0 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 74d48172d63e..c428babc2ae6 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 cb4176713005..34b5114e71cd 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 309b939d066e..9442ced8f978 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 acea84d4c7d0..12e4bb2429b3 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/window.md +++ b/cobalt/site/docs/reference/starboard/modules/14/window.md @@ -10,7 +10,8 @@ Provides functionality to handle Window creation and management. ### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. +kSbEventOnScreenKeyboardInvalidTicket. TODO(b/151173891): This should be moved +to the extension header ### kSbWindowInvalid @@ -52,6 +53,7 @@ Options that can be requested at window creation time. Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. +TODO(b/151173891): This should be moved to the extension header #### Members @@ -328,3 +330,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 5c66ba442803..8f2a652445a9 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 0ed31cb649ec..9653e53cecd3 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 9277c70837b0..3cb7a8295805 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 72dc9327ed1e..4b2cab30de3d 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 2d8f30b5fdce..cd381c5e3f9e 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 d0ba3c7196f8..fa3e15a4e160 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 e2aa35f2bb1a..2057469dcd1b 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 1e98db5db54d..50ae1ac7833c 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/15/decode_target.md @@ -11,8 +11,7 @@ An SbDecodeTarget can be passed into any function which decodes video or image data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. - -## SbDecodeTargetFormat +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 @@ -20,8 +19,7 @@ be easier to render. Some may take less memory. Each decoder needs to support the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. - -## 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 +31,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 @@ -207,8 +161,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 @@ -368,8 +321,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 +352,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 6f845f6567a9..1c0f90482119 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 f42e43bf3db7..659cc3ddaefb 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/15/drm.md @@ -415,3 +415,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 4afff1aa236e..69db1b835ea8 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/15/egl.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between EGL implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## EGL Version +EGL Version This API has the ability to support EGL 1.5, however it is not required to support anything beyond EGL 1.4. The user is responsible for ensuring that the @@ -144,3 +143,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 fdfa85670d1e..ca663d14aaf1 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/event.md +++ b/cobalt/site/docs/reference/starboard/modules/15/event.md @@ -4,8 +4,7 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `event.h` Defines the event system that wraps the Starboard main loop and entry point. - -## The Starboard Application Lifecycle +The Starboard Application Lifecycle ``` * ---------- @@ -313,7 +312,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -399,7 +398,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 +411,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 103af475ace1..fd9b4fbf5c21 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 77bc07e71c82..0822c6b70a80 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/15/gles.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between GLES implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## GLES Version +GLES Version This API has the ability to support GLES 3.0, however platforms are not required to support anything beyond GLES 2.0. The caller is responsible for ensuring that @@ -459,3 +458,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 945938a09903..029a1ccfd6fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/image.md +++ b/cobalt/site/docs/reference/starboard/modules/15/image.md @@ -10,8 +10,7 @@ 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 +SbImageIsDecodeSupported and SbImageDecode Example ``` SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); @@ -26,6 +25,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +75,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 a858c73e3e89..d2dd2db32dc5 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 ed87e531f4fc..c07837e233c8 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 6cf3a491a2a7..60b361d4697d 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 42871c2abda4..f202c5607d93 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 @@ -466,7 +466,7 @@ 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 +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 `encryptionscheme` is set to "". The implementation should return @@ -548,7 +548,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 +558,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 +589,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 @@ -692,10 +692,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 5b13119060ec..caa0f6fa56c9 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/15/memory.md @@ -4,14 +4,12 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. - -## Porters +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 +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 @@ -30,8 +28,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 +329,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 5e49693e70bc..000000000000 --- 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 bcf9e4355e65..497cbe91cec4 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 82ff8500ab8d..37e2ce06bab4 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 d77302467f8b..de4867461edc 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 0382642a35fe..ebebb9860f77 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/player.md +++ b/cobalt/site/docs/reference/starboard/modules/15/player.md @@ -192,14 +192,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 +250,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. @@ -397,13 +397,13 @@ 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. +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 @@ -537,7 +537,7 @@ 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 +545,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 744c04e3847d..e7f4bc9e7156 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 f1c6bd8b9f2f..54bc7eae0645 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 0bd6e65b6379..ea4ad46b3f87 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 f20016113be1..0311c62bf10a 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 3fed809df461..bd04c99c9419 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 86437a3d0804..04fceecbe83e 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 56c7898a12b4..e9094e39df5c 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 a6228cc0de6c..e5c8cd2fedd0 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 74d48172d63e..c428babc2ae6 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 cb4176713005..34b5114e71cd 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 309b939d066e..9442ced8f978 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 acea84d4c7d0..12e4bb2429b3 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/window.md +++ b/cobalt/site/docs/reference/starboard/modules/15/window.md @@ -10,7 +10,8 @@ Provides functionality to handle Window creation and management. ### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. +kSbEventOnScreenKeyboardInvalidTicket. TODO(b/151173891): This should be moved +to the extension header ### kSbWindowInvalid @@ -52,6 +53,7 @@ Options that can be requested at window creation time. Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. +TODO(b/151173891): This should be moved to the extension header #### Members @@ -328,3 +330,4 @@ hidden. ``` 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 5c66ba442803..8f2a652445a9 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 0ed31cb649ec..9653e53cecd3 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 9277c70837b0..3cb7a8295805 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 index 72dc9327ed1e..4b2cab30de3d 100644 --- a/cobalt/site/docs/reference/starboard/modules/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/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/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/condition_variable.md index 2d8f30b5fdce..cd381c5e3f9e 100644 --- a/cobalt/site/docs/reference/starboard/modules/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/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/configuration.md b/cobalt/site/docs/reference/starboard/modules/configuration.md index 1a3502e270ac..fa3e15a4e160 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration.md @@ -65,7 +65,10 @@ header available. ### SB_HAS_64_BIT_ATOMICS -Whether the current platform has 64-bit atomic operations. +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) @@ -86,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 @@ -98,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. @@ -123,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/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/cpu_features.md index e2aa35f2bb1a..2057469dcd1b 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 6df175b6ba9a..50ae1ac7833c 100644 --- a/cobalt/site/docs/reference/starboard/modules/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/decode_target.md @@ -11,8 +11,7 @@ An SbDecodeTarget can be passed into any function which decodes video or image data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. - -## SbDecodeTargetFormat +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 @@ -20,8 +19,7 @@ be easier to render. Some may take less memory. Each decoder needs to support the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. - -## 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 +31,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 @@ -207,8 +161,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 @@ -399,3 +352,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 6f845f6567a9..1c0f90482119 100644 --- a/cobalt/site/docs/reference/starboard/modules/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/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/drm.md b/cobalt/site/docs/reference/starboard/modules/drm.md index f42e43bf3db7..659cc3ddaefb 100644 --- a/cobalt/site/docs/reference/starboard/modules/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/drm.md @@ -415,3 +415,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 4afff1aa236e..69db1b835ea8 100644 --- a/cobalt/site/docs/reference/starboard/modules/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/egl.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between EGL implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## EGL Version +EGL Version This API has the ability to support EGL 1.5, however it is not required to support anything beyond EGL 1.4. The user is responsible for ensuring that the @@ -144,3 +143,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 b8005a5d6c36..ca663d14aaf1 100644 --- a/cobalt/site/docs/reference/starboard/modules/event.md +++ b/cobalt/site/docs/reference/starboard/modules/event.md @@ -4,8 +4,7 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `event.h` Defines the event system that wraps the Starboard main loop and entry point. - -## The Starboard Application Lifecycle +The Starboard Application Lifecycle ``` * ---------- @@ -236,6 +235,16 @@ 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. * `kSbEventTypeAccessibilityCaptionSettingsChanged` One or more of the fields returned by SbAccessibilityGetCaptionSettings has @@ -303,7 +312,7 @@ Structure representing a Starboard event and its data. #### Members * `SbEventType type` -* `SbTimeMonotonic timestamp` +* `int64_t timestamp` * `void * data` ### SbEventStartData @@ -389,7 +398,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 +411,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 103af475ace1..fd9b4fbf5c21 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 @@ -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/gles.md b/cobalt/site/docs/reference/starboard/modules/gles.md index 77bc07e71c82..0822c6b70a80 100644 --- a/cobalt/site/docs/reference/starboard/modules/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/gles.md @@ -10,8 +10,7 @@ platforms. This API is designed to abstract the differences between GLES implementations and versions on different systems, and to remove the requirement for any other code to directly pull in and use these system libraries. - -## GLES Version +GLES Version This API has the ability to support GLES 3.0, however platforms are not required to support anything beyond GLES 2.0. The caller is responsible for ensuring that @@ -459,3 +458,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 index 945938a09903..029a1ccfd6fa 100644 --- a/cobalt/site/docs/reference/starboard/modules/image.md +++ b/cobalt/site/docs/reference/starboard/modules/image.md @@ -10,8 +10,7 @@ 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 +SbImageIsDecodeSupported and SbImageDecode Example ``` SbDecodeTargetProvider* provider = GetProviderFromSomewhere(); @@ -26,6 +25,7 @@ if (!SbImageIsDecodeSupported(mime_type, format)) { SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); + ``` ## Functions @@ -75,3 +75,4 @@ indefinitely. ``` 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 a858c73e3e89..d2dd2db32dc5 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 ed87e531f4fc..c07837e233c8 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 6cf3a491a2a7..60b361d4697d 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 0619503f46f6..f202c5607d93 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 @@ -466,7 +466,7 @@ 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 +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 `encryptionscheme` is set to "". The implementation should return @@ -531,13 +531,24 @@ 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. + +#### Declaration + +``` +int SbMediaGetBufferAlignment() +``` + ### 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. +stack will allocate individual buffers directly using malloc functions. #### Declaration @@ -547,19 +558,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 @@ -578,7 +589,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 @@ -681,10 +692,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 5b13119060ec..caa0f6fa56c9 100644 --- a/cobalt/site/docs/reference/starboard/modules/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/memory.md @@ -4,14 +4,12 @@ Book: /youtube/cobalt/_book.yaml # Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. - -## Porters +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 +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 @@ -30,8 +28,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 +329,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/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/memory_reporter.md deleted file mode 100644 index 5e49693e70bc..000000000000 --- 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 bcf9e4355e65..497cbe91cec4 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 index 82ff8500ab8d..37e2ce06bab4 100644 --- a/cobalt/site/docs/reference/starboard/modules/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/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/once.md b/cobalt/site/docs/reference/starboard/modules/once.md index d77302467f8b..de4867461edc 100644 --- a/cobalt/site/docs/reference/starboard/modules/once.md +++ b/cobalt/site/docs/reference/starboard/modules/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/player.md b/cobalt/site/docs/reference/starboard/modules/player.md index 0382642a35fe..ebebb9860f77 100644 --- a/cobalt/site/docs/reference/starboard/modules/player.md +++ b/cobalt/site/docs/reference/starboard/modules/player.md @@ -192,14 +192,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 +250,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. @@ -397,13 +397,13 @@ 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. +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 @@ -537,7 +537,7 @@ 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 +545,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 744c04e3847d..e7f4bc9e7156 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 f1c6bd8b9f2f..54bc7eae0645 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 0bd6e65b6379..ea4ad46b3f87 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 f20016113be1..0311c62bf10a 100644 --- a/cobalt/site/docs/reference/starboard/modules/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/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/string.md b/cobalt/site/docs/reference/starboard/modules/string.md index 3fed809df461..bd04c99c9419 100644 --- a/cobalt/site/docs/reference/starboard/modules/string.md +++ b/cobalt/site/docs/reference/starboard/modules/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/system.md b/cobalt/site/docs/reference/starboard/modules/system.md index 86437a3d0804..04fceecbe83e 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 56c7898a12b4..e9094e39df5c 100644 --- a/cobalt/site/docs/reference/starboard/modules/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/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/time.md b/cobalt/site/docs/reference/starboard/modules/time.md index a6228cc0de6c..e5c8cd2fedd0 100644 --- a/cobalt/site/docs/reference/starboard/modules/time.md +++ b/cobalt/site/docs/reference/starboard/modules/time.md @@ -150,3 +150,4 @@ times. ``` 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 74d48172d63e..c428babc2ae6 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 index cb4176713005..34b5114e71cd 100644 --- a/cobalt/site/docs/reference/starboard/modules/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/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/user.md b/cobalt/site/docs/reference/starboard/modules/user.md index 309b939d066e..9442ced8f978 100644 --- a/cobalt/site/docs/reference/starboard/modules/user.md +++ b/cobalt/site/docs/reference/starboard/modules/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/window.md b/cobalt/site/docs/reference/starboard/modules/window.md index 25845315aed4..12e4bb2429b3 100644 --- a/cobalt/site/docs/reference/starboard/modules/window.md +++ b/cobalt/site/docs/reference/starboard/modules/window.md @@ -10,7 +10,8 @@ Provides functionality to handle Window creation and management. ### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value -kSbEventOnScreenKeyboardInvalidTicket. +kSbEventOnScreenKeyboardInvalidTicket. TODO(b/151173891): This should be moved +to the extension header ### kSbWindowInvalid @@ -52,6 +53,7 @@ Options that can be requested at window creation time. Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. +TODO(b/151173891): This should be moved to the extension header #### Members @@ -95,6 +97,20 @@ 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 @@ -135,6 +151,20 @@ 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. @@ -148,6 +178,18 @@ 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 @@ -176,6 +218,29 @@ 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. @@ -186,6 +251,28 @@ 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. @@ -198,3 +285,49 @@ 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) +``` +