From 0a42d9b5e6853d9c9b68c43943d7cb5e8eda026d Mon Sep 17 00:00:00 2001 From: cobalt-github-releaser-bot <95661244+cobalt-github-releaser-bot@users.noreply.github.com> Date: Tue, 28 Nov 2023 16:27:19 -0800 Subject: [PATCH] Cherry pick PR #1943: Update generated docs with new markdown headers (#1991) Refer to the original PR: https://github.com/youtube/cobalt/pull/1943 Generation scripts are updated in an internal change. b/236404667 --------- Co-authored-by: Oscar Vestlie --- cobalt/doc/memory_tuning.md | 24 +-- .../site/docs/gen/cobalt/doc/memory_tuning.md | 22 +-- .../starboard/tools/doc/abstract_launcher.md | 7 +- .../docs/gen/starboard/tools/doc/testing.md | 7 +- .../starboard/configuration-public.md | 8 +- .../reference/starboard/gn-configuration.md | 8 +- .../starboard/modules/13/accessibility.md | 66 +++---- .../reference/starboard/modules/13/atomic.md | 44 ++--- .../starboard/modules/13/audio_sink.md | 64 +++---- .../starboard/modules/13/byte_swap.md | 34 ++-- .../modules/13/condition_variable.md | 54 +++--- .../starboard/modules/13/configuration.md | 70 +++---- .../modules/13/configuration_constants.md | 60 +++--- .../starboard/modules/13/cpu_features.md | 34 ++-- .../starboard/modules/13/decode_target.md | 90 ++++----- .../starboard/modules/13/directory.md | 44 ++--- .../reference/starboard/modules/13/drm.md | 114 +++++------ .../reference/starboard/modules/13/egl.md | 40 ++-- .../reference/starboard/modules/13/event.md | 62 +++--- .../reference/starboard/modules/13/export.md | 16 +- .../reference/starboard/modules/13/file.md | 108 +++++------ .../reference/starboard/modules/13/gles.md | 32 ++-- .../reference/starboard/modules/13/image.md | 20 +- .../reference/starboard/modules/13/input.md | 28 +-- .../reference/starboard/modules/13/key.md | 18 +- .../reference/starboard/modules/13/log.md | 52 ++--- .../reference/starboard/modules/13/media.md | 140 +++++++------- .../reference/starboard/modules/13/memory.md | 104 +++++----- .../starboard/modules/13/memory_reporter.md | 38 ++-- .../starboard/modules/13/microphone.md | 74 ++++---- .../reference/starboard/modules/13/mutex.md | 50 ++--- .../reference/starboard/modules/13/once.md | 28 +-- .../reference/starboard/modules/13/player.md | 112 +++++------ .../reference/starboard/modules/13/socket.md | 152 +++++++-------- .../starboard/modules/13/socket_waiter.md | 66 +++---- .../starboard/modules/13/speech_synthesis.md | 22 +-- .../reference/starboard/modules/13/storage.md | 48 ++--- .../reference/starboard/modules/13/string.md | 50 ++--- .../reference/starboard/modules/13/system.md | 178 +++++++++--------- .../reference/starboard/modules/13/thread.md | 174 ++++++++--------- .../reference/starboard/modules/13/time.md | 66 +++---- .../starboard/modules/13/time_zone.md | 24 +-- .../reference/starboard/modules/13/types.md | 12 +- .../starboard/modules/13/ui_navigation.md | 56 +++--- .../reference/starboard/modules/13/user.md | 46 ++--- .../reference/starboard/modules/13/window.md | 104 +++++----- .../starboard/modules/14/accessibility.md | 66 +++---- .../reference/starboard/modules/14/atomic.md | 44 ++--- .../starboard/modules/14/audio_sink.md | 64 +++---- .../starboard/modules/14/byte_swap.md | 34 ++-- .../modules/14/condition_variable.md | 54 +++--- .../starboard/modules/14/configuration.md | 70 +++---- .../modules/14/configuration_constants.md | 62 +++--- .../starboard/modules/14/cpu_features.md | 34 ++-- .../starboard/modules/14/decode_target.md | 90 ++++----- .../starboard/modules/14/directory.md | 44 ++--- .../reference/starboard/modules/14/drm.md | 114 +++++------ .../reference/starboard/modules/14/egl.md | 40 ++-- .../reference/starboard/modules/14/event.md | 62 +++--- .../reference/starboard/modules/14/export.md | 16 +- .../reference/starboard/modules/14/file.md | 108 +++++------ .../reference/starboard/modules/14/gles.md | 32 ++-- .../reference/starboard/modules/14/image.md | 20 +- .../reference/starboard/modules/14/input.md | 28 +-- .../reference/starboard/modules/14/key.md | 18 +- .../reference/starboard/modules/14/log.md | 52 ++--- .../reference/starboard/modules/14/media.md | 140 +++++++------- .../reference/starboard/modules/14/memory.md | 104 +++++----- .../starboard/modules/14/memory_reporter.md | 38 ++-- .../starboard/modules/14/microphone.md | 74 ++++---- .../reference/starboard/modules/14/mutex.md | 50 ++--- .../reference/starboard/modules/14/once.md | 28 +-- .../reference/starboard/modules/14/player.md | 112 +++++------ .../reference/starboard/modules/14/socket.md | 152 +++++++-------- .../starboard/modules/14/socket_waiter.md | 66 +++---- .../starboard/modules/14/speech_synthesis.md | 22 +-- .../reference/starboard/modules/14/storage.md | 48 ++--- .../reference/starboard/modules/14/string.md | 50 ++--- .../reference/starboard/modules/14/system.md | 170 ++++++++--------- .../reference/starboard/modules/14/thread.md | 174 ++++++++--------- .../reference/starboard/modules/14/time.md | 66 +++---- .../starboard/modules/14/time_zone.md | 24 +-- .../reference/starboard/modules/14/types.md | 12 +- .../starboard/modules/14/ui_navigation.md | 56 +++--- .../reference/starboard/modules/14/user.md | 46 ++--- .../reference/starboard/modules/14/window.md | 104 +++++----- .../starboard/modules/15/accessibility.md | 66 +++---- .../reference/starboard/modules/15/atomic.md | 44 ++--- .../starboard/modules/15/audio_sink.md | 64 +++---- .../starboard/modules/15/byte_swap.md | 34 ++-- .../modules/15/condition_variable.md | 54 +++--- .../starboard/modules/15/configuration.md | 70 +++---- .../modules/15/configuration_constants.md | 60 +++--- .../starboard/modules/15/cpu_features.md | 34 ++-- .../starboard/modules/15/decode_target.md | 90 ++++----- .../starboard/modules/15/directory.md | 44 ++--- .../reference/starboard/modules/15/drm.md | 114 +++++------ .../reference/starboard/modules/15/egl.md | 40 ++-- .../reference/starboard/modules/15/event.md | 66 +++---- .../reference/starboard/modules/15/export.md | 16 +- .../reference/starboard/modules/15/file.md | 108 +++++------ .../reference/starboard/modules/15/gles.md | 32 ++-- .../reference/starboard/modules/15/image.md | 20 +- .../reference/starboard/modules/15/input.md | 28 +-- .../reference/starboard/modules/15/key.md | 18 +- .../reference/starboard/modules/15/log.md | 52 ++--- .../reference/starboard/modules/15/media.md | 144 +++++++------- .../reference/starboard/modules/15/memory.md | 100 +++++----- .../starboard/modules/15/microphone.md | 74 ++++---- .../reference/starboard/modules/15/mutex.md | 50 ++--- .../reference/starboard/modules/15/once.md | 28 +-- .../reference/starboard/modules/15/player.md | 120 ++++++------ .../reference/starboard/modules/15/socket.md | 152 +++++++-------- .../starboard/modules/15/socket_waiter.md | 66 +++---- .../starboard/modules/15/speech_synthesis.md | 22 +-- .../reference/starboard/modules/15/storage.md | 48 ++--- .../reference/starboard/modules/15/string.md | 50 ++--- .../reference/starboard/modules/15/system.md | 162 ++++++++-------- .../reference/starboard/modules/15/thread.md | 174 ++++++++--------- .../reference/starboard/modules/15/time.md | 66 +++---- .../starboard/modules/15/time_zone.md | 24 +-- .../reference/starboard/modules/15/types.md | 12 +- .../starboard/modules/15/ui_navigation.md | 56 +++--- .../reference/starboard/modules/15/user.md | 46 ++--- .../reference/starboard/modules/15/window.md | 104 +++++----- .../starboard/modules/accessibility.md | 66 +++---- .../reference/starboard/modules/atomic.md | 44 ++--- .../reference/starboard/modules/audio_sink.md | 64 +++---- .../reference/starboard/modules/byte_swap.md | 34 ++-- .../starboard/modules/condition_variable.md | 54 +++--- .../starboard/modules/configuration.md | 70 +++---- .../modules/configuration_constants.md | 60 +++--- .../starboard/modules/cpu_features.md | 34 ++-- .../starboard/modules/decode_target.md | 90 ++++----- .../reference/starboard/modules/directory.md | 44 ++--- .../docs/reference/starboard/modules/drm.md | 114 +++++------ .../docs/reference/starboard/modules/egl.md | 40 ++-- .../docs/reference/starboard/modules/event.md | 66 +++---- .../reference/starboard/modules/export.md | 16 +- .../docs/reference/starboard/modules/file.md | 108 +++++------ .../docs/reference/starboard/modules/gles.md | 32 ++-- .../docs/reference/starboard/modules/image.md | 20 +- .../docs/reference/starboard/modules/input.md | 28 +-- .../docs/reference/starboard/modules/key.md | 18 +- .../docs/reference/starboard/modules/log.md | 52 ++--- .../docs/reference/starboard/modules/media.md | 144 +++++++------- .../reference/starboard/modules/memory.md | 100 +++++----- .../reference/starboard/modules/microphone.md | 74 ++++---- .../docs/reference/starboard/modules/mutex.md | 50 ++--- .../docs/reference/starboard/modules/once.md | 28 +-- .../reference/starboard/modules/player.md | 120 ++++++------ .../reference/starboard/modules/socket.md | 152 +++++++-------- .../starboard/modules/socket_waiter.md | 66 +++---- .../starboard/modules/speech_synthesis.md | 22 +-- .../reference/starboard/modules/storage.md | 48 ++--- .../reference/starboard/modules/string.md | 50 ++--- .../reference/starboard/modules/system.md | 162 ++++++++-------- .../reference/starboard/modules/thread.md | 174 ++++++++--------- .../docs/reference/starboard/modules/time.md | 66 +++---- .../reference/starboard/modules/time_zone.md | 24 +-- .../docs/reference/starboard/modules/types.md | 12 +- .../starboard/modules/ui_navigation.md | 56 +++--- .../docs/reference/starboard/modules/user.md | 46 ++--- .../reference/starboard/modules/window.md | 104 +++++----- starboard/build/doc/migration_changes.md | 2 +- .../doc/evergreen/cobalt_evergreen_lite.md | 2 +- 166 files changed, 5182 insertions(+), 5184 deletions(-) diff --git a/cobalt/doc/memory_tuning.md b/cobalt/doc/memory_tuning.md index 662fb59feb93..297a7e4594a9 100644 --- a/cobalt/doc/memory_tuning.md +++ b/cobalt/doc/memory_tuning.md @@ -1,4 +1,4 @@ -# Memory Tuning # +# Memory Tuning Cobalt is designed to choose sensible parameters for memory-related options and parameters through a system called "AutoMem". @@ -16,7 +16,7 @@ Read on for more information. *Setting `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` on the command line is a beta feature.* -### Memory Settings Table ### +### Memory Settings Table A table similar to the one below, will be printed on startup. @@ -79,7 +79,7 @@ be set from a specific place or automatically generated from Cobalt. * This value was AutoSet to a default value, but then was reduced in response to `max_cobalt_cpu_usage` or `max_cobalt_gpu_usage being` set too low. -### Maximum Memory Table ### +### Maximum Memory Table This second table is also printed at startup and details the sum of memory and maximum memory limits as reported by cobalt. @@ -128,13 +128,13 @@ consumed by the settings, then any settings that are AutoSet AND adjustable will reduce their memory consumption. When this happens, look for the string *`AutoSet (Constrained)`* in the first table. -## Setting Maximum Memory Values ## +## Setting Maximum Memory Values The max cpu and gpu memory of the system can be set by command line: * `--max_cobalt_cpu_usage=160MB` * `--max_cobalt_gpu_usage=160MB` -### Memory Scaling ### +### Memory Scaling There are two primary ways in which the memory consumption settings will scale down. One is by specifying `--max_cobalt_cpu_usage` (or `max_cobalt_gpu_usage`) to a @@ -152,7 +152,7 @@ flexible via the command line by setting the value to "autoset". For example, `--image_cache_size_in_bytes=auto` will allow `image_cache_size_in_bytes` to be flexible by disabling the value being set by a build setting. -### Memory Warnings ### +### Memory Warnings Cobalt will periodically check to see if the memory consumed by the application is less than the `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` amount. @@ -160,7 +160,7 @@ If the cpu/gpu exceeds this maximum value then an error message will be logged once to stdout for cpu and/or gpu memory systems. -### Example 1 - Configuring for a memory restricted platform ### +### Example 1 - Configuring for a memory restricted platform Let's say that we are configuring platform called "XXX": @@ -186,7 +186,7 @@ We will configure XXX such that: * `cobalt --max_cobalt_cpu_usage=160MB` -### Example 2 - Configuring for a memory-plentiful platform ### +### Example 2 - Configuring for a memory-plentiful platform The following command line will give a lot of memory to image cache and give 500MB to `max_cobalt_cpu_usage` and `max_cobalt_gpu_usage`. @@ -196,9 +196,9 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB --image_cache_size_in_bytes=80MB ~~~ -## API Reference ## +## API Reference -#### Memory System API #### +#### Memory System API * `max_cobalt_cpu_usage` * This setting will set the maximum cpu memory that the app will consume. @@ -218,7 +218,7 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB for `max_cobalt_gpu_usage` in commandline/starboard settings then no GPU memory checking is performed. -#### Memory Setting API #### +#### Memory Setting API * `image_cache_size_in_bytes` * See documentation *Image cache capacity* in `performance_tuning.md` for what @@ -252,7 +252,7 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB for what this setting does. * Set via command line, or else Cobalt extension, or else automatically by Cobalt. -#### Units for Command Line Settings #### +#### Units for Command Line Settings Memory values passed into Cobalt via command line arguments support units such kb, mb, and gb for kilo-byte, megabyte, gigabytes. These units are case insensitive. diff --git a/cobalt/site/docs/gen/cobalt/doc/memory_tuning.md b/cobalt/site/docs/gen/cobalt/doc/memory_tuning.md index daa26f3463e0..eaf8f582e364 100644 --- a/cobalt/site/docs/gen/cobalt/doc/memory_tuning.md +++ b/cobalt/site/docs/gen/cobalt/doc/memory_tuning.md @@ -19,7 +19,7 @@ Read on for more information. *Setting `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` on the command line is a beta feature.* -### Memory Settings Table ### +### Memory Settings Table A table similar to the one below, will be printed on startup. @@ -82,7 +82,7 @@ be set from a specific place or automatically generated from Cobalt. * This value was AutoSet to a default value, but then was reduced in response to `max_cobalt_cpu_usage` or `max_cobalt_gpu_usage being` set too low. -### Maximum Memory Table ### +### Maximum Memory Table This second table is also printed at startup and details the sum of memory and maximum memory limits as reported by cobalt. @@ -131,13 +131,13 @@ consumed by the settings, then any settings that are AutoSet AND adjustable will reduce their memory consumption. When this happens, look for the string *`AutoSet (Constrained)`* in the first table. -## Setting Maximum Memory Values ## +## Setting Maximum Memory Values The max cpu and gpu memory of the system can be set by command line: * `--max_cobalt_cpu_usage=160MB` * `--max_cobalt_gpu_usage=160MB` -### Memory Scaling ### +### Memory Scaling There are two primary ways in which the memory consumption settings will scale down. One is by specifying `--max_cobalt_cpu_usage` (or `max_cobalt_gpu_usage`) to a @@ -155,7 +155,7 @@ flexible via the command line by setting the value to "autoset". For example, `--image_cache_size_in_bytes=auto` will allow `image_cache_size_in_bytes` to be flexible by disabling the value being set by a build setting. -### Memory Warnings ### +### Memory Warnings Cobalt will periodically check to see if the memory consumed by the application is less than the `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` amount. @@ -163,7 +163,7 @@ If the cpu/gpu exceeds this maximum value then an error message will be logged once to stdout for cpu and/or gpu memory systems. -### Example 1 - Configuring for a memory restricted platform ### +### Example 1 - Configuring for a memory restricted platform Let's say that we are configuring platform called "XXX": @@ -189,7 +189,7 @@ We will configure XXX such that: * `cobalt --max_cobalt_cpu_usage=160MB` -### Example 2 - Configuring for a memory-plentiful platform ### +### Example 2 - Configuring for a memory-plentiful platform The following command line will give a lot of memory to image cache and give 500MB to `max_cobalt_cpu_usage` and `max_cobalt_gpu_usage`. @@ -199,9 +199,9 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB --image_cache_size_in_bytes=80MB ~~~ -## API Reference ## +## API Reference -#### Memory System API #### +#### Memory System API * `max_cobalt_cpu_usage` * This setting will set the maximum cpu memory that the app will consume. @@ -221,7 +221,7 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB for `max_cobalt_gpu_usage` in commandline/starboard settings then no GPU memory checking is performed. -#### Memory Setting API #### +#### Memory Setting API * `image_cache_size_in_bytes` * See documentation *Image cache capacity* in `performance_tuning.md` for what @@ -255,7 +255,7 @@ cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB for what this setting does. * Set via command line, or else Cobalt extension, or else automatically by Cobalt. -#### Units for Command Line Settings #### +#### Units for Command Line Settings Memory values passed into Cobalt via command line arguments support units such kb, mb, and gb for kilo-byte, megabyte, gigabytes. These units are case insensitive. diff --git a/cobalt/site/docs/gen/starboard/tools/doc/abstract_launcher.md b/cobalt/site/docs/gen/starboard/tools/doc/abstract_launcher.md index d75ba45c3166..c15660260dce 100644 --- a/cobalt/site/docs/gen/starboard/tools/doc/abstract_launcher.md +++ b/cobalt/site/docs/gen/starboard/tools/doc/abstract_launcher.md @@ -1,7 +1,6 @@ ---- -layout: doc -title: "App Launchers" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + # App Launchers The app launcher framework is used to run an executable on a given platform, diff --git a/cobalt/site/docs/gen/starboard/tools/doc/testing.md b/cobalt/site/docs/gen/starboard/tools/doc/testing.md index 12d372b77cb8..6a74af5fe3e1 100644 --- a/cobalt/site/docs/gen/starboard/tools/doc/testing.md +++ b/cobalt/site/docs/gen/starboard/tools/doc/testing.md @@ -1,7 +1,6 @@ ---- -layout: doc -title: "Test Runner Documentation" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + # Test Runner Documentation The scripts in this folder comprise a cross-platform unit test runner. The diff --git a/cobalt/site/docs/reference/starboard/configuration-public.md b/cobalt/site/docs/reference/starboard/configuration-public.md index 44659a2106d0..9cf1635393e5 100644 --- a/cobalt/site/docs/reference/starboard/configuration-public.md +++ b/cobalt/site/docs/reference/starboard/configuration-public.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Configuration Reference Guide" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +Starboard Configuration Reference Guide ## Architecture Configuration diff --git a/cobalt/site/docs/reference/starboard/gn-configuration.md b/cobalt/site/docs/reference/starboard/gn-configuration.md index 18db1eea7eea..b139d8036a23 100644 --- a/cobalt/site/docs/reference/starboard/gn-configuration.md +++ b/cobalt/site/docs/reference/starboard/gn-configuration.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard: configuration.gni Reference Guide" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard: configuration.gni Reference Guide | Variables | | :--- | diff --git a/cobalt/site/docs/reference/starboard/modules/13/accessibility.md b/cobalt/site/docs/reference/starboard/modules/13/accessibility.md index a6c8460bcf2b..8f2a652445a9 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/13/accessibility.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: accessibility.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `accessibility.h` Provides access to the system options and settings related to accessibility. -## Enums ## +## Enums -### SbAccessibilityCaptionCharacterEdgeStyle ### +### SbAccessibilityCaptionCharacterEdgeStyle Enum for possible closed captioning character edge styles. -#### Values #### +#### Values * `kSbAccessibilityCaptionCharacterEdgeStyleNone` * `kSbAccessibilityCaptionCharacterEdgeStyleRaised` @@ -19,11 +19,11 @@ Enum for possible closed captioning character edge styles. * `kSbAccessibilityCaptionCharacterEdgeStyleUniform` * `kSbAccessibilityCaptionCharacterEdgeStyleDropShadow` -### SbAccessibilityCaptionColor ### +### SbAccessibilityCaptionColor Enum for possible closed captioning colors. -#### Values #### +#### Values * `kSbAccessibilityCaptionColorBlue` * `kSbAccessibilityCaptionColorBlack` @@ -34,11 +34,11 @@ Enum for possible closed captioning colors. * `kSbAccessibilityCaptionColorWhite` * `kSbAccessibilityCaptionColorYellow` -### SbAccessibilityCaptionFontFamily ### +### SbAccessibilityCaptionFontFamily Enum for possible closed captioning font families -#### Values #### +#### Values * `kSbAccessibilityCaptionFontFamilyCasual` * `kSbAccessibilityCaptionFontFamilyCursive` @@ -48,11 +48,11 @@ Enum for possible closed captioning font families * `kSbAccessibilityCaptionFontFamilyProportionalSerif` * `kSbAccessibilityCaptionFontFamilySmallCapitals` -### SbAccessibilityCaptionFontSizePercentage ### +### SbAccessibilityCaptionFontSizePercentage Enum for possible closed captioning font size percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionFontSizePercentage25` * `kSbAccessibilityCaptionFontSizePercentage50` @@ -67,11 +67,11 @@ Enum for possible closed captioning font size percentages. * `kSbAccessibilityCaptionFontSizePercentage275` * `kSbAccessibilityCaptionFontSizePercentage300` -### SbAccessibilityCaptionOpacityPercentage ### +### SbAccessibilityCaptionOpacityPercentage Enum for possible closed captioning opacity percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionOpacityPercentage0` * `kSbAccessibilityCaptionOpacityPercentage25` @@ -79,11 +79,11 @@ Enum for possible closed captioning opacity percentages. * `kSbAccessibilityCaptionOpacityPercentage75` * `kSbAccessibilityCaptionOpacityPercentage100` -### SbAccessibilityCaptionState ### +### SbAccessibilityCaptionState Enum for possible states of closed captioning properties. -#### Values #### +#### Values * `kSbAccessibilityCaptionStateUnsupported` @@ -115,14 +115,14 @@ Enum for possible states of closed captioning properties. SbAccessibilityCaptionSettings.supportsOverride contains false, then no fields of SbAccessibilityCaptionSettings will ever contain this value. -## Structs ## +## Structs -### SbAccessibilityCaptionSettings ### +### SbAccessibilityCaptionSettings A group of settings related to system-level closed captioning settings, for platforms that expose closed captioning settings. -#### Members #### +#### Members * `SbAccessibilityCaptionColor background_color` * `SbAccessibilityCaptionState background_color_state` @@ -166,9 +166,9 @@ platforms that expose closed captioning settings. false, the values of `SbAccessibilityCaptionState` should be interpreted differently. -### SbAccessibilityDisplaySettings ### +### SbAccessibilityDisplaySettings -#### Members #### +#### Members * `bool has_high_contrast_text_setting` @@ -177,12 +177,12 @@ platforms that expose closed captioning settings. Whether the high contrast text setting is enabled or not. -### SbAccessibilityTextToSpeechSettings ### +### SbAccessibilityTextToSpeechSettings A group of settings related to text-to-speech functionality, for platforms that expose system settings for text-to-speech. -#### Members #### +#### Members * `bool has_text_to_speech_setting` @@ -192,9 +192,9 @@ expose system settings for text-to-speech. Whether the text-to-speech setting is enabled or not. This setting is only valid if `has_text_to_speech_setting` is set to true. -## Functions ## +## Functions -### SbAccessibilityGetCaptionSettings ### +### SbAccessibilityGetCaptionSettings Get the platform's settings for system-level closed captions. This function returns false if `caption_settings` is NULL or if it is not zero-initialized. @@ -202,13 +202,13 @@ returns false if `caption_settings` is NULL or if it is not zero-initialized. `caption_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetCaptionSettings(SbAccessibilityCaptionSettings *caption_settings) ``` -### SbAccessibilityGetDisplaySettings ### +### SbAccessibilityGetDisplaySettings Get the platform settings related to high contrast text. This function returns false if `out_settings` is NULL or if it is not zero-initialized. @@ -216,13 +216,13 @@ false if `out_settings` is NULL or if it is not zero-initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityDisplaySettings* struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetDisplaySettings(SbAccessibilityDisplaySettings *out_settings) ``` -### SbAccessibilityGetTextToSpeechSettings ### +### SbAccessibilityGetTextToSpeechSettings Get the platform settings related to the text-to-speech accessibility feature. This function returns false if `out_settings` is NULL or if it is not zero- @@ -231,13 +231,13 @@ initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetTextToSpeechSettings(SbAccessibilityTextToSpeechSettings *out_settings) ``` -### SbAccessibilitySetCaptionsEnabled ### +### SbAccessibilitySetCaptionsEnabled Modifies whether closed captions are enabled at a system level. This function returns false if this feature is not supported by the platform, or if changing @@ -246,7 +246,7 @@ the setting is unsuccessful. This function will modify the setting system-wide. `enabled`: A boolean indicating whether captions should be turned on (true) or off (false). -#### Declaration #### +#### Declaration ``` 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 5f799906cdaf..9653e53cecd3 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/13/atomic.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: atomic.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `atomic.h` Defines a set of atomic integer operations that can be used as lightweight synchronization or as building blocks for heavier synchronization primitives. @@ -9,32 +9,32 @@ Their use is very subtle and requires detailed understanding of the behavior of supported architectures, so their direct use is not recommended except when rigorously deemed absolutely necessary for performance reasons. -## Typedefs ## +## Typedefs -### SbAtomic64 ### +### SbAtomic64 64-bit atomic operations (only available on 64-bit processors). -#### Definition #### +#### Definition ``` typedef int64_t SbAtomic64 ``` -### SbAtomicPtr ### +### SbAtomicPtr Pointer-sized atomic operations. Forwards to either 32-bit or 64-bit functions as appropriate. -#### Definition #### +#### Definition ``` typedef SbAtomic32 SbAtomicPtr ``` -## Functions ## +## Functions -### SbAtomicAcquire_CompareAndSwap ### +### SbAtomicAcquire_CompareAndSwap These following lower-level operations are typically useful only to people implementing higher-level synchronization operations like spinlocks, mutexes, @@ -45,23 +45,23 @@ operations ensure that no previous memory access can be reordered after the operation. "Barrier" operations have both "Acquire" and "Release" semantics. A SbAtomicMemoryBarrier() has "Barrier" semantics, but does no memory access. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicAcquire_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicBarrier_Increment ### +### SbAtomicBarrier_Increment Same as SbAtomicNoBarrier_Increment, but with a memory barrier. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicNoBarrier_CompareAndSwap ### +### SbAtomicNoBarrier_CompareAndSwap Atomically execute: result = *ptr; if (*ptr == old_value) *ptr = new_value; return result; @@ -71,39 +71,39 @@ return the old value of "*ptr" This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Exchange ### +### SbAtomicNoBarrier_Exchange Atomically store new_value into *ptr, returning the previous value held in *ptr. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Exchange(volatile SbAtomic32 *ptr, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Increment ### +### SbAtomicNoBarrier_Increment Atomically increment *ptr by "increment". Returns the new value of *ptr with the increment applied. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicRelease_CompareAndSwap8 ### +### SbAtomicRelease_CompareAndSwap8 Overloaded functions for Atomic8. -#### Declaration #### +#### Declaration ``` 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 b0e652f50e92..9277c70837b0 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/13/audio_sink.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: audio_sink.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `audio_sink.h` Provides an interface to output raw audio data. -## Macros ## +## Macros -### kSbAudioSinkInvalid ### +### kSbAudioSinkInvalid Well-defined value for an invalid audio sink. -## Typedefs ## +## Typedefs -### SbAudioSink ### +### SbAudioSink An opaque handle to an implementation-private structure representing an audio sink. -#### Definition #### +#### Definition ``` typedef struct SbAudioSinkPrivate* SbAudioSink ``` -### SbAudioSinkConsumeFramesFunc ### +### SbAudioSinkConsumeFramesFunc Callback used to report frames consumed. The consumed frames will be removed from the source frame buffer to free space for new audio frames. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkConsumeFramesFunc) (int frames_consumed, void *context) ``` -### SbAudioSinkFrameBuffers ### +### SbAudioSinkFrameBuffers An array of frame buffers. For interleaved audio streams, there will be only one element in the array. For planar audio streams, the number of elements in the array equal to the number of channels. -#### Definition #### +#### Definition ``` typedef void** SbAudioSinkFrameBuffers ``` -### SbAudioSinkUpdateSourceStatusFunc ### +### SbAudioSinkUpdateSourceStatusFunc Callback being called periodically to retrieve the status of the audio source. The first two output parameters indicating the filling level of the audio frame @@ -64,15 +64,15 @@ usually this is caused by a seek. All parameters except `context` cannot be NULL. Note that this function only reports the status of the source, it doesn't remove audio data from the source frame buffer. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkUpdateSourceStatusFunc) (int *frames_in_buffer, int *offset_in_frames, bool *is_playing, bool *is_eos_reached, void *context) ``` -## Functions ## +## Functions -### SbAudioSinkCreate ### +### SbAudioSinkCreate Creates an audio sink for the specified `channels` and `sampling_frequency_hz`, acquires all resources needed to operate the audio sink, and returns an opaque @@ -113,13 +113,13 @@ to sample data. value that is passed back to all callbacks and is generally used to point at a class or struct that contains state associated with the audio sink. -#### Declaration #### +#### Declaration ``` SbAudioSink SbAudioSinkCreate(int channels, int sampling_frequency_hz, SbMediaAudioSampleType audio_sample_type, SbMediaAudioFrameStorageType audio_frame_storage_type, SbAudioSinkFrameBuffers frame_buffers, int frames_per_channel, SbAudioSinkUpdateSourceStatusFunc update_source_status_func, SbAudioSinkConsumeFramesFunc consume_frames_func, void *context) ``` -### SbAudioSinkDestroy ### +### SbAudioSinkDestroy Destroys `audio_sink`, freeing all associated resources. Before returning, the function waits until all callbacks that are in progress have finished. After the @@ -132,24 +132,24 @@ any of the callbacks passed into SbAudioSinkCreate. `audio_sink`: The audio sink to destroy. -#### Declaration #### +#### Declaration ``` void SbAudioSinkDestroy(SbAudioSink audio_sink) ``` -### SbAudioSinkGetMaxChannels ### +### SbAudioSinkGetMaxChannels Returns the maximum number of channels supported on the platform. For example, the number would be `2` if the platform only supports stereo. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMaxChannels() ``` -### SbAudioSinkGetMinBufferSizeInFrames ### +### SbAudioSinkGetMinBufferSizeInFrames Returns the minimum frames required by audio sink to play without underflows. Returns -1, if `channels`, `sample_type` or `sampling_frequency_hz` is not @@ -162,52 +162,52 @@ stereo audio. `audio_sample_type`: The type of each sample of the audio data – audio data being streamed. For example, 22,000 Hz means 22,000 sample elements represents one second of audio data. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMinBufferSizeInFrames(int channels, SbMediaAudioSampleType sample_type, int sampling_frequency_hz) ``` -### SbAudioSinkGetNearestSupportedSampleFrequency ### +### SbAudioSinkGetNearestSupportedSampleFrequency Returns the supported sample rate closest to `sampling_frequency_hz`. On platforms that don't support all sample rates, it is the caller's responsibility to resample the audio frames into the supported sample rate returned by this function. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetNearestSupportedSampleFrequency(int sampling_frequency_hz) ``` -### SbAudioSinkIsAudioFrameStorageTypeSupported ### +### SbAudioSinkIsAudioFrameStorageTypeSupported Indicates whether `audio_frame_storage_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioFrameStorageTypeSupported(SbMediaAudioFrameStorageType audio_frame_storage_type) ``` -### SbAudioSinkIsAudioSampleTypeSupported ### +### SbAudioSinkIsAudioSampleTypeSupported Indicates whether `audio_sample_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioSampleTypeSupported(SbMediaAudioSampleType audio_sample_type) ``` -### SbAudioSinkIsValid ### +### SbAudioSinkIsValid Indicates whether the given audio sink handle is valid. `audio_sink`: The audio sink handle to check. -#### Declaration #### +#### Declaration ``` 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 580bc5dbb0e5..4b2cab30de3d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/13/byte_swap.md @@ -1,74 +1,74 @@ ---- -layout: doc -title: "Starboard Module Reference: byte_swap.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `byte_swap.h` Specifies functions for swapping byte order. These functions are used to deal with endianness when performing I/O. -## Functions ## +## Functions -### SbByteSwapS16 ### +### SbByteSwapS16 Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int16_t SbByteSwapS16(int16_t value) ``` -### SbByteSwapS32 ### +### SbByteSwapS32 Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int32_t SbByteSwapS32(int32_t value) ``` -### SbByteSwapS64 ### +### SbByteSwapS64 Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int64_t SbByteSwapS64(int64_t value) ``` -### SbByteSwapU16 ### +### SbByteSwapU16 Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint16_t SbByteSwapU16(uint16_t value) ``` -### SbByteSwapU32 ### +### SbByteSwapU32 Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint32_t SbByteSwapU32(uint32_t value) ``` -### SbByteSwapU64 ### +### SbByteSwapU64 Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint64_t SbByteSwapU64(uint64_t value) diff --git a/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md index 836c4b813d9c..a665a24f45bf 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/13/condition_variable.md @@ -1,23 +1,23 @@ ---- -layout: doc -title: "Starboard Module Reference: condition_variable.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `condition_variable.h` Defines an interface for condition variables. -## Macros ## +## Macros -### SB_CONDITION_VARIABLE_MAX_SIZE ### +### SB_CONDITION_VARIABLE_MAX_SIZE Max size of the SbConditionVariable type. -## Enums ## +## Enums -### SbConditionVariableResult ### +### SbConditionVariableResult Enumeration of possible results from waiting on a condvar. -#### Values #### +#### Values * `kSbConditionVariableSignaled` @@ -30,22 +30,22 @@ Enumeration of possible results from waiting on a condvar. The wait failed, either because a parameter wasn't valid, or the condition variable has already been destroyed, or something similar. -## Typedefs ## +## Typedefs -### SbConditionVariable ### +### SbConditionVariable An opaque handle to a condition variable type with reserved memory buffer of size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbConditionVariable SbConditionVariable ``` -## Functions ## +## Functions -### SbConditionVariableBroadcast ### +### SbConditionVariableBroadcast Broadcasts to all current waiters of `condition` to stop waiting. This function wakes all of the threads waiting on `condition` while SbConditionVariableSignal @@ -53,26 +53,26 @@ wakes a single thread. `condition`: The condition that should no longer be waited for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableBroadcast(SbConditionVariable *condition) ``` -### SbConditionVariableCreate ### +### SbConditionVariableCreate Creates a new condition variable to work with `opt_mutex`, which may be null, placing the newly created condition variable in `out_condition`. The return value indicates whether the condition variable could be created. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) ``` -### SbConditionVariableDestroy ### +### SbConditionVariableDestroy Destroys the specified SbConditionVariable . The return value indicates whether the destruction was successful. The behavior is undefined if other threads are @@ -81,23 +81,23 @@ currently waiting on this condition variable. `condition`: The SbConditionVariable to be destroyed. This invalidates the condition variable. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableDestroy(SbConditionVariable *condition) ``` -### SbConditionVariableIsSignaled ### +### SbConditionVariableIsSignaled Returns whether the given result is a success. -#### Declaration #### +#### Declaration ``` static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) ``` -### SbConditionVariableSignal ### +### SbConditionVariableSignal Signals the next waiter of `condition` to stop waiting. This function wakes a single thread waiting on `condition` while SbConditionVariableBroadcast wakes @@ -105,24 +105,24 @@ all threads waiting on it. `condition`: The condition that the waiter should stop waiting for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableSignal(SbConditionVariable *condition) ``` -### SbConditionVariableWait ### +### SbConditionVariableWait Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, and returning the result. Behavior is undefined if `mutex` is not held. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) ``` -### SbConditionVariableWaitTimed ### +### SbConditionVariableWaitTimed Waits for `condition`, releasing the held lock `mutex`, blocking up to `timeout_duration`, and returning the acquisition result. Behavior is undefined @@ -133,7 +133,7 @@ if `mutex` is not held. function returns as quickly as possible with a kSbConditionVariableTimedOut result. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime 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 630f1cf32228..d0ba3c7196f8 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/13/configuration.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration.h` Provides a description of the current platform in lurid detail so that common code never needs to actually know what the current operating system and @@ -13,117 +13,117 @@ Configuration feature instead. This implies the continued existence of very narrowly-defined configuration features, but it retains porting control in Starboard. -## Macros ## +## Macros -### SB_ALIGNAS(byte_alignment) ### +### SB_ALIGNAS(byte_alignment) Specifies the alignment for a class, struct, union, enum, class/struct field, or stack variable. -### SB_ALIGNOF(type) ### +### SB_ALIGNOF(type) Returns the alignment required for any instance of the type indicated by `type`. -### SB_ARRAY_SIZE(array) ### +### SB_ARRAY_SIZE(array) A constant expression that evaluates to the size_t size of a statically-sized array. -### SB_ARRAY_SIZE_INT(array) ### +### SB_ARRAY_SIZE_INT(array) A constant expression that evaluates to the int size of a statically-sized array. -### SB_CAN(SB_FEATURE) ### +### SB_CAN(SB_FEATURE) Determines a compile-time capability of the system. -### SB_COMPILE_ASSERT(expr, msg) ### +### SB_COMPILE_ASSERT(expr, msg) Will cause a compiler error with `msg` if `expr` is false. `msg` must be a valid identifier, and must be a unique type in the scope of the declaration. -### SB_DEPRECATED(FUNC) ### +### SB_DEPRECATED(FUNC) SB_DEPRECATED(int Foo(int bar)); Annotates the function as deprecated, which will trigger a compiler warning when referenced. -### SB_DEPRECATED_EXTERNAL(FUNC) ### +### SB_DEPRECATED_EXTERNAL(FUNC) SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION ### +### 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 ### +### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for logging. -### SB_HAS(SB_FEATURE) ### +### SB_HAS(SB_FEATURE) Determines at compile-time whether this platform has a standard feature or header available. -### SB_HAS_64_BIT_ATOMICS ### +### SB_HAS_64_BIT_ATOMICS Whether the current platform has 64-bit atomic operations. -### SB_HAS_GLES2 ### +### SB_HAS_GLES2 Specifies whether this platform has a performant OpenGL ES 2 implementation, which allows client applications to use GL rendering paths. Derived from the gyp variable `gl_type` gl_type which indicates what kind of GL implementation is available. -### SB_HAS_QUIRK(SB_FEATURE) ### +### SB_HAS_QUIRK(SB_FEATURE) Determines at compile-time whether this platform has a quirk. -### SB_INT64_C(x) ### +### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. -### SB_IS(SB_FEATURE) ### +### SB_IS(SB_FEATURE) Determines at compile-time an inherent aspect of this platform. -### SB_LIKELY(x) ### +### SB_LIKELY(x) Macro for hinting that an expression is likely to be true. -### SB_MAXIMUM_API_VERSION ### +### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, inclusive. -### SB_MINIMUM_API_VERSION ### +### SB_MINIMUM_API_VERSION The minimum API version allowed by this version of the Starboard headers, inclusive. -### SB_NORETURN ### +### SB_NORETURN Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE ### +### SB_OVERRIDE Declares a function as overriding a virtual function on compilers that support it. -### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA ### +### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. Setting this up properly means avoiding slow color swizzles when passing pixel data from one library to another. Note that these definitions are in byte-order and so are endianness-independent. -### SB_PRINTF_FORMAT(format_param, dots_param) ### +### SB_PRINTF_FORMAT(format_param, dots_param) Tells the compiler a function is using a printf-style format string. `format_param` is the one-based index of the format string parameter; @@ -132,7 +132,7 @@ functions (which take a va_list), pass 0 for dots_param. (This is undocumented but matches what the system C headers do.) (Partially taken from base/compiler_specific.h) -### SB_RESTRICT ### +### SB_RESTRICT 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 @@ -140,29 +140,29 @@ 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. -### SB_SIZE_OF(DATATYPE) ### +### SB_SIZE_OF(DATATYPE) Determines at compile-time the size of a data type, or 0 if the data type that was specified was invalid. -### SB_STRINGIFY(x) ### +### SB_STRINGIFY(x) Standard CPP trick to stringify an evaluated macro definition. -### SB_UINT64_C(x) ### +### SB_UINT64_C(x) Declare numeric literals of unsigned 64-bit type. -### SB_UNLIKELY(x) ### +### SB_UNLIKELY(x) Macro for hinting that an expression is likely to be false. -### SB_UNREFERENCED_PARAMETER(x) ### +### SB_UNREFERENCED_PARAMETER(x) Trivially references a parameter that is otherwise unreferenced, preventing a compiler warning on some platforms. -### SB_WARN_UNUSED_RESULT ### +### SB_WARN_UNUSED_RESULT Causes the annotated (at the end) function to generate a warning if the result is not accessed. diff --git a/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md index b380f6216461..012754b623bd 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/13/configuration_constants.md @@ -1,113 +1,113 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration_constants.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration_constants.h` Declares all configuration variables we will need to use at runtime. These variables describe the current platform in detail to allow cobalt to make runtime decisions based on per platform configurations. -## Variables ## +## Variables -### kSbDefaultMmapThreshold ### +### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if available), rather than allocated within the core heap. -### kSbFileAltSepChar ### +### kSbFileAltSepChar The current platform's alternate file path component separator character. This is like SB_FILE_SEP_CHAR, except if your platform supports an alternate character, then you can place that here. For example, on windows machines, the primary separator character is probably '\', but the alternate is '/'. -### kSbFileAltSepString ### +### kSbFileAltSepString The string form of SB_FILE_ALT_SEP_CHAR. -### kSbFileMaxName ### +### kSbFileMaxName The current platform's maximum length of the name of a single directory entry, not including the absolute path. -### kSbFileMaxOpen ### +### kSbFileMaxOpen The current platform's maximum number of files that can be opened at the same time by one process. -### kSbFileMaxPath ### +### kSbFileMaxPath The current platform's maximum length of an absolute path. -### kSbFileSepChar ### +### kSbFileSepChar The current platform's file path component separator character. This is the character that appears after a directory in a file path. For example, the absolute canonical path of the file "/path/to/a/file.txt" uses '/' as a path component separator character. -### kSbFileSepString ### +### kSbFileSepString The string form of SB_FILE_SEP_CHAR. -### kSbHasAc3Audio ### +### kSbHasAc3Audio Allow ac3 and ec3 support -### kSbHasMediaWebmVp9Support ### +### kSbHasMediaWebmVp9Support Specifies whether this platform has webm/vp9 support. This should be set to non- zero on platforms with webm/vp9 support. -### kSbHasThreadPrioritySupport ### +### kSbHasThreadPrioritySupport Whether the current platform supports thread priorities. -### kSbMallocAlignment ### +### kSbMallocAlignment Determines the alignment that allocations should have on this platform. -### kSbMaxThreadLocalKeys ### +### kSbMaxThreadLocalKeys The maximum number of thread local storage keys supported by this platform. This comes from _POSIX_THREAD_KEYS_MAX. The value of PTHREAD_KEYS_MAX is higher, but unit tests show that the implementation doesn't support nearly as many keys. -### kSbMaxThreadNameLength ### +### kSbMaxThreadNameLength The maximum length of the name for a thread, including the NULL-terminator. -### kSbMaxThreads ### +### kSbMaxThreads Defines the maximum number of simultaneous threads for this platform. Some platforms require sharing thread handles with other kinds of system handles, like mutexes, so we want to keep this manageable. -### kSbMediaMaxAudioBitrateInBitsPerSecond ### +### kSbMediaMaxAudioBitrateInBitsPerSecond The maximum audio bitrate the platform can decode. The following value equals to 5M bytes per seconds which is more than enough for compressed audio. -### kSbMediaMaxVideoBitrateInBitsPerSecond ### +### kSbMediaMaxVideoBitrateInBitsPerSecond The maximum video bitrate the platform can decode. The following value equals to 8M bytes per seconds which is more than enough for compressed video. -### kSbMediaVideoFrameAlignment ### +### kSbMediaVideoFrameAlignment Specifies how video frame buffers must be aligned on this platform. -### kSbMemoryLogPath ### +### kSbMemoryLogPath Defines the path where memory debugging logs should be written to. -### kSbMemoryPageSize ### +### kSbMemoryPageSize The memory page size, which controls the size of chunks on memory that allocators deal with, and the alignment of those chunks. This doesn't have to be the hardware-defined physical page size, but it should be a multiple of it. -### kSbNetworkReceiveBufferSize ### +### kSbNetworkReceiveBufferSize Specifies the network receive buffer size in bytes, set via SbSocketSetReceiveBufferSize(). @@ -122,7 +122,7 @@ affect throughput in the presence of latency. If your platform does not have a good TCP auto-tuning mechanism, a setting of (128 * 1024) here is recommended. -### kSbPathSepChar ### +### kSbPathSepChar The current platform's search path component separator character. When specifying an ordered list of absolute paths of directories to search for a @@ -130,16 +130,16 @@ given reason, this is the character that appears between entries. For example, the search path of "/etc/search/first:/etc/search/second" uses ':' as a search path component separator character. -### kSbPathSepString ### +### kSbPathSepString The string form of SB_PATH_SEP_CHAR. -### kSbPreferredRgbaByteOrder ### +### kSbPreferredRgbaByteOrder Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. -### kSbUserMaxSignedIn ### +### kSbUserMaxSignedIn The maximum number of users that can be signed in at the same time. diff --git a/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md index ee12e715e78f..f5287bf7f5e2 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/13/cpu_features.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: cpu_features.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml -## Structs ## +# Starboard Module Reference: `cpu_features.h` -### SbCPUFeatures ### +## Structs -#### Members #### +### SbCPUFeatures + +#### Members * `SbCPUFeaturesArchitecture architecture` @@ -54,9 +54,9 @@ title: "Starboard Module Reference: cpu_features.h" defined as a macro. * `SbCPUFeaturesX86 x86` -### SbCPUFeaturesARM ### +### SbCPUFeaturesARM -#### Members #### +#### Members * `int16_t implementer` @@ -98,7 +98,7 @@ title: "Starboard Module Reference: cpu_features.h" SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags ###### + ###### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -114,17 +114,17 @@ title: "Starboard Module Reference: cpu_features.h" 64-bit PMULL and PMULL2 instructions. -### SbCPUFeaturesMIPS ### +### SbCPUFeaturesMIPS -#### Members #### +#### Members * `bool has_msa` MIPS SIMD Architecture (MSA). -### SbCPUFeaturesX86 ### +### SbCPUFeaturesX86 -#### Members #### +#### Members * `const char * vendor` @@ -244,9 +244,9 @@ title: "Starboard Module Reference: cpu_features.h" SAHF in long mode. -## Functions ## +## Functions -### SbCPUFeaturesGet ### +### SbCPUFeaturesGet Retrieve the underlying CPU features and place it in `features`, which must not be NULL. @@ -254,7 +254,7 @@ be NULL. If this function returns false, it means the CPU architecture is unknown and all fields in `features` are invalid. -#### Declaration #### +#### Declaration ``` 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 23ed59d6106b..2794d9ddfbe2 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/13/decode_target.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: decode_target.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `decode_target.h` A target for decoding image and video data into. This corresponds roughly to an EGLImage, but that extension may not be fully supported on all GL platforms. @@ -12,7 +12,7 @@ data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. -## SbDecodeTargetFormat ## +## SbDecodeTargetFormat SbDecodeTargets support several different formats that can be used to decode into and render from. Some formats may be easier to decode into, and others may @@ -21,7 +21,7 @@ the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. -## SbDecodeTargetGraphicsContextProvider ## +## SbDecodeTargetGraphicsContextProvider Some components may need to acquire SbDecodeTargets compatible with a certain rendering context, which may need to be created on a particular thread. The @@ -36,7 +36,7 @@ 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 ## +## 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. @@ -79,15 +79,15 @@ GLuint texture = info.planes[kSbDecodeTargetPlaneRGBA].texture; ``` -## Macros ## +## Macros -### kSbDecodeTargetInvalid ### +### kSbDecodeTargetInvalid Well-defined value for an invalid decode target handle. -## Enums ## +## Enums -### SbDecodeTargetFormat ### +### SbDecodeTargetFormat The list of all possible decoder target formats. An SbDecodeTarget consists of one or more planes of data, each plane corresponding with a surface. For some @@ -96,7 +96,7 @@ formats, different planes will be different sizes for the same dimensions. NOTE: For enumeration entries with an alpha component, the alpha will always be premultiplied unless otherwise explicitly specified. -#### Values #### +#### Values * `kSbDecodeTargetFormat1PlaneRGBA` @@ -132,11 +132,11 @@ premultiplied unless otherwise explicitly specified. An invalid decode target format. -### SbDecodeTargetPlane ### +### SbDecodeTargetPlane All the planes supported by SbDecodeTarget. -#### Values #### +#### Values * `kSbDecodeTargetPlaneRGBA` @@ -157,45 +157,45 @@ All the planes supported by SbDecodeTarget. The V plane for 3-plane YUV formats. -## Typedefs ## +## Typedefs -### SbDecodeTarget ### +### SbDecodeTarget A handle to a target for image data decoding. -#### Definition #### +#### Definition ``` typedef SbDecodeTargetPrivate* SbDecodeTarget ``` -### SbDecodeTargetGlesContextRunner ### +### SbDecodeTargetGlesContextRunner Signature for a function provided by the application to the Starboard implementation that will let the Starboard implementation run arbitrary code on the application's renderer thread with the application's EGLContext held current. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunner) (struct SbDecodeTargetGraphicsContextProvider *graphics_context_provider, SbDecodeTargetGlesContextRunnerTarget target_function, void *target_function_context) ``` -### SbDecodeTargetGlesContextRunnerTarget ### +### SbDecodeTargetGlesContextRunnerTarget Signature for a Starboard implementation function that is to be run by a SbDecodeTargetGlesContextRunner callback. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunnerTarget) (void *gles_context_runner_target_context) ``` -## Structs ## +## Structs -### SbDecodeTargetGraphicsContextProvider ### +### SbDecodeTargetGraphicsContextProvider In general, the SbDecodeTargetGraphicsContextProvider structure provides information about the graphics context that will be used to render @@ -205,7 +205,7 @@ References to SbDecodeTargetGraphicsContextProvider objects should be provided to all Starboard functions that might create SbDecodeTargets (e.g. SbImageDecode()). -#### Members #### +#### Members * `void * egl_display` @@ -228,12 +228,12 @@ SbImageDecode()). Context data that is to be passed in to `gles_context_runner` when it is invoked. -### SbDecodeTargetInfo ### +### SbDecodeTargetInfo Contains all information about a decode target, including all of its planes. This can be queried via calls to SbDecodeTargetGetInfo(). -#### Members #### +#### Members * `SbDecodeTargetFormat format` @@ -262,11 +262,11 @@ This can be queried via calls to SbDecodeTargetGetInfo(). kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode target. -### SbDecodeTargetInfoContentRegion ### +### SbDecodeTargetInfoContentRegion Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. -#### Members #### +#### Members * `float left` @@ -278,11 +278,11 @@ Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. * `float right` * `float bottom` -### SbDecodeTargetInfoPlane ### +### SbDecodeTargetInfoPlane Defines an image plane within a SbDecodeTargetInfo object. -#### Members #### +#### Members * `uint32_t texture` @@ -312,53 +312,53 @@ Defines an image plane within a SbDecodeTargetInfo object. these parameters are number of pixels. The range for left/right is [0, width], and for top/bottom it is [0, height]. -## Functions ## +## Functions -### PrivateDecodeTargetReleaser ### +### PrivateDecodeTargetReleaser This function is just an implementation detail of SbDecodeTargetReleaseInGlesContext() and should not be called directly. -#### Declaration #### +#### Declaration ``` static void PrivateDecodeTargetReleaser(void *context) ``` -### SbDecodeTargetGetInfo ### +### SbDecodeTargetGetInfo Writes all information about `decode_target` into `out_info`. The `decode_target` must not be kSbDecodeTargetInvalid. The `out_info` pointer must not be NULL. Returns false if the provided `out_info` structure is not zero initialized. -#### Declaration #### +#### Declaration ``` bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target, SbDecodeTargetInfo *out_info) ``` -### SbDecodeTargetIsFormatValid ### +### SbDecodeTargetIsFormatValid Returns whether a given format is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsFormatValid(SbDecodeTargetFormat format) ``` -### SbDecodeTargetIsValid ### +### SbDecodeTargetIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsValid(SbDecodeTarget handle) ``` -### SbDecodeTargetRelease ### +### SbDecodeTargetRelease Returns ownership of `decode_target` to the Starboard implementation. This function will likely result in the destruction of the SbDecodeTarget and all its @@ -366,31 +366,31 @@ 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 -#### Declaration #### +#### Declaration ``` void SbDecodeTargetRelease(SbDecodeTarget decode_target) ``` -### SbDecodeTargetReleaseInGlesContext ### +### SbDecodeTargetReleaseInGlesContext Helper function that is possibly useful to Starboard implementations that will release a decode target on the thread with the GLES context current. -#### Declaration #### +#### Declaration ``` static void SbDecodeTargetReleaseInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTarget decode_target) ``` -### SbDecodeTargetRunInGlesContext ### +### SbDecodeTargetRunInGlesContext Inline convenience function to run an arbitrary SbDecodeTargetGlesContextRunnerTarget function through a SbDecodeTargetGraphicsContextProvider . This is intended to be called by Starboard implementations, if it is necessary. -#### Declaration #### +#### Declaration ``` 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 d46c9a194b02..1c0f90482119 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/13/directory.md @@ -1,56 +1,56 @@ ---- -layout: doc -title: "Starboard Module Reference: directory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `directory.h` Provides directory listing functions. -## Macros ## +## Macros -### kSbDirectoryInvalid ### +### kSbDirectoryInvalid Well-defined value for an invalid directory stream handle. -## Typedefs ## +## Typedefs -### SbDirectory ### +### SbDirectory A handle to an open directory stream. -#### Definition #### +#### Definition ``` typedef struct SbDirectoryPrivate* SbDirectory ``` -## Functions ## +## Functions -### SbDirectoryCanOpen ### +### SbDirectoryCanOpen Indicates whether SbDirectoryOpen is allowed for the given `path`. `path`: The path to be checked. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCanOpen(const char *path) ``` -### SbDirectoryClose ### +### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the directory was closed successfully. `directory`: The directory stream handle to close. -#### Declaration #### +#### Declaration ``` bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate ### +### SbDirectoryCreate Creates the directory `path`, assuming the parent directory already exists. This function returns `true` if the directory now exists (even if it existed before) @@ -58,13 +58,13 @@ and returns `false` if the directory does not exist. `path`: The path to be created. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCreate(const char *path) ``` -### SbDirectoryGetNext ### +### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and moves the stream forward by one entry. @@ -83,23 +83,23 @@ entry. The space allocated for this string should be equal to `out_entry_size`. `out_entry_size`: The size of the space allocated for `out_entry`. This should be at least equal to kSbFileMaxName. -#### Declaration #### +#### Declaration ``` bool SbDirectoryGetNext(SbDirectory directory, char *out_entry, size_t out_entry_size) ``` -### SbDirectoryIsValid ### +### SbDirectoryIsValid Returns whether the given directory stream handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDirectoryIsValid(SbDirectory directory) ``` -### SbDirectoryOpen ### +### SbDirectoryOpen Opens the given existing directory for listing. This function returns kSbDirectoryInvalidHandle if it is not successful. @@ -110,7 +110,7 @@ SbFileError code on failure. `out_error`: An output parameter that, in case of an error, is set to the reason that the directory could not be opened. -#### Declaration #### +#### Declaration ``` 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 fbb92f9ec841..f42e43bf3db7 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/13/drm.md @@ -1,37 +1,37 @@ ---- -layout: doc -title: "Starboard Module Reference: drm.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `drm.h` Provides definitions that allow for DRM support, which are common between Player and Decoder interfaces. -## Macros ## +## Macros -### kSbDrmSystemInvalid ### +### kSbDrmSystemInvalid An invalid SbDrmSystem. -### kSbDrmTicketInvalid ### +### kSbDrmTicketInvalid A ticket for callback invocations initiated by the DRM system. -## Enums ## +## Enums -### SbDrmEncryptionScheme ### +### SbDrmEncryptionScheme Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. -#### Values #### +#### Values * `kSbDrmEncryptionSchemeAesCtr` * `kSbDrmEncryptionSchemeAesCbc` -### SbDrmKeyStatus ### +### SbDrmKeyStatus Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) -#### Values #### +#### Values * `kSbDrmKeyStatusUsable` * `kSbDrmKeyStatusExpired` @@ -41,24 +41,24 @@ Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-de * `kSbDrmKeyStatusPending` * `kSbDrmKeyStatusError` -### SbDrmSessionRequestType ### +### SbDrmSessionRequestType The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype) -#### Values #### +#### Values * `kSbDrmSessionRequestTypeLicenseRequest` * `kSbDrmSessionRequestTypeLicenseRenewal` * `kSbDrmSessionRequestTypeLicenseRelease` * `kSbDrmSessionRequestTypeIndividualizationRequest` -### SbDrmStatus ### +### SbDrmStatus The status of session related operations. Used by `SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and `SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names) -#### Values #### +#### Values * `kSbDrmStatusSuccess` * `kSbDrmStatusTypeError` @@ -70,42 +70,42 @@ The status of session related operations. Used by The following error can be used when the error status cannot be mapped to one of the above errors. -## Typedefs ## +## Typedefs -### SbDrmServerCertificateUpdatedFunc ### +### SbDrmServerCertificateUpdatedFunc A callback to notify the caller of SbDrmUpdateServerCertificate() whether the update has been successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message) ``` -### SbDrmSessionClosedFunc ### +### SbDrmSessionClosedFunc A callback for signalling that a session has been closed by the SbDrmSystem -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size) ``` -### SbDrmSessionKeyStatusesChangedFunc ### +### SbDrmSessionKeyStatusesChangedFunc A callback for notifications that the status of one or more keys in a session has been changed. All keys of the session and their new status will be passed along. Any keys not in the list is considered as deleted. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses) ``` -### SbDrmSessionUpdateRequestFunc ### +### SbDrmSessionUpdateRequestFunc A callback that will receive generated session update request when requested from a SbDrmSystem. `drm_system` will be the DRM system that @@ -128,13 +128,13 @@ there was an error generating the request. This allows Cobalt to find and reject the correct Promise corresponding to the associated SbDrmGenerateSessionUpdateRequest(). -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url) ``` -### SbDrmSessionUpdatedFunc ### +### SbDrmSessionUpdatedFunc A callback for notifications that a session has been added, and subsequent encrypted samples are actively ready to be decoded. `drm_system` will be the DRM @@ -150,37 +150,37 @@ context passed into that call to SbDrmCreateSystem(). `status` is `kSbDrmStatusSuccess` or if no error message can be provided. `succeeded` is whether the session was successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size) ``` -### SbDrmSystem ### +### SbDrmSystem A handle to a DRM system which can be used with either an SbDecoder or an SbPlayer. -#### Definition #### +#### Definition ``` typedef struct SbDrmSystemPrivate* SbDrmSystem ``` -## Structs ## +## Structs -### SbDrmEncryptionPattern ### +### SbDrmEncryptionPattern Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. -#### Members #### +#### Members * `uint32_t crypt_byte_block` * `uint32_t skip_byte_block` -### SbDrmKeyId ### +### SbDrmKeyId -#### Members #### +#### Members * `uint8_t identifier` @@ -188,11 +188,11 @@ Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. PlayReady, this is the license GUID in packed little-endian binary form. * `int identifier_size` -### SbDrmSampleInfo ### +### SbDrmSampleInfo All the optional information needed per sample for encrypted samples. -#### Members #### +#### Members * `SbDrmEncryptionScheme encryption_scheme` @@ -217,13 +217,13 @@ All the optional information needed per sample for encrypted samples. The clear/encrypted mapping of each subsample in this sample. This must be an array of `subsample_count` mappings. -### SbDrmSubSampleMapping ### +### SbDrmSubSampleMapping A mapping of clear and encrypted bytes for a single subsample. All subsamples within a sample must be encrypted with the same encryption parameters. The clear bytes always appear first in the sample. -#### Members #### +#### Members * `int32_t clear_byte_count` @@ -232,21 +232,21 @@ bytes always appear first in the sample. How many bytes of the corresponding subsample are encrypted. -## Functions ## +## Functions -### SbDrmCloseSession ### +### SbDrmCloseSession Clear any internal states/resources related to the specified `session_id`. `drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` -### SbDrmDestroySystem ### +### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and invalidates all outstanding session update requests. A DRM system cannot be @@ -258,13 +258,13 @@ SbDrmCreateSystem(), a deadlock will occur. `drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` void SbDrmDestroySystem(SbDrmSystem drm_system) ``` -### SbDrmGenerateSessionUpdateRequest ### +### SbDrmGenerateSessionUpdateRequest Asynchronously generates a session update request payload for `initialization_data`, of `initialization_data_size`, in case sensitive `type`, @@ -296,13 +296,13 @@ be NULL. `initialization_data`: The data for which the session update request payload is created. Must not be NULL. `initialization_data_size`: The size of the session update request payload. -#### Declaration #### +#### Declaration ``` void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size) ``` -### SbDrmGetMetrics ### +### SbDrmGetMetrics Get the metrics of the underlying drm system. @@ -326,13 +326,13 @@ system, or when the drm system implementation fails to retrieve the metrics. `drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL. -#### Declaration #### +#### Declaration ``` const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size) ``` -### SbDrmIsServerCertificateUpdatable ### +### SbDrmIsServerCertificateUpdatable Returns true if server certificate of `drm_system` can be updated via SbDrmUpdateServerCertificate(). The return value should remain the same during @@ -341,33 +341,33 @@ the life time of `drm_system`. `drm_system`: The DRM system to check if its server certificate is updatable. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system) ``` -### SbDrmSystemIsValid ### +### SbDrmSystemIsValid Indicates whether `drm_system` is a valid SbDrmSystem. -#### Declaration #### +#### Declaration ``` static bool SbDrmSystemIsValid(SbDrmSystem drm) ``` -### SbDrmTicketIsValid ### +### SbDrmTicketIsValid Indicates whether `ticket` is a valid ticket. -#### Declaration #### +#### Declaration ``` static bool SbDrmTicketIsValid(int ticket) ``` -### SbDrmUpdateServerCertificate ### +### SbDrmUpdateServerCertificate Update the server certificate of `drm_system`. The function can be called multiple times. It is possible that a call to it happens before the callback of @@ -384,13 +384,13 @@ requests with the same ticket may result in undefined behavior. The value certificate data. Must not be NULL. `certificate_size`: Size of the server certificate data. -#### Declaration #### +#### Declaration ``` void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size) ``` -### SbDrmUpdateSession ### +### SbDrmUpdateSession Update session with `key`, in `drm_system`'s key system, from the license server response. Calls `session_updated_callback` with `context` and whether the update @@ -410,7 +410,7 @@ with that DRM key system will be able to decrypt encrypted samples. thread before this function returns or from another thread. The `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` 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 b1e120b2e5ea..87deff271ad9 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/13/egl.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: egl.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `egl.h` The EGL API provides an interface with accompanying type declarations and defines that together provide a single consistent method of EGL usage across @@ -11,67 +11,67 @@ 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 functions from EGL 1.5 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_EGL_ALPHA_FORMAT ### +### SB_EGL_ALPHA_FORMAT EGL_VERSION_1_2 -### SB_EGL_ALPHA_SIZE ### +### SB_EGL_ALPHA_SIZE EGL_VERSION_1_0 -### SB_EGL_BACK_BUFFER ### +### SB_EGL_BACK_BUFFER EGL_VERSION_1_1 -### SB_EGL_CONFORMANT ### +### SB_EGL_CONFORMANT EGL_VERSION_1_3 -### SB_EGL_CONTEXT_MAJOR_VERSION ### +### SB_EGL_CONTEXT_MAJOR_VERSION EGL_VERSION_1_5 -### SB_EGL_DEFAULT_DISPLAY ### +### SB_EGL_DEFAULT_DISPLAY EGL_VERSION_1_4 -## Typedefs ## +## Typedefs -### SbEglCastsToProperFunctionPointerType ### +### SbEglCastsToProperFunctionPointerType The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/egl.h](https://www.khronos.org/registry/EGL/api/EGL/egl.h) . -#### Definition #### +#### Definition ``` typedef void(* SbEglCastsToProperFunctionPointerType) (void) ``` -### SbEglInt32 ### +### SbEglInt32 The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h](https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h) . -#### Definition #### +#### Definition ``` typedef int32_t SbEglInt32 ``` -## Structs ## +## Structs -### SbEglInterface ### +### SbEglInterface -#### Members #### +#### Members * `SbEglBoolean(*eglChooseConfig)(SbEglDisplay dpy, const SbEglInt32 *attrib_list, SbEglConfig *configs, SbEglInt32 config_size, SbEglInt32 diff --git a/cobalt/site/docs/reference/starboard/modules/13/event.md b/cobalt/site/docs/reference/starboard/modules/13/event.md index 01a9d24cadbf..7887d8d235f7 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/event.md +++ b/cobalt/site/docs/reference/starboard/modules/13/event.md @@ -1,11 +1,11 @@ ---- -layout: doc -title: "Starboard Module Reference: event.h" ---- +Project: /youtube/cobalt/_project.yaml +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 ``` * ---------- @@ -78,15 +78,15 @@ for a more graceful shutdown. Note that the application is always expected to transition through `BLURRED`, `CONCEALED` to `FROZEN` before receiving `Stop` or being killed. -## Enums ## +## Enums -### SbEventType ### +### SbEventType An enumeration of all possible event types dispatched directly by the system. Each event is accompanied by a void* data argument, and each event must define the type of the value pointed to by that data argument, if any. -#### Values #### +#### Values * `kSbEventTypePreload` @@ -273,55 +273,55 @@ the type of the value pointed to by that data argument, if any. change in the timezone setting). This should trigger the application to re- query the relevant APIs to update the date and time. -## Typedefs ## +## Typedefs -### SbEventCallback ### +### SbEventCallback A function that can be called back from the main Starboard event pump. -#### Definition #### +#### Definition ``` typedef void(* SbEventCallback) (void *context) ``` -### SbEventDataDestructor ### +### SbEventDataDestructor A function that will cleanly destroy an event data instance of a specific type. -#### Definition #### +#### Definition ``` typedef void(* SbEventDataDestructor) (void *data) ``` -### SbEventId ### +### SbEventId An ID that can be used to refer to a scheduled event. -#### Definition #### +#### Definition ``` typedef uint32_t SbEventId ``` -## Structs ## +## Structs -### SbEvent ### +### SbEvent Structure representing a Starboard event and its data. -#### Members #### +#### Members * `SbEventType type` * `SbTimeMonotonic timestamp` * `void * data` -### SbEventStartData ### +### SbEventStartData Event data for kSbEventTypeStart events. -#### Members #### +#### Members * `char ** argument_values` @@ -333,31 +333,31 @@ Event data for kSbEventTypeStart events. The startup link, if any. -### SbEventWindowSizeChangedData ### +### SbEventWindowSizeChangedData Event data for kSbEventTypeWindowSizeChanged events. -#### Members #### +#### Members * `SbWindow window` * `SbWindowSize size` -## Functions ## +## Functions -### SbEventCancel ### +### SbEventCancel Cancels the specified `event_id`. Note that this function is a no-op if the event already fired. This function can be safely called from any thread, but the only way to guarantee that the event does not run anyway is to call it from the main Starboard event loop thread. -#### Declaration #### +#### Declaration ``` void SbEventCancel(SbEventId event_id) ``` -### SbEventHandle ### +### SbEventHandle The entry point that Starboard applications MUST implement. Any memory pointed at by `event` or the `data` field inside `event` is owned by the system, and @@ -370,23 +370,23 @@ specification about what other work might happen on this thread, so the application should generally do as little work as possible on this thread, and just dispatch it over to another thread. -#### Declaration #### +#### Declaration ``` SB_IMPORT void SbEventHandle(const SbEvent *event) ``` -### SbEventIsIdValid ### +### SbEventIsIdValid Returns whether the given event handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbEventIsIdValid(SbEventId handle) ``` -### SbEventSchedule ### +### SbEventSchedule Schedules an event `callback` into the main Starboard event loop. This function may be called from any thread, but `callback` is always called from the main @@ -397,7 +397,7 @@ context that is passed to the `callback` function. `delay`: The minimum number of microseconds to wait before calling the `callback` function. Set `delay` to `0` to call the callback as soon as possible. -#### Declaration #### +#### Declaration ``` SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) diff --git a/cobalt/site/docs/reference/starboard/modules/13/export.md b/cobalt/site/docs/reference/starboard/modules/13/export.md index ff797770e824..a398d4ad0c85 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/export.md +++ b/cobalt/site/docs/reference/starboard/modules/13/export.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: export.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `export.h` Provides macros for properly exporting or importing symbols from shared libraries. -## Macros ## +## Macros -### SB_EXPORT ### +### SB_EXPORT Specification for a symbol that should be exported when building the DLL and imported when building code that uses the DLL. -### SB_EXPORT_PRIVATE ### +### SB_EXPORT_PRIVATE Specification for a symbol that should be exported or imported for testing purposes only. -### SB_IMPORT ### +### SB_IMPORT Specification for a symbol that is expected to be defined externally to this module. diff --git a/cobalt/site/docs/reference/starboard/modules/13/file.md b/cobalt/site/docs/reference/starboard/modules/13/file.md index e22edeb51ee7..02c7863d8710 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/file.md +++ b/cobalt/site/docs/reference/starboard/modules/13/file.md @@ -1,25 +1,25 @@ ---- -layout: doc -title: "Starboard Module Reference: file.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `file.h` Defines file system input/output functions. -## Macros ## +## Macros -### kSbFileInvalid ### +### kSbFileInvalid Well-defined value for an invalid file handle. -## Enums ## +## Enums -### SbFileError ### +### SbFileError kSbFileErrorAccessDenied is returned when a call fails because of a filesystem restriction. kSbFileErrorSecurity is returned when a security policy doesn't allow the operation to be executed. -#### Values #### +#### Values * `kSbFileOk` * `kSbFileErrorFailed` @@ -40,7 +40,7 @@ allow the operation to be executed. * `kSbFileErrorIO` * `kSbFileErrorMax` -### SbFileFlags ### +### SbFileFlags Flags that define how a file is used in the application. These flags should be or'd together when passed to SbFileOpen to open or create a file. @@ -66,7 +66,7 @@ In addition, one or more of the following flags must be specified: The `kSbFileAsync` flag is optional. -#### Values #### +#### Values * `kSbFileOpenOnly` * `kSbFileCreateOnly` @@ -85,35 +85,35 @@ The `kSbFileAsync` flag is optional. * `kSbFileWrite` * `kSbFileAsync` -### SbFileWhence ### +### SbFileWhence This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. -#### Values #### +#### Values * `kSbFileFromBegin` * `kSbFileFromCurrent` * `kSbFileFromEnd` -## Typedefs ## +## Typedefs -### SbFile ### +### SbFile A handle to an open file. -#### Definition #### +#### Definition ``` typedef SbFilePrivate* SbFile ``` -## Structs ## +## Structs -### SbFileInfo ### +### SbFileInfo Used to hold information about a file. -#### Members #### +#### Members * `int64_t size` @@ -134,9 +134,9 @@ Used to hold information about a file. The creation time of a file. -## Functions ## +## Functions -### SbFileAtomicReplace ### +### SbFileAtomicReplace Replaces the content of the file at `path` with `data`. Returns whether the contents of the file were replaced. The replacement of the content is an atomic @@ -146,39 +146,39 @@ operation. The file will either have all of the data, or none. to replace the file contents with. `data_size`: The amount of `data`, in bytes, to be written to the file. -#### Declaration #### +#### Declaration ``` bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size) ``` -### SbFileCanOpen ### +### SbFileCanOpen Indicates whether SbFileOpen() with the given `flags` is allowed for `path`. `path`: The absolute path to be checked. `flags`: The flags that are being evaluated for the given `path`. -#### Declaration #### +#### Declaration ``` bool SbFileCanOpen(const char *path, int flags) ``` -### SbFileClose ### +### SbFileClose Closes `file`. The return value indicates whether the file was closed successfully. `file`: The absolute path of the file to be closed. -#### Declaration #### +#### Declaration ``` bool SbFileClose(SbFile file) ``` -### SbFileDelete ### +### SbFileDelete Deletes the regular file, symlink, or empty directory at `path`. This function is used primarily to clean up after unit tests. On some platforms, this function @@ -186,38 +186,38 @@ fails if the file in question is being held open. `path`: The absolute path of the file, symlink, or directory to be deleted. -#### Declaration #### +#### Declaration ``` bool SbFileDelete(const char *path) ``` -### SbFileExists ### +### SbFileExists Indicates whether a file or directory exists at `path`. `path`: The absolute path of the file or directory being checked. -#### Declaration #### +#### Declaration ``` bool SbFileExists(const char *path) ``` -### SbFileFlush ### +### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed. `file`: The SbFile to which the write buffer is flushed. -#### Declaration #### +#### Declaration ``` bool SbFileFlush(SbFile file) ``` -### SbFileGetInfo ### +### SbFileGetInfo Retrieves information about `file`. The return value indicates whether the file information was retrieved successfully. @@ -226,13 +226,13 @@ information was retrieved successfully. into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetInfo(SbFile file, SbFileInfo *out_info) ``` -### SbFileGetPathInfo ### +### SbFileGetPathInfo Retrieves information about the file at `path`. The return value indicates whether the file information was retrieved successfully. @@ -241,36 +241,36 @@ whether the file information was retrieved successfully. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info) ``` -### SbFileIsValid ### +### SbFileIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbFileIsValid(SbFile file) ``` -### SbFileModeStringToFlags ### +### SbFileModeStringToFlags Converts an ISO `fopen()` mode string into flags that can be equivalently passed into SbFileOpen(). `mode`: The mode string to be converted into flags. -#### Declaration #### +#### Declaration ``` int SbFileModeStringToFlags(const char *mode) ``` -### SbFileOpen ### +### SbFileOpen Opens the file at `path`, which must be absolute, creating it if specified by `flags`. The read/write position is at the beginning of the file. @@ -287,13 +287,13 @@ which can happen if the `kSbFileCreateAlways` flag is set. Otherwise, Starboard sets this value to `false`. `out_error`: If `path` cannot be created, this is set to `kSbFileInvalid`. Otherwise, it is `NULL`. -#### Declaration #### +#### Declaration ``` SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error) ``` -### SbFileRead ### +### SbFileRead Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -306,13 +306,13 @@ However, this function can be run in a loop to make it a best-effort read. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` int SbFileRead(SbFile file, char *data, int size) ``` -### SbFileReadAll ### +### SbFileReadAll Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -326,13 +326,13 @@ be read unless there is an error. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` static int SbFileReadAll(SbFile file, char *data, int size) ``` -### SbFileSeek ### +### SbFileSeek Changes the current read/write position in `file`. The return value identifies the resultant current read/write position in the file (relative to the start) or @@ -344,13 +344,13 @@ The starting read/write position. The position is modified relative to this value. `offset`: The amount that the read/write position is changed, relative to `whence`. -#### Declaration #### +#### Declaration ``` int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset) ``` -### SbFileTruncate ### +### SbFileTruncate Truncates the given `file` to the given `length`. The return value indicates whether the file was truncated successfully. @@ -360,13 +360,13 @@ after it is truncated. If `length` is greater than the current size of the file, then the file is extended with zeros. If `length` is negative, then the function is a no-op and returns `false`. -#### Declaration #### +#### Declaration ``` bool SbFileTruncate(SbFile file, int64_t length) ``` -### SbFileWrite ### +### SbFileWrite Writes the given buffer into `file` at the file's current position, overwriting any data that was previously there. @@ -380,13 +380,13 @@ in a loop to ensure that all data is written. `file`: The SbFile to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` int SbFileWrite(SbFile file, const char *data, int size) ``` -### SbFileWriteAll ### +### SbFileWriteAll Writes the given buffer into `file`, starting at the beginning of the file, and overwriting any data that was previously there. Unlike SbFileWrite, this @@ -397,7 +397,7 @@ The return value identifies the number of bytes written, or `-1` on error. `file`: The file to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` 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 7a9108a25280..049838f80b65 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/13/gles.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: gles.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `gles.h` The GLES API provides an interface with accompanying type declarations and defines that together provide a single consistent method of GLES usage across @@ -11,37 +11,37 @@ 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 the functions from GLES 3.0 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_GL_DEPTH_BUFFER_BIT ### +### SB_GL_DEPTH_BUFFER_BIT Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) -### SB_GL_READ_BUFFER ### +### SB_GL_READ_BUFFER Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h](https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h) . -## Typedefs ## +## Typedefs -### SbGlBoolean ### +### SbGlBoolean The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) . -#### Definition #### +#### Definition ``` typedef uint8_t SbGlBoolean ``` -### SbGlIntPtr ### +### SbGlIntPtr Some compilers will transform the intptr_t to an int transparently behind the scenes, which is not equivalent to a long int, or long long int, as far as the @@ -49,17 +49,17 @@ compiler is concerned. We check the Starboard configuration and set the types to those exact types used by OpenGL ES 2.0 ( [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h) ). -#### Definition #### +#### Definition ``` typedef long int SbGlIntPtr ``` -## Structs ## +## Structs -### SbGlesInterface ### +### SbGlesInterface -#### Members #### +#### Members * `void(*glActiveTexture)(SbGlEnum texture)` diff --git a/cobalt/site/docs/reference/starboard/modules/13/image.md b/cobalt/site/docs/reference/starboard/modules/13/image.md index 1427d3995d54..945938a09903 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/image.md +++ b/cobalt/site/docs/reference/starboard/modules/13/image.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: image.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `image.h` API for hardware accelerated image decoding. This module allows for the client to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It @@ -11,7 +11,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(); @@ -28,9 +28,9 @@ SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); ``` -## Functions ## +## Functions -### SbImageDecode ### +### SbImageDecode Attempt to decode encoded `mime_type` image data `data` of size `data_size` into an SbDecodeTarget of SbDecodeFormatType `format`, possibly using @@ -56,13 +56,13 @@ scenarios regarding the provider may happen: kSbDecodeTargetInvalid will be returned, with any intermediate allocations being cleaned up in the implementation. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) ``` -### SbImageIsDecodeSupported ### +### SbImageIsDecodeSupported Whether the current platform supports hardware accelerated decoding an image of mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must @@ -70,7 +70,7 @@ not be NULL. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. -#### Declaration #### +#### Declaration ``` 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 e8df816a4987..d2dd2db32dc5 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/input.md +++ b/cobalt/site/docs/reference/starboard/modules/13/input.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: input.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `input.h` Defines input events and associated data types. -## Enums ## +## Enums -### SbInputDeviceType ### +### SbInputDeviceType Identifies possible input subsystem types. The types of events that each device type produces correspond to `SbInputEventType` values. -#### Values #### +#### Values * `kSbInputDeviceTypeGesture` @@ -57,11 +57,11 @@ type produces correspond to `SbInputEventType` values. Produces `Input` events. -### SbInputEventType ### +### SbInputEventType The action that an input event represents. -#### Values #### +#### Values * `kSbInputEventTypeMove` @@ -86,13 +86,13 @@ The action that an input event represents. [https://w3c.github.io/uievents/#event-type-input](https://w3c.github.io/uievents/#event-type-input) -## Structs ## +## Structs -### SbInputData ### +### SbInputData Event data for `kSbEventTypeInput` events. -#### Members #### +#### Members * `SbWindow window` @@ -160,11 +160,11 @@ Event data for `kSbEventTypeInput` events. Set to true if the input event is part of a composition event. -### SbInputVector ### +### SbInputVector A 2-dimensional vector used to represent points and motion vectors. -#### Members #### +#### Members * `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 16be3c144b4b..853f820a65ad 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/key.md +++ b/cobalt/site/docs/reference/starboard/modules/13/key.md @@ -1,19 +1,19 @@ ---- -layout: doc -title: "Starboard Module Reference: key.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `key.h` Defines the canonical set of Starboard key codes. -## Enums ## +## Enums -### SbKey ### +### SbKey A standard set of key codes, ordered by value, that represent each possible input key across all kinds of devices. Starboard uses the semi-standard Windows virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx) -#### Values #### +#### Values * `kSbKeyUnknown` * `kSbKeyCancel` @@ -274,11 +274,11 @@ virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windo * `kSbKeyGamepadRightStickLeft` * `kSbKeyGamepadRightStickRight` -### SbKeyModifiers ### +### SbKeyModifiers Bit-mask of key modifiers. -#### Values #### +#### Values * `kSbKeyModifiersNone` * `kSbKeyModifiersAlt` diff --git a/cobalt/site/docs/reference/starboard/modules/13/log.md b/cobalt/site/docs/reference/starboard/modules/13/log.md index 42de5138c303..6cf3a491a2a7 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/log.md +++ b/cobalt/site/docs/reference/starboard/modules/13/log.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: log.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `log.h` Defines core debug logging functions. -## Enums ## +## Enums -### SbLogPriority ### +### SbLogPriority The priority at which a message should be logged. The platform may be configured to filter logs by priority, or render them differently. -#### Values #### +#### Values * `kSbLogPriorityUnknown` * `kSbLogPriorityInfo` @@ -20,9 +20,9 @@ to filter logs by priority, or render them differently. * `kSbLogPriorityError` * `kSbLogPriorityFatal` -## Functions ## +## Functions -### SbLog ### +### SbLog Writes `message` to the platform's debug output log. This method is thread-safe, and responsible for ensuring that the output from multiple threads is not mixed. @@ -35,55 +35,55 @@ NULL. No formatting is required to be done on the value, including newline termination. That said, platforms can adjust the message to be more suitable for their output method by wrapping the text, stripping unprintable characters, etc. -#### Declaration #### +#### Declaration ``` void SbLog(SbLogPriority priority, const char *message) ``` -### SbLogFlush ### +### SbLogFlush Flushes the log buffer on some platforms. This method is safe to call from multiple threads. -#### Declaration #### +#### Declaration ``` void SbLogFlush() ``` -### SbLogFormat ### +### SbLogFormat A log output method that additionally performs a string format on the data being logged. -#### Declaration #### +#### Declaration ``` void SbLogFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogFormatF ### +### SbLogFormatF Inline wrapper of SbLogFormat that converts from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` void static void static void SbLogFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` -### SbLogIsTty ### +### SbLogIsTty Indicates whether the log output goes to a TTY or is being redirected. -#### Declaration #### +#### Declaration ``` bool SbLogIsTty() ``` -### SbLogRaw ### +### SbLogRaw A bare-bones log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). It should not do any @@ -91,13 +91,13 @@ additional formatting. `message`: The message to be logged. Must not be NULL. -#### Declaration #### +#### Declaration ``` void SbLogRaw(const char *message) ``` -### SbLogRawDumpStack ### +### SbLogRawDumpStack Dumps the stack of the current thread to the log in an async-signal-safe manner, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` @@ -108,28 +108,28 @@ dumping the current thread to the log. This parameter lets you remove noise from helper functions that might end up on top of every stack dump so that the stack dump is just the relevant function stack where the problem occurred. -#### Declaration #### +#### Declaration ``` void SbLogRawDumpStack(int frames_to_skip) ``` -### SbLogRawFormat ### +### SbLogRawFormat A formatted log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). -#### Declaration #### +#### Declaration ``` void SbLogRawFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogRawFormatF ### +### SbLogRawFormatF Inline wrapper of SbLogFormat to convert from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` 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 968db5b80de4..5ea1ef8f1657 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/media.md +++ b/cobalt/site/docs/reference/starboard/modules/13/media.md @@ -1,28 +1,28 @@ ---- -layout: doc -title: "Starboard Module Reference: media.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `media.h` Provides media definitions that are common between the Decoder and Player interfaces. -## Macros ## +## Macros -### kSbMediaBitsPerPixelInvalid ### +### kSbMediaBitsPerPixelInvalid Value used when a video's bits per pixel is not known. -### kSbMediaVideoResolutionDimensionInvalid ### +### kSbMediaVideoResolutionDimensionInvalid Value used when a video's resolution is not known. -## Enums ## +## Enums -### SbMediaAudioCodec ### +### SbMediaAudioCodec Types of audio elementary streams that can be supported. -#### Values #### +#### Values * `kSbMediaAudioCodecNone` * `kSbMediaAudioCodecAac` @@ -31,11 +31,11 @@ Types of audio elementary streams that can be supported. * `kSbMediaAudioCodecOpus` * `kSbMediaAudioCodecVorbis` -### SbMediaAudioCodingType ### +### SbMediaAudioCodingType Possible audio coding types. -#### Values #### +#### Values * `kSbMediaAudioCodingTypeNone` * `kSbMediaAudioCodingTypeAac` @@ -49,11 +49,11 @@ Possible audio coding types. * `kSbMediaAudioCodingTypeMpeg3` * `kSbMediaAudioCodingTypePcm` -### SbMediaAudioConnector ### +### SbMediaAudioConnector Possible audio connector types. -#### Values #### +#### Values * `kSbMediaAudioConnectorNone` * `kSbMediaAudioConnectorAnalog` @@ -63,11 +63,11 @@ Possible audio connector types. * `kSbMediaAudioConnectorSpdif` * `kSbMediaAudioConnectorUsb` -### SbMediaAudioFrameStorageType ### +### SbMediaAudioFrameStorageType Possible audio frame storage types. -#### Values #### +#### Values * `kSbMediaAudioFrameStorageTypeInterleaved` @@ -83,22 +83,22 @@ Possible audio frame storage types. with timestamps 0, 1, 2, etc., the samples are stored in two buffers "L0 L1 L2 ..." and "R0 R1 R2 ...". -### SbMediaAudioSampleType ### +### SbMediaAudioSampleType Possible audio sample types. -#### Values #### +#### Values * `kSbMediaAudioSampleTypeInt16Deprecated` * `kSbMediaAudioSampleTypeFloat32` -### SbMediaRangeId ### +### SbMediaRangeId This corresponds to the WebM Range enum which is part of WebM color data (see [http://www.webmproject.org/docs/container/#Range](http://www.webmproject.org/docs/container/#Range) ). H.264 only uses a bool, which corresponds to the LIMITED/FULL values. Chrome- specific values start at 1000. -#### Values #### +#### Values * `kSbMediaRangeIdUnspecified` @@ -114,13 +114,13 @@ specific values start at 1000. Range is defined by TransferId/MatrixId. * `kSbMediaRangeIdLast` -### SbMediaSupportType ### +### SbMediaSupportType Indicates how confident the device is that it can play media resources of the given type. The values are a direct map of the canPlayType() method specified at the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype](https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype) -#### Values #### +#### Values * `kSbMediaSupportTypeNotSupported` @@ -132,11 +132,11 @@ the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom The media type seems to be playable. -### SbMediaType ### +### SbMediaType Types of media component streams. -#### Values #### +#### Values * `kSbMediaTypeAudio` @@ -145,11 +145,11 @@ Types of media component streams. Value used for video streams. -### SbMediaVideoCodec ### +### SbMediaVideoCodec Types of video elementary streams that could be supported. -#### Values #### +#### Values * `kSbMediaVideoCodecNone` * `kSbMediaVideoCodecH264` @@ -161,14 +161,14 @@ Types of video elementary streams that could be supported. * `kSbMediaVideoCodecVp8` * `kSbMediaVideoCodecVp9` -## Structs ## +## Structs -### SbMediaAudioConfiguration ### +### SbMediaAudioConfiguration A structure describing the audio configuration parameters of a single audio output. -#### Members #### +#### Members * `int index` @@ -190,7 +190,7 @@ output. `0` if this device cannot provide this information, in which case the caller can probably assume stereo output. -### SbMediaAudioSampleInfo ### +### SbMediaAudioSampleInfo An audio sample info, which is a description of a given audio sample. This acts as a set of instructions to the audio decoder. @@ -200,7 +200,7 @@ structure, as well as other information for the audio decoder, including the Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at [http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx](http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx)x) . -#### Members #### +#### Members * `SbMediaAudioCodec codec` @@ -235,14 +235,14 @@ Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1: [http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF](http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF) -### SbMediaColorMetadata ### +### SbMediaColorMetadata HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR formats, together with the ColorSpace. HDR reproduces a greater dynamic range of luminosity than is possible with standard digital imaging. See the Consumer Electronics Association press release: [https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) -#### Members #### +#### Members * `unsigned int bits_per_channel` @@ -323,7 +323,7 @@ Electronics Association press release: [https://www.cta.tech/News/Press-Releases a row-major ordered 3 x 4 submatrix of the 4 x 4 transform matrix. The 4th row is completed as (0, 0, 0, 1). -### SbMediaMasteringMetadata ### +### SbMediaMasteringMetadata SMPTE 2086 mastering data [http://ieeexplore.ieee.org/document/7291707/](http://ieeexplore.ieee.org/document/7291707/) This standard specifies the metadata items to specify the color volume (the @@ -332,7 +332,7 @@ in mastering video content. The metadata is specified as a set of values independent of any specific digital representation. Also see the WebM container guidelines: [https://www.webmproject.org/docs/container/](https://www.webmproject.org/docs/container/) -#### Members #### +#### Members * `float primary_r_chromaticity_x` @@ -367,11 +367,11 @@ guidelines: [https://www.webmproject.org/docs/container/](https://www.webmprojec Minimum luminance. Shall be represented in candelas per square meter (cd/m^2). In range [0, 9999.99]. -### SbMediaVideoSampleInfo ### +### SbMediaVideoSampleInfo The set of information required by the decoder or player for each video sample. -#### Members #### +#### Members * `SbMediaVideoCodec codec` @@ -417,9 +417,9 @@ The set of information required by the decoder or player for each video sample. . This will only be specified on frames where the HDR metadata and color / color space might have changed (e.g. keyframes). -## Functions ## +## Functions -### SbMediaCanPlayMimeAndKeySystem ### +### SbMediaCanPlayMimeAndKeySystem Returns information about whether the playback of the specific media described by `mime` and encrypted using `key_system` can be played. @@ -463,13 +463,13 @@ return `kSbMediaSupportTypeProbably` kSbMediaSupportTypeProbably when implementation supports key system with attributes on one key system, it has to support key system with attributes on all key systems supported. -#### Declaration #### +#### Declaration ``` SbMediaSupportType SbMediaCanPlayMimeAndKeySystem(const char *mime, const char *key_system) ``` -### SbMediaGetAudioBufferBudget ### +### SbMediaGetAudioBufferBudget Specifies the maximum amount of memory used by audio buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -477,13 +477,13 @@ being used by audio buffers but will also make the app less likely to re- download audio data. Note that the app may experience significant difficulty if this value is too low. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioBufferBudget() ``` -### SbMediaGetAudioConfiguration ### +### SbMediaGetAudioConfiguration Retrieves the current physical audio configuration of audio output `output_index` on this device and places it in `out_configuration`, which must @@ -495,38 +495,38 @@ if `output_index` does not exist on this device. `out_configuration`: The variable that holds the audio configuration information. -#### Declaration #### +#### Declaration ``` bool SbMediaGetAudioConfiguration(int output_index, SbMediaAudioConfiguration *out_configuration) ``` -### SbMediaGetAudioOutputCount ### +### SbMediaGetAudioOutputCount Returns the number of audio outputs currently available on this device. Even if the number of outputs or their audio configurations can't be determined, it is expected that the platform will at least return a single output that supports at least stereo. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioOutputCount() ``` -### SbMediaGetBufferAlignment ### +### SbMediaGetBufferAlignment The media buffer will be allocated using the returned alignment. Set this to a larger value may increase the memory consumption of media buffers.`type`: the media type of the stream (audio or video). -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferAlignment(SbMediaType type) ``` -### SbMediaGetBufferAllocationUnit ### +### SbMediaGetBufferAllocationUnit When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can @@ -534,13 +534,13 @@ 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferAllocationUnit() ``` -### SbMediaGetBufferGarbageCollectionDurationThreshold ### +### SbMediaGetBufferGarbageCollectionDurationThreshold Specifies the duration threshold of media source garbage collection. When the accumulated duration in a source buffer exceeds this value, the media source @@ -551,25 +551,25 @@ 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 #### +#### Declaration ``` SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() ``` -### SbMediaGetBufferPadding ### +### SbMediaGetBufferPadding Extra bytes allocated at the end of a media buffer to ensure that the buffer can be use optimally by specific instructions like SIMD. Set to 0 to remove any padding.`type`: the media type of the stream (audio or video). -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferPadding(SbMediaType type) ``` -### SbMediaGetBufferStorageType ### +### SbMediaGetBufferStorageType Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored @@ -579,26 +579,26 @@ by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when its value is "file" the media stack will still allocate memory to cache the the buffers in use. -#### Declaration #### +#### Declaration ``` SbMediaBufferStorageType SbMediaGetBufferStorageType() ``` -### SbMediaGetInitialBufferCapacity ### +### SbMediaGetInitialBufferCapacity The amount of memory that will be used to store media buffers allocated during system startup. To allocate a large chunk at startup helps with reducing fragmentation and can avoid failures to allocate incrementally. This can return 0. -#### Declaration #### +#### Declaration ``` int SbMediaGetInitialBufferCapacity() ``` -### SbMediaGetMaxBufferCapacity ### +### SbMediaGetMaxBufferCapacity The maximum amount of memory that will be used to store media buffers. This must be larger than sum of the video budget and audio budget. This is a soft limit @@ -613,13 +613,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetProgressiveBufferBudget ### +### SbMediaGetProgressiveBufferBudget The memory used when playing mp4 videos that is not in DASH format. The resolution of such videos shouldn't go beyond 1080p. Its value should be less @@ -631,13 +631,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetVideoBufferBudget ### +### SbMediaGetVideoBufferBudget Specifies the maximum amount of memory used by video buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -650,13 +650,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaIsBufferPoolAllocateOnDemand ### +### SbMediaIsBufferPoolAllocateOnDemand When either SbMediaGetInitialBufferCapacity or SbMediaGetBufferAllocationUnit isn't zero, media buffers will be allocated using a memory pool. Set the @@ -667,24 +667,24 @@ SbMediaGetInitialBufferCapacity bytes for media buffer on startup and will not release any media buffer memory back to the system even if there is no media buffers allocated. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferPoolAllocateOnDemand() ``` -### SbMediaIsBufferUsingMemoryPool ### +### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer pools should be allocated on demand, as opposed to using SbMemory* functions. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferUsingMemoryPool() ``` -### SbMediaSetAudioWriteDuration ### +### SbMediaSetAudioWriteDuration Communicate to the platform how far past `current_playback_position` the app will write audio samples. The app will write all samples between @@ -696,7 +696,7 @@ in general. The platform is responsible for guaranteeing that when only as transient or indefinite hanging). The platform may assume `duration` >= 0.5 seconds. -#### Declaration #### +#### Declaration ``` void SbMediaSetAudioWriteDuration(SbTime duration) diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory.md b/cobalt/site/docs/reference/starboard/modules/13/memory.md index e09dbc3cf67e..3905f6f89a29 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/13/memory.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: memory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. -## Porters ## +## 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 @@ -26,14 +26,14 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. * The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). -## Enums ## +## Enums -### SbMemoryMapFlags ### +### SbMemoryMapFlags The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used. -#### Values #### +#### Values * `kSbMemoryMapProtectReserved` @@ -44,9 +44,9 @@ the mapped memory can be used. * `kSbMemoryMapProtectExec` * `kSbMemoryMapProtectReadWrite` -## Functions ## +## Functions -### SbMemoryAllocate ### +### SbMemoryAllocate Allocates and returns a chunk of memory of at least `size` bytes. This function should be called from the client codebase. It is intended to be a drop-in @@ -58,13 +58,13 @@ Note that this function returns `NULL` if it is unable to allocate the memory. return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocate(size_t size) ``` -### SbMemoryAllocateAligned ### +### SbMemoryAllocateAligned Allocates and returns a chunk of memory of at least `size` bytes, aligned to `alignment`. This function should be called from the client codebase. It is @@ -78,87 +78,87 @@ must be a power of two. `size`: The size of the memory to be allocated. If `size` is `0`, the function may return `NULL` or it may return a unique aligned pointer value that can be passed to SbMemoryDeallocateAligned. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAligned(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedChecked ### +### SbMemoryAllocateAlignedChecked Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedUnchecked ### +### SbMemoryAllocateAlignedUnchecked This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateChecked ### +### SbMemoryAllocateChecked Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateChecked(size_t size) ``` -### SbMemoryAllocateNoReport ### +### SbMemoryAllocateNoReport Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateNoReport(size_t size) ``` -### SbMemoryAllocateUnchecked ### +### SbMemoryAllocateUnchecked This is the implementation of SbMemoryAllocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateUnchecked(size_t size) ``` -### SbMemoryCalloc ### +### SbMemoryCalloc A wrapper that implements a drop-in replacement for `calloc`, which is used in some packages. -#### Declaration #### +#### Declaration ``` static void* SbMemoryCalloc(size_t count, size_t size) ``` -### SbMemoryDeallocate ### +### SbMemoryDeallocate Frees a previously allocated chunk of memory. If `memory` is NULL, then the operation is a no-op. This function should be called from the client codebase. @@ -166,87 +166,87 @@ It is meant to be a drop-in replacement for `free`. `memory`: The chunk of memory to be freed. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocate(void *memory) ``` -### SbMemoryDeallocateAligned ### +### SbMemoryDeallocateAligned `memory`: The chunk of memory to be freed. If `memory` is NULL, then the function is a no-op. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateAligned(void *memory) ``` -### SbMemoryDeallocateNoReport ### +### SbMemoryDeallocateNoReport Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport(). -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateNoReport(void *memory) ``` -### SbMemoryFlush ### +### SbMemoryFlush Flushes any data in the given virtual address range that is cached locally in the current processor core to physical memory, ensuring that data and instruction caches are cleared. This is required to be called on executable memory that has been written to and might be executed in the future. -#### Declaration #### +#### Declaration ``` void SbMemoryFlush(void *virtual_address, int64_t size_bytes) ``` -### SbMemoryFree ### +### SbMemoryFree This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocate(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFree(void *memory) ``` -### SbMemoryFreeAligned ### +### SbMemoryFreeAligned This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFreeAligned(void *memory) ``` -### SbMemoryGetStackBounds ### +### SbMemoryGetStackBounds Gets the stack bounds for the current thread. `out_high`: The highest addressable byte + 1 for the current thread. `out_low`: The lowest addressable byte for the current thread. -#### Declaration #### +#### Declaration ``` void SbMemoryGetStackBounds(void **out_high, void **out_low) ``` -### SbMemoryMap ### +### SbMemoryMap Allocates `size_bytes` worth of physical memory pages and maps them into an available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on @@ -261,24 +261,24 @@ used, the address space will not be accessible and, if possible, the platform should not count it against any memory budget. `name`: A value that appears in the debugger on some platforms. The value can be up to 32 bytes. -#### Declaration #### +#### Declaration ``` void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) ``` -### SbMemoryProtect ### +### SbMemoryProtect Change the protection of `size_bytes` of memory regions, starting from `virtual_address`, to `flags`, returning `true` on success. -#### Declaration #### +#### Declaration ``` bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) ``` -### SbMemoryReallocate ### +### SbMemoryReallocate Attempts to resize `memory` to be at least `size` bytes, without touching the contents of memory. @@ -298,39 +298,39 @@ it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which `memory` will be resized. If `size` is `0`, the function may return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocate(void *memory, size_t size) ``` -### SbMemoryReallocateChecked ### +### SbMemoryReallocateChecked Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateChecked(void *memory, size_t size) ``` -### SbMemoryReallocateUnchecked ### +### SbMemoryReallocateUnchecked This is the implementation of SbMemoryReallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateUnchecked(void *memory, size_t size) ``` -### SbMemoryUnmap ### +### SbMemoryUnmap Unmap `size_bytes` of physical pages starting from `virtual_address`, returning `true` on success. After this function completes, [virtual_address, @@ -340,7 +340,7 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns `(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns `(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. -#### Declaration #### +#### Declaration ``` bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md index 4b4a5397a504..433d0044238d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md +++ b/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md @@ -1,57 +1,57 @@ ---- -layout: doc -title: "Starboard Module Reference: memory_reporter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory_reporter.h` Provides an interface for memory reporting. -## Typedefs ## +## Typedefs -### SbMemoryReporterOnAlloc ### +### SbMemoryReporterOnAlloc A function to report a memory allocation from SbMemoryAllocate(). Note that operator new calls SbMemoryAllocate which will delegate to this callback. -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnAlloc) (void *context, const void *memory, size_t size) ``` -### SbMemoryReporterOnDealloc ### +### SbMemoryReporterOnDealloc A function to report a memory deallocation from SbMemoryDeallcoate(). Note that operator delete calls SbMemoryDeallocate which will delegate to this callback. -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnDealloc) (void *context, const void *memory) ``` -### SbMemoryReporterOnMapMemory ### +### SbMemoryReporterOnMapMemory A function to report a memory mapping from SbMemoryMap(). -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnMapMemory) (void *context, const void *memory, size_t size) ``` -### SbMemoryReporterOnUnMapMemory ### +### SbMemoryReporterOnUnMapMemory A function to report a memory unmapping from SbMemoryUnmap(). -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnUnMapMemory) (void *context, const void *memory, size_t size) ``` -## Structs ## +## Structs -### SbMemoryReporter ### +### 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 @@ -59,7 +59,7 @@ struct initialization is used so that the arguments can be typed check by the compiler. For example, SbMemoryReporter mem_reporter = { MallocCallback, .... context }; -#### Members #### +#### Members * `SbMemoryReporterOnAlloc on_alloc_cb` @@ -77,9 +77,9 @@ context }; Optional, is passed to callbacks as first argument. -## Functions ## +## Functions -### SbMemorySetReporter ### +### SbMemorySetReporter Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime management is done internally on input pointer. @@ -96,7 +96,7 @@ SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); ... SbMemorySetReporter(NULL); delete mem_reporter; // May crash. -#### Declaration #### +#### Declaration ``` 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 1379f86726ae..497cbe91cec4 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/13/microphone.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: microphone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `microphone.h` Defines functions for microphone creation, control, audio data fetching, and destruction. This module supports multiple calls to `SbMicrophoneOpen` and @@ -31,23 +31,23 @@ How to use this API: 1. Destroy the microphone with `SbMicrophoneDestroy`. -## Macros ## +## Macros -### kSbMicrophoneIdInvalid ### +### kSbMicrophoneIdInvalid Well-defined value for an invalid microphone ID handle. -### kSbMicrophoneInvalid ### +### kSbMicrophoneInvalid Well-defined value for an invalid microphone handle. -## Enums ## +## Enums -### SbMicrophoneType ### +### SbMicrophoneType All possible microphone types. -#### Values #### +#### Values * `kSbMicrophoneCamera` @@ -66,37 +66,37 @@ All possible microphone types. Unknown microphone type. The microphone could be different than the other enum descriptions or could fall under one of those descriptions. -## Typedefs ## +## Typedefs -### SbMicrophone ### +### SbMicrophone An opaque handle to an implementation-private structure that represents a microphone. -#### Definition #### +#### Definition ``` typedef struct SbMicrophonePrivate* SbMicrophone ``` -### SbMicrophoneId ### +### SbMicrophoneId An opaque handle to an implementation-private structure that represents a microphone ID. -#### Definition #### +#### Definition ``` typedef struct SbMicrophoneIdPrivate* SbMicrophoneId ``` -## Structs ## +## Structs -### SbMicrophoneInfo ### +### SbMicrophoneInfo Microphone information. -#### Members #### +#### Members * `SbMicrophoneId id` @@ -116,9 +116,9 @@ Microphone information. of the microphone type. For example, "Headset Microphone". The string must be null terminated. -## Functions ## +## Functions -### SbMicrophoneClose ### +### SbMicrophoneClose Closes the microphone port, stops recording audio on `microphone`, and clears the unread buffer if it is not empty. If the microphone has already been @@ -127,13 +127,13 @@ is closed. `microphone`: The microphone to close. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneClose(SbMicrophone microphone) ``` -### SbMicrophoneCreate ### +### SbMicrophoneCreate Creates a microphone with the specified ID, audio sample rate, and cached audio buffer size. Starboard only requires support for creating one microphone at a @@ -153,25 +153,25 @@ from the audio buffer if it has been read, and new audio data can be read from this buffer in smaller chunks than this size. This parameter must be set to a value greater than zero and the ideal size is `2^n`. -#### Declaration #### +#### Declaration ``` SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size_bytes) ``` -### SbMicrophoneDestroy ### +### SbMicrophoneDestroy Destroys a microphone. If the microphone is in started state, it is first stopped and then destroyed. Any data that has been recorded and not read is thrown away. -#### Declaration #### +#### Declaration ``` void SbMicrophoneDestroy(SbMicrophone microphone) ``` -### SbMicrophoneGetAvailable ### +### SbMicrophoneGetAvailable Retrieves all currently available microphone information and stores it in `out_info_array`. The return value is the number of the available microphones. @@ -184,43 +184,43 @@ indicates that an internal error occurred. placed into this output parameter. `info_array_size`: The size of `out_info_array`. -#### Declaration #### +#### Declaration ``` int SbMicrophoneGetAvailable(SbMicrophoneInfo *out_info_array, int info_array_size) ``` -### SbMicrophoneIdIsValid ### +### SbMicrophoneIdIsValid Indicates whether the given microphone ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIdIsValid(SbMicrophoneId id) ``` -### SbMicrophoneIsSampleRateSupported ### +### SbMicrophoneIsSampleRateSupported Indicates whether the microphone supports the sample rate. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz) ``` -### SbMicrophoneIsValid ### +### SbMicrophoneIsValid Indicates whether the given microphone is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIsValid(SbMicrophone microphone) ``` -### SbMicrophoneOpen ### +### SbMicrophoneOpen Opens the microphone port and starts recording audio on `microphone`. @@ -230,13 +230,13 @@ clears the unread buffer. The return value indicates whether the microphone is open. `microphone`: The microphone that will be opened and will start recording audio. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneOpen(SbMicrophone microphone) ``` -### SbMicrophoneRead ### +### SbMicrophoneRead Retrieves the recorded audio data from the microphone and writes that data to `out_audio_data`. @@ -255,7 +255,7 @@ audio data is thrown out. No audio data is read from a stopped microphone. smaller than `min_read_size` of `SbMicrophoneInfo`, the extra audio data that has already been read from the device is discarded. -#### Declaration #### +#### Declaration ``` 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 58f19079f56a..9c18999b7479 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/13/mutex.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: mutex.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `mutex.h` Defines a mutually exclusive lock that can be used to coordinate with other threads. -## Macros ## +## Macros -### SB_MUTEX_MAX_SIZE ### +### SB_MUTEX_MAX_SIZE Max size of the SbMutex type. -## Enums ## +## Enums -### SbMutexResult ### +### SbMutexResult Enumeration of possible results from acquiring a mutex. -#### Values #### +#### Values * `kSbMutexAcquired` @@ -30,22 +30,22 @@ Enumeration of possible results from acquiring a mutex. The mutex has already been destroyed. -## Typedefs ## +## Typedefs -### SbMutex ### +### SbMutex An opaque handle to a mutex type with reserved memory buffer of size SB_MUTEX_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbMutex SbMutex ``` -## Functions ## +## Functions -### SbMutexAcquire ### +### SbMutexAcquire Acquires `mutex`, blocking indefinitely. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition @@ -53,13 +53,13 @@ blocks forever. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquire(SbMutex *mutex) ``` -### SbMutexAcquireTry ### +### SbMutexAcquireTry Acquires `mutex`, without blocking. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition has undefined @@ -67,52 +67,52 @@ behavior. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquireTry(SbMutex *mutex) ``` -### SbMutexCreate ### +### SbMutexCreate Creates a new mutex. The return value indicates whether the function was able to create a new mutex. `out_mutex`: The handle to the newly created mutex. -#### Declaration #### +#### Declaration ``` bool SbMutexCreate(SbMutex *out_mutex) ``` -### SbMutexDestroy ### +### SbMutexDestroy Destroys a mutex. The return value indicates whether the destruction was successful. Destroying a locked mutex results in undefined behavior. `mutex`: The mutex to be invalidated. -#### Declaration #### +#### Declaration ``` bool SbMutexDestroy(SbMutex *mutex) ``` -### SbMutexIsSuccess ### +### SbMutexIsSuccess Indicates whether the given result is a success. A value of `true` indicates that the mutex was acquired. `result`: The result being checked. -#### Declaration #### +#### Declaration ``` static bool SbMutexIsSuccess(SbMutexResult result) ``` -### SbMutexRelease ### +### SbMutexRelease Releases `mutex` held by the current thread. The return value indicates whether the release was successful. Releases should always be successful if `mutex` is @@ -120,7 +120,7 @@ held by the current thread. `mutex`: The mutex to be released. -#### Declaration #### +#### Declaration ``` bool SbMutexRelease(SbMutex *mutex) diff --git a/cobalt/site/docs/reference/starboard/modules/13/once.md b/cobalt/site/docs/reference/starboard/modules/13/once.md index ce3c4d637c8c..3088cd90e625 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/once.md +++ b/cobalt/site/docs/reference/starboard/modules/13/once.md @@ -1,43 +1,43 @@ ---- -layout: doc -title: "Starboard Module Reference: once.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `once.h` Onces represent initializations that should only ever happen once per process, in a thread-safe way. -## Macros ## +## Macros -### SB_ONCE_MAX_SIZE ### +### SB_ONCE_MAX_SIZE Max size of the SbOnceControl type. -## Typedefs ## +## Typedefs -### SbOnceControl ### +### SbOnceControl An opaque handle to a once control type with reserved memory buffer of size SB_ONCE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbOnceControl SbOnceControl ``` -### SbOnceInitRoutine ### +### SbOnceInitRoutine Function pointer type for methods that can be called via the SbOnce() system. -#### Definition #### +#### Definition ``` typedef void(* SbOnceInitRoutine) (void) ``` -## Functions ## +## Functions -### SbOnce ### +### SbOnce Thread-safely runs `init_routine` only once. @@ -50,7 +50,7 @@ Thread-safely runs `init_routine` only once. * If `once_control` or `init_routine` is invalid, the function returns `false`. -#### Declaration #### +#### Declaration ``` bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) diff --git a/cobalt/site/docs/reference/starboard/modules/13/player.md b/cobalt/site/docs/reference/starboard/modules/13/player.md index 3fd955dfe85c..807597d4be20 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/player.md +++ b/cobalt/site/docs/reference/starboard/modules/13/player.md @@ -1,45 +1,45 @@ ---- -layout: doc -title: "Starboard Module Reference: player.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `player.h` Defines an interface for controlling playback of media elementary streams. -## Macros ## +## Macros -### SB_PLAYER_INITIAL_TICKET ### +### SB_PLAYER_INITIAL_TICKET The value of the initial ticket held by the player before the first seek. The player will use this ticket value to make the first call to SbPlayerStatusFunc with kSbPlayerStateInitialized. -### SB_PLAYER_NO_DURATION ### +### SB_PLAYER_NO_DURATION The value to pass into SbPlayerCreate's `duration_pts` argument for cases where the duration is unknown, such as for live streams. -### kSbPlayerInvalid ### +### kSbPlayerInvalid Well-defined value for an invalid player. -## Enums ## +## Enums -### SbPlayerDecoderState ### +### SbPlayerDecoderState An indicator of whether the decoder can accept more samples. -#### Values #### +#### Values * `kSbPlayerDecoderStateNeedsData` The decoder is asking for one more sample. -### SbPlayerSampleSideDataType ### +### SbPlayerSampleSideDataType Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side data may come from multiple sources. -#### Values #### +#### Values * `kMatroskaBlockAdditional` @@ -48,11 +48,11 @@ data may come from multiple sources. . The first 8 bytes of the data contains the value of BlockAddID in big endian format, followed by the content of BlockAdditional. -### SbPlayerState ### +### SbPlayerState An indicator of the general playback state. -#### Values #### +#### Values * `kSbPlayerStateInitialized` @@ -76,31 +76,31 @@ An indicator of the general playback state. The player has been destroyed, and will send no more callbacks. -## Typedefs ## +## Typedefs -### SbPlayer ### +### SbPlayer An opaque handle to an implementation-private structure representing a player. -#### Definition #### +#### Definition ``` typedef struct SbPlayerPrivate* SbPlayer ``` -### SbPlayerDeallocateSampleFunc ### +### SbPlayerDeallocateSampleFunc Callback to free the given sample buffer data. When more than one buffer are sent in SbPlayerWriteSample(), the implementation only has to call this callback with `sample_buffer` points to the the first buffer. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) ``` -### SbPlayerDecoderStatusFunc ### +### SbPlayerDecoderStatusFunc Callback for decoder status updates, called in response to a call to SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called @@ -114,45 +114,45 @@ player will make at most one call to SbPlayerWriteSample() or SbPlayerWriteEndOfStream(). The player implementation should update the decoder status again after such call to notify its user to continue writing more frames. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) ``` -### SbPlayerErrorFunc ### +### SbPlayerErrorFunc Callback for player errors, that may set a `message`. `error`: indicates the error code. `message`: provides specific informative diagnostic message about the error condition encountered. It is ok for the message to be an empty string or NULL if no information is available. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) ``` -### SbPlayerStatusFunc ### +### SbPlayerStatusFunc Callback for player status updates. These callbacks will happen on a different thread than the calling thread, and it is not valid to call SbPlayer functions from within this callback. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) ``` -## Structs ## +## Structs -### SbPlayerCreationParam ### +### SbPlayerCreationParam The playback related parameters to pass into SbPlayerCreate() and SbPlayerGetPreferredOutputMode(). -#### Members #### +#### Members * `SbDrmSystem drm_system` @@ -178,11 +178,11 @@ SbPlayerGetPreferredOutputMode(). should be made available for the application to pull via calls to SbPlayerGetCurrentFrame(). -### SbPlayerInfo2 ### +### SbPlayerInfo2 Information about the current media playback state. -#### Members #### +#### Members * `SbTime current_media_timestamp` @@ -229,11 +229,11 @@ Information about the current media playback state. faster than normal speed. When it is less than one, the video is played in a slower than normal speed. Negative speeds are not supported. -### SbPlayerSampleInfo ### +### SbPlayerSampleInfo Information about the samples to be written into SbPlayerWriteSamples(). -#### Members #### +#### Members * `SbMediaType type` * `const void * buffer` @@ -266,12 +266,12 @@ Information about the samples to be written into SbPlayerWriteSamples(). The DRM system related info for the media sample. This value is required for encrypted samples. Otherwise, it must be `NULL`. -### SbPlayerSampleSideData ### +### SbPlayerSampleSideData Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data coming from multiple sources. -#### Members #### +#### Members * `SbPlayerSampleSideDataType type` * `const uint8_t * data` @@ -282,9 +282,9 @@ coming from multiple sources. The size of the data pointed by `data`, in bytes. -## Functions ## +## Functions -### SbPlayerDestroy ### +### SbPlayerDestroy Destroys `player`, freeing all associated resources. @@ -299,13 +299,13 @@ Destroys `player`, freeing all associated resources. SbPlayerDestroy has been called on that player. `player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` void SbPlayerDestroy(SbPlayer player) ``` -### SbPlayerGetCurrentFrame ### +### SbPlayerGetCurrentFrame Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, it will return a SbDecodeTarget representing the current frame to be rasterized. @@ -317,13 +317,13 @@ kSbDecodeTargetInvalid is returned. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` -### SbPlayerGetMaximumNumberOfSamplesPerWrite ### +### 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 @@ -337,13 +337,13 @@ to retain from those structures. of sample for which the number is retrieved. See the `SbMediaType` enum in media.h. -#### Declaration #### +#### Declaration ``` int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) ``` -### SbPlayerGetPreferredOutputMode ### +### SbPlayerGetPreferredOutputMode Returns the preferred output mode of the implementation when a video described by `creation_param` is played. It is assumed that it is okay to call @@ -361,23 +361,23 @@ whether the video described by `creation_param` can be played on the platform, and the implementation should try its best effort to return a valid output mode. `creation_param` must not be NULL. -#### Declaration #### +#### Declaration ``` SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) ``` -### SbPlayerIsValid ### +### SbPlayerIsValid Returns whether the given player handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbPlayerIsValid(SbPlayer player) ``` -### SbPlayerSetBounds ### +### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do not take effect until the next graphics frame buffer swap. The default bounds @@ -398,13 +398,13 @@ smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. `y`: The y-coordinate of the upper-left corner of the player. `width`: The width of the player, in pixels. `height`: The height of the player, in pixels. -#### Declaration #### +#### Declaration ``` void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) ``` -### SbPlayerSetPlaybackRate ### +### SbPlayerSetPlaybackRate Set the playback rate of the `player`. `rate` is default to 1.0 which indicates the playback is at its original speed. A `rate` greater than one will make the @@ -419,13 +419,13 @@ to support. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) ``` -### SbPlayerSetVolume ### +### SbPlayerSetVolume Sets the player's volume. @@ -434,13 +434,13 @@ Sets the player's volume. `0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be muted, and a value of `1.0` means that it should be played at full volume. -#### Declaration #### +#### Declaration ``` void SbPlayerSetVolume(SbPlayer player, double volume) ``` -### SbPlayerWriteEndOfStream ### +### SbPlayerWriteEndOfStream Writes a marker to `player`'s input stream of `stream_type` indicating that there are no more samples for that media type for the remainder of this media @@ -450,13 +450,13 @@ contents, after a call to SbPlayerSeek. `player`: The player to which the marker is written. `stream_type`: The type of stream for which the marker is written. -#### Declaration #### +#### Declaration ``` void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ``` -### SbPlayerWriteSample2 ### +### SbPlayerWriteSample2 `sample_type`: The type of sample being written. See the `SbMediaType` enum in media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with @@ -468,7 +468,7 @@ be copied if its content will be used after SbPlayerWriteSamples() returns. `sample_infos`. It has to be at least one, and less than the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). -#### Declaration #### +#### Declaration ``` void SbPlayerWriteSample2(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) diff --git a/cobalt/site/docs/reference/starboard/modules/13/socket.md b/cobalt/site/docs/reference/starboard/modules/13/socket.md index 9e0f81b98334..744c04e3847d 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/13/socket.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket.h` Defines Starboard socket I/O functions. Starboard supports IPv4 and IPv6, TCP and UDP, server and client sockets. Some platforms may not support IPv6, some @@ -18,19 +18,19 @@ the connection, thus requiring use of either an SbSocketWaiter or spin-polling. TODO: For platforms that do not support sockets at all, they must support at least a high-level HTTP client API (to be defined later). -## Macros ## +## Macros -### kSbSocketInvalid ### +### kSbSocketInvalid Well-defined value for an invalid socket handle. -## Enums ## +## Enums -### SbSocketAddressType ### +### SbSocketAddressType All possible address types. -#### Values #### +#### Values * `kSbSocketAddressTypeIpv4` @@ -39,13 +39,13 @@ All possible address types. An IPv6 address, which uses 16 entries of the address buffer. -### SbSocketError ### +### SbSocketError Enumeration of all Starboard socket operation results. Despite the enum name, note that the value actually describes the outcome of an operation, which is not always an error. -#### Values #### +#### Values * `kSbSocketOk` @@ -63,11 +63,11 @@ always an error. The operation failed for some other reason not specified above. -### SbSocketProtocol ### +### SbSocketProtocol All possible IP socket types. -#### Values #### +#### Values * `kSbSocketProtocolTcp` @@ -77,11 +77,11 @@ All possible IP socket types. The UDP/IP protocol, an unreliable, connectionless, discrete packet (datagram) protocol. -### SbSocketResolveFilter ### +### SbSocketResolveFilter Bits that can be set when calling SbSocketResolve to filter the results. -#### Values #### +#### Values * `kSbSocketResolveFilterNone` @@ -93,25 +93,25 @@ Bits that can be set when calling SbSocketResolve to filter the results. Include Ipv6 addresses. -## Typedefs ## +## Typedefs -### SbSocket ### +### SbSocket A handle to a socket. -#### Definition #### +#### Definition ``` typedef SbSocketPrivate* SbSocket ``` -## Structs ## +## Structs -### SbSocketAddress ### +### SbSocketAddress A representation of any possible supported address type. -#### Members #### +#### Members * `uint8_t address` @@ -126,11 +126,11 @@ A representation of any possible supported address type. The port component of this socket address. If not specified, it will be zero, which is officially undefined. -### SbSocketResolution ### +### SbSocketResolution The result of a host name resolution. -#### Members #### +#### Members * `SbSocketAddress* addresses` @@ -139,9 +139,9 @@ The result of a host name resolution. The length of the `addresses` array. -## Functions ## +## Functions -### SbSocketAccept ### +### SbSocketAccept Accepts a pending connection on `socket` and returns a new SbSocket representing that connection. This function sets the error on `socket` and returns @@ -149,13 +149,13 @@ that connection. This function sets the error on `socket` and returns `socket`: The SbSocket that is accepting a pending connection. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketAccept(SbSocket socket) ``` -### SbSocketBind ### +### SbSocketBind Binds `socket` to a specific local interface and port specified by `local_address`. This function sets and returns the socket error if it is unable @@ -170,24 +170,24 @@ local address to which the socket is to be bound. This value must not be `NULL`. * Setting the IP address to `0.0.0.0` means that the socket should be bound to all interfaces. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address) ``` -### SbSocketClearLastError ### +### SbSocketClearLastError Clears the last error set on `socket`. The return value indicates whether the socket error was cleared. -#### Declaration #### +#### Declaration ``` bool SbSocketClearLastError(SbSocket socket) ``` -### SbSocketConnect ### +### SbSocketConnect Opens a connection of `socket`'s type to the host and port specified by `address`. This function sets and returns the socket error if it is unable to @@ -197,13 +197,13 @@ successfully.) `socket`: The type of connection that should be opened. `address`: The host and port to which the socket should connect. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketCreate ### +### SbSocketCreate Creates a new non-blocking socket for protocol `protocol` using address family `address_type`. @@ -216,13 +216,13 @@ Creates a new non-blocking socket for protocol `protocol` using address family `address_type`: The type of IP address to use for the socket. `protocol`: The protocol to use for the socket. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol) ``` -### SbSocketDestroy ### +### SbSocketDestroy Destroys the `socket` by flushing it, closing any connection that may be active on it, and reclaiming any resources associated with it, including any @@ -234,25 +234,25 @@ more. `socket`: The SbSocket to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketDestroy(SbSocket socket) ``` -### SbSocketFreeResolution ### +### SbSocketFreeResolution Frees a resolution allocated by SbSocketResolve. `resolution`: The resolution to be freed. -#### Declaration #### +#### Declaration ``` void SbSocketFreeResolution(SbSocketResolution *resolution) ``` -### SbSocketGetInterfaceAddress ### +### SbSocketGetInterfaceAddress Gets the source address and the netmask that would be used to connect to the destination. The netmask parameter is optional, and only populated if a non-NULL @@ -288,26 +288,26 @@ this output variable. `out_netmask`: This parameter is optional. If a non-NULL value is passed in, this function places the netmask associated with the source address in this output variable. -#### Declaration #### +#### Declaration ``` bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask) ``` -### SbSocketGetLastError ### +### SbSocketGetLastError Returns the last error set on `socket`. If `socket` is not valid, this function returns `kSbSocketErrorFailed`. `socket`: The SbSocket that the last error is returned for. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketGetLastError(SbSocket socket) ``` -### SbSocketGetLocalAddress ### +### SbSocketGetLocalAddress Gets the address that this socket is bound to locally, if the socket is connected. The return value indicates whether the address was retrieved @@ -316,59 +316,59 @@ successfully. `socket`: The SbSocket for which the local address is retrieved. `out_address`: The SbSocket's local address. -#### Declaration #### +#### Declaration ``` bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address) ``` -### SbSocketIsConnected ### +### SbSocketIsConnected Indicates whether `socket` is connected to anything. Invalid sockets are not connected. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnected(SbSocket socket) ``` -### SbSocketIsConnectedAndIdle ### +### SbSocketIsConnectedAndIdle Returns whether `socket` is connected to anything, and, if so, whether it is receiving any data. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnectedAndIdle(SbSocket socket) ``` -### SbSocketIsIpv6Supported ### +### SbSocketIsIpv6Supported Returns whether IPV6 is supported on the current platform. -#### Declaration #### +#### Declaration ``` bool SbSocketIsIpv6Supported() ``` -### SbSocketIsValid ### +### SbSocketIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketIsValid(SbSocket socket) ``` -### SbSocketJoinMulticastGroup ### +### SbSocketJoinMulticastGroup Joins `socket` to an IP multicast group identified by `address`. The equivalent of IP_ADD_MEMBERSHIP. The return value indicates whether the socket was joined @@ -377,13 +377,13 @@ to the group successfully. `socket`: The SbSocket to be joined to the IP multicast group. `address`: The location of the IP multicast group. -#### Declaration #### +#### Declaration ``` bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketListen ### +### SbSocketListen Causes `socket` to listen on the local address that `socket` was previously bound to by SbSocketBind. This function sets and returns the socket error if it @@ -392,13 +392,13 @@ connection successfully.) `socket`: The SbSocket on which the function operates. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketListen(SbSocket socket) ``` -### SbSocketReceiveFrom ### +### SbSocketReceiveFrom Reads up to `data_size` bytes from `socket` into `out_data` and places the source address of the packet in `out_source` if out_source is not NULL. Returns @@ -420,13 +420,13 @@ the address is unnecessary, but allowed. the socket. Must not be NULL. `data_size`: The number of bytes to read. `out_source`: The source address of the packet. -#### Declaration #### +#### Declaration ``` int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source) ``` -### SbSocketResolve ### +### SbSocketResolve Synchronously resolves `hostname` into the returned SbSocketResolution , which must be freed with SbSocketFreeResolution. The function returns `NULL` if it is @@ -438,13 +438,13 @@ not specify an IP address family filter, all address families are included. However, if one IP address family filter is specified, only that address family is included. The function ignores unrecognized filter bits. -#### Declaration #### +#### Declaration ``` SbSocketResolution* SbSocketResolve(const char *hostname, int filters) ``` -### SbSocketSendTo ### +### SbSocketSendTo Writes up to `data_size` bytes of `data` to `destination` via `socket`. Returns the number of bytes written, or a negative number if there is an error, in which @@ -466,13 +466,13 @@ to multiple sources from a single UDP server socket. TCP has two endpoints connected persistently, so setting `destination` when sending to a TCP socket will cause an error. -#### Declaration #### +#### Declaration ``` int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination) ``` -### SbSocketSetBroadcast ### +### SbSocketSetBroadcast Sets the `SO_BROADCAST`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -483,13 +483,13 @@ the broadcast address. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetBroadcast(SbSocket socket, bool value) ``` -### SbSocketSetReceiveBufferSize ### +### SbSocketSetReceiveBufferSize Sets the `SO_RCVBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -497,13 +497,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetReuseAddress ### +### SbSocketSetReuseAddress Sets the `SO_REUSEADDR`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -514,13 +514,13 @@ to it. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReuseAddress(SbSocket socket, bool value) ``` -### SbSocketSetSendBufferSize ### +### SbSocketSetSendBufferSize Sets the `SO_SNDBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -528,13 +528,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetTcpKeepAlive ### +### SbSocketSetTcpKeepAlive Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -545,13 +545,13 @@ 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`. -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) ``` -### SbSocketSetTcpNoDelay ### +### SbSocketSetTcpNoDelay Sets the `TCP_NODELAY`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -564,13 +564,13 @@ behavior. `socket`: The SbSocket for which the option is set. `value`: Indicates whether the Nagle algorithm should be disabled (`value`=`true`). -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpNoDelay(SbSocket socket, bool value) ``` -### SbSocketSetTcpWindowScaling ### +### SbSocketSetTcpWindowScaling Sets the `SO_WINSCALE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -578,7 +578,7 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: The value for the option. -#### Declaration #### +#### Declaration ``` 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 738fafb11dec..146938cbebd9 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/13/socket_waiter.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket_waiter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket_waiter.h` Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to: @@ -26,19 +26,19 @@ thread, it needs to call SbSocketWaiterWakeUp() on the SbSocketWaiter after queuing the work item, or the SbSocketWaiter is not otherwise guaranteed to wake up. -## Macros ## +## Macros -### kSbSocketWaiterInvalid ### +### kSbSocketWaiterInvalid Well-defined value for an invalid socket watcher handle. -## Enums ## +## Enums -### SbSocketWaiterInterest ### +### SbSocketWaiterInterest All the interests that a socket may register for on a waiter. -#### Values #### +#### Values * `kSbSocketWaiterInterestNone` @@ -50,11 +50,11 @@ All the interests that a socket may register for on a waiter. An interest in or readiness to write to a socket without blocking. -### SbSocketWaiterResult ### +### SbSocketWaiterResult Possible reasons why a call to SbSocketWaiterWaitTimed returned. -#### Values #### +#### Values * `kSbSocketWaiterResultInvalid` @@ -66,31 +66,31 @@ Possible reasons why a call to SbSocketWaiterWaitTimed returned. The wait stopped because a call to SbSocketWaiterWakeUp was consumed. -## Typedefs ## +## Typedefs -### SbSocketWaiter ### +### SbSocketWaiter A handle to a socket waiter. -#### Definition #### +#### Definition ``` typedef SbSocketWaiterPrivate* SbSocketWaiter ``` -### SbSocketWaiterCallback ### +### SbSocketWaiterCallback Function pointer for socket waiter callbacks. -#### Definition #### +#### Definition ``` typedef void(* SbSocketWaiterCallback) (SbSocketWaiter waiter, SbSocket socket, void *context, int ready_interests) ``` -## Functions ## +## Functions -### SbSocketWaiterAdd ### +### SbSocketWaiterAdd Adds a new socket to be waited on by the `waiter` with a bitfield of `interests`. This function should only be called on the thread that waits on @@ -120,25 +120,25 @@ socket: `callback`, even if not all registered `interests` became ready, which allows for adding it again in the `callback`. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterAdd(SbSocketWaiter waiter, SbSocket socket, void *context, SbSocketWaiterCallback callback, int interests, bool persistent) ``` -### SbSocketWaiterCreate ### +### SbSocketWaiterCreate The results of two threads waiting on the same waiter is undefined and will not work. Except for the SbSocketWaiterWakeUp() function, SbSocketWaiters are not thread-safe and don't expect to be modified concurrently. -#### Declaration #### +#### Declaration ``` SbSocketWaiter SbSocketWaiterCreate() ``` -### SbSocketWaiterDestroy ### +### SbSocketWaiterDestroy Destroys `waiter` and removes all sockets still registered by way of SbSocketWaiterAdd. This function may be called on any thread as long as there is @@ -146,23 +146,23 @@ no risk of concurrent access to the waiter. `waiter`: The SbSocketWaiter to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterDestroy(SbSocketWaiter waiter) ``` -### SbSocketWaiterIsValid ### +### SbSocketWaiterIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketWaiterIsValid(SbSocketWaiter watcher) ``` -### SbSocketWaiterRemove ### +### SbSocketWaiterRemove Removes a socket, previously added with SbSocketWaiterAdd(), from a waiter. This function should only be called on the thread that waits on this waiter. @@ -174,26 +174,26 @@ returns `true`. `waiter`: The waiter from which the socket is removed. `socket`: The socket to remove from the waiter. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket) ``` -### SbSocketWaiterWait ### +### SbSocketWaiterWait Waits on all registered sockets, calling the registered callbacks if and when the corresponding sockets become ready for an interested operation. This version exits only after SbSocketWaiterWakeUp() is called. This function should only be called on the thread that waits on this waiter. -#### Declaration #### +#### Declaration ``` void SbSocketWaiterWait(SbSocketWaiter waiter) ``` -### SbSocketWaiterWaitTimed ### +### SbSocketWaiterWaitTimed Behaves similarly to SbSocketWaiterWait(), but this function also causes `waiter` to exit on its own after at least `duration` has passed if @@ -207,13 +207,13 @@ 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 #### +#### Declaration ``` SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) ``` -### SbSocketWaiterWakeUp ### +### SbSocketWaiterWakeUp Wakes up `waiter` once. This is the only thread-safe waiter function. It can can be called from a SbSocketWaiterCallback to wake up its own waiter, and it can @@ -230,7 +230,7 @@ next 7 times they are called. `waiter`: The socket waiter to be woken up. -#### Declaration #### +#### Declaration ``` 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 e46a2cac70cd..ea4ad46b3f87 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/13/speech_synthesis.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: speech_synthesis.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `speech_synthesis.h` A basic text-to-speech API intended to be used for audio accessibility. @@ -11,29 +11,29 @@ non-visual navigation of the application. Note that these functions do not have to be thread-safe. They must only be called from a single application thread. -## Functions ## +## Functions -### SbSpeechSynthesisCancel ### +### SbSpeechSynthesisCancel Cancels all speaking and queued speech synthesis audio. Must return immediately. -#### Declaration #### +#### Declaration ``` void SbSpeechSynthesisCancel() ``` -### SbSpeechSynthesisIsSupported ### +### SbSpeechSynthesisIsSupported Returns whether the platform supports speech synthesis -#### Declaration #### +#### Declaration ``` bool SbSpeechSynthesisIsSupported() ``` -### SbSpeechSynthesisSpeak ### +### SbSpeechSynthesisSpeak Enqueues `text`, a UTF-8 string, to be spoken. Returns immediately. @@ -44,7 +44,7 @@ If audio from previous SbSpeechSynthesisSpeak() invocations is still processing, the current speaking should continue and this new text should be queued to play when the previous utterances are complete. -#### Declaration #### +#### Declaration ``` 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 c98207b67d98..b486ac84c525 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/13/storage.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: storage.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `storage.h` Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and retrieval API that is intended for robust long-term, per-user storage. Some @@ -15,27 +15,27 @@ record for a user will result in undefined behavior. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbStorageInvalidRecord ### +### kSbStorageInvalidRecord Well-defined value for an invalid storage record handle. -## Typedefs ## +## Typedefs -### SbStorageRecord ### +### SbStorageRecord A handle to an open storage record. -#### Definition #### +#### Definition ``` typedef SbStorageRecordPrivate* SbStorageRecord ``` -## Functions ## +## Functions -### SbStorageCloseRecord ### +### SbStorageCloseRecord Closes `record`, synchronously ensuring that all written data is flushed. This function performs blocking I/O on the calling thread. @@ -47,13 +47,13 @@ deleted (or, even better, untouched). `record`: The storage record to close. `record` is invalid after this point, and subsequent calls referring to `record` will fail. -#### Declaration #### +#### Declaration ``` bool SbStorageCloseRecord(SbStorageRecord record) ``` -### SbStorageDeleteRecord ### +### SbStorageDeleteRecord Deletes the `SbStorageRecord` for `user` named `name`. The return value indicates whether the record existed and was successfully deleted. If the record @@ -68,36 +68,36 @@ function performs blocking I/O on the calling thread. `user`: The user for whom the record will be deleted. `name`: The filesystem- safe name of the record to open. -#### Declaration #### +#### Declaration ``` bool SbStorageDeleteRecord(SbUser user, const char *name) ``` -### SbStorageGetRecordSize ### +### SbStorageGetRecordSize Returns the size of `record`, or `-1` if there is an error. This function performs blocking I/O on the calling thread. `record`: The record to retrieve the size of. -#### Declaration #### +#### Declaration ``` int64_t SbStorageGetRecordSize(SbStorageRecord record) ``` -### SbStorageIsValidRecord ### +### SbStorageIsValidRecord Returns whether the given storage record handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbStorageIsValidRecord(SbStorageRecord record) ``` -### SbStorageOpenRecord ### +### SbStorageOpenRecord Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on the calling thread until the open is completed. If `user` is not a valid @@ -111,13 +111,13 @@ would have been saved with the previous version of SbStorageOpenRecord. `user`: The user for which the storage record will be opened. `name`: The filesystem-safe name of the record to open. -#### Declaration #### +#### Declaration ``` SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) ``` -### SbStorageReadRecord ### +### SbStorageReadRecord Reads up to `data_size` bytes from `record`, starting at the beginning of the record. The function returns the actual number of bytes read, which must be <= @@ -128,13 +128,13 @@ the calling thread until the entire record is read or an error is encountered. `record`: The record to be read. `out_data`: The data read from the record. `data_size`: The amount of data, in bytes, to read. -#### Declaration #### +#### Declaration ``` int64_t SbStorageReadRecord(SbStorageRecord record, char *out_data, int64_t data_size) ``` -### SbStorageWriteRecord ### +### SbStorageWriteRecord Replaces the data in `record` with `data_size` bytes from `data`. This function always deletes any previous data in that record. The return value indicates @@ -151,7 +151,7 @@ after a short time, even if there is an unexpected process termination before `record`: The record to be written to. `data`: The data to write to the record. `data_size`: The amount of `data`, in bytes, to write to the record. -#### Declaration #### +#### Declaration ``` 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 95790d4acff4..5e9796880177 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/string.md +++ b/cobalt/site/docs/reference/starboard/modules/13/string.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: string.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `string.h` Defines functions for interacting with c-style strings. -## Functions ## +## Functions -### SbStringCompareNoCase ### +### SbStringCompareNoCase Compares two strings, ignoring differences in case. The return value is: @@ -21,13 +21,13 @@ This function is meant to be a drop-in replacement for `strcasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCase(const char *string1, const char *string2) ``` -### SbStringCompareNoCaseN ### +### SbStringCompareNoCaseN Compares the first `count` characters of two strings, ignoring differences in case. The return value is: @@ -43,13 +43,13 @@ This function is meant to be a drop-in replacement for `strncasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. `count`: The number of characters to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) ``` -### SbStringDuplicate ### +### SbStringDuplicate Copies `source` into a buffer that is allocated by this function and that can be freed with SbMemoryDeallocate. This function is meant to be a drop-in @@ -57,13 +57,13 @@ replacement for `strdup`. `source`: The string to be copied. -#### Declaration #### +#### Declaration ``` char* SbStringDuplicate(const char *source) ``` -### SbStringFormat ### +### SbStringFormat Produces a string formatted with `format` and `arguments`, placing as much of the result that will fit into `out_buffer`. The return value specifies the @@ -76,13 +76,13 @@ This function is meant to be a drop-in replacement for `vsnprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatF ### +### SbStringFormatF An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This function is meant to be a drop-in replacement for `snprintf`. @@ -91,13 +91,13 @@ function is meant to be a drop-in replacement for `snprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatUnsafeF ### +### SbStringFormatUnsafeF An inline wrapper of SbStringFormat that is meant to be a drop-in replacement for the unsafe but commonly used `sprintf`. @@ -106,13 +106,13 @@ for the unsafe but commonly used `sprintf`. string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 ``` -### SbStringFormatWide ### +### SbStringFormatWide This function is identical to SbStringFormat, but is for wide characters. It is meant to be a drop-in replacement for `vswprintf`. @@ -121,13 +121,13 @@ meant to be a drop-in replacement for `vswprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF ### +### SbStringFormatWideF An inline wrapper of SbStringFormatWide that converts from ellipsis to `va_args`. @@ -136,13 +136,13 @@ An inline wrapper of SbStringFormatWide that converts from ellipsis to The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) ``` -### SbStringScan ### +### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The return value specifies the number of successfully matched items, which may be @@ -154,20 +154,20 @@ This function is meant to be a drop-in replacement for `vsscanf`. for in `buffer`. `arguments`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` int SbStringScan(const char *buffer, const char *pattern, va_list arguments) ``` -### SbStringScanF ### +### SbStringScanF An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` 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 b02dc010d811..d3052d1ccde1 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/system.md +++ b/cobalt/site/docs/reference/starboard/modules/13/system.md @@ -1,21 +1,21 @@ ---- -layout: doc -title: "Starboard Module Reference: system.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `system.h` Defines a broad set of APIs that allow the client application to query build and runtime properties of the enclosing system. -## Enums ## +## Enums -### SbSystemCapabilityId ### +### SbSystemCapabilityId Runtime capabilities are boolean properties of a platform that can't be determined at compile-time. They may vary from device to device, but they will not change over the course of a single execution. They often specify particular behavior of other APIs within the bounds of their operating range. -#### Values #### +#### Values * `kSbSystemCapabilityReversedEnterAndBack` @@ -26,11 +26,11 @@ behavior of other APIs within the bounds of their operating range. only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call. -### SbSystemConnectionType ### +### SbSystemConnectionType Enumeration of network connection types. -#### Values #### +#### Values * `kSbSystemConnectionTypeWired` @@ -42,11 +42,11 @@ Enumeration of network connection types. The system connection type is unknown. -### SbSystemDeviceType ### +### SbSystemDeviceType Enumeration of device types. -#### Values #### +#### Values * `kSbSystemDeviceTypeBlueRayDiskPlayer` @@ -76,11 +76,11 @@ Enumeration of device types. Unknown device. -### SbSystemPathId ### +### SbSystemPathId Enumeration of special paths that the platform can define. -#### Values #### +#### Values * `kSbSystemPathContentDirectory` @@ -119,22 +119,22 @@ Enumeration of special paths that the platform can define. for storing the updates. See starboard/doc/evergreen/cobalt_evergreen_overview.md -### SbSystemPlatformErrorResponse ### +### SbSystemPlatformErrorResponse Possible responses for `SbSystemPlatformErrorCallback`. -#### Values #### +#### Values * `kSbSystemPlatformErrorResponsePositive` * `kSbSystemPlatformErrorResponseNegative` * `kSbSystemPlatformErrorResponseCancel` -### SbSystemPlatformErrorType ### +### SbSystemPlatformErrorType Enumeration of possible values for the `type` parameter passed to the `SbSystemRaisePlatformError` function. -#### Values #### +#### Values * `kSbSystemPlatformErrorTypeConnectionError` @@ -143,12 +143,12 @@ Enumeration of possible values for the `type` parameter passed to the `kSbSystemPlatformErrorResponsePositive` then the request should be retried, otherwise the app should be stopped. -### SbSystemPropertyId ### +### SbSystemPropertyId System properties that can be queried for. Many of these are used in User-Agent string generation. -#### Values #### +#### Values * `kSbSystemPropertyCertificationScope` @@ -196,9 +196,9 @@ string generation. A field that, if available, is appended to the user agent -## Typedefs ## +## Typedefs -### SbSystemComparator ### +### SbSystemComparator Pointer to a function to compare two items. The return value uses standard `*cmp` semantics: @@ -211,23 +211,23 @@ Pointer to a function to compare two items. The return value uses standard `a`: The first value to compare. `b`: The second value to compare. -#### Definition #### +#### Definition ``` typedef int(* SbSystemComparator) (const void *a, const void *b) ``` -### SbSystemError ### +### SbSystemError A type that can represent a system error code across all Starboard platforms. -#### Definition #### +#### Definition ``` typedef int SbSystemError ``` -### SbSystemPlatformErrorCallback ### +### SbSystemPlatformErrorCallback Type of callback function that may be called in response to an error notification from `SbSystemRaisePlatformError`. `response` is a code to indicate @@ -235,56 +235,56 @@ the user's response, e.g. if the platform raised a dialog to notify the user of the error. `user_data` is the opaque pointer that was passed to the call to `SbSystemRaisePlatformError`. -#### Definition #### +#### Definition ``` typedef void(* SbSystemPlatformErrorCallback) (SbSystemPlatformErrorResponse response, void *user_data) ``` -## Functions ## +## Functions -### SbSystemBreakIntoDebugger ### +### SbSystemBreakIntoDebugger Breaks the current program into the debugger, if a debugger is attached. If a debugger is not attached, this function aborts the program. -#### Declaration #### +#### Declaration ``` SB_NORETURN void SbSystemBreakIntoDebugger() ``` -### SbSystemClearLastError ### +### SbSystemClearLastError Clears the last error set by a Starboard call in the current thread. -#### Declaration #### +#### Declaration ``` void SbSystemClearLastError() ``` -### SbSystemGetConnectionType ### +### SbSystemGetConnectionType Returns the device's current network connection type. -#### Declaration #### +#### Declaration ``` SbSystemConnectionType SbSystemGetConnectionType() ``` -### SbSystemGetDeviceType ### +### SbSystemGetDeviceType Returns the type of the device. -#### Declaration #### +#### Declaration ``` SbSystemDeviceType SbSystemGetDeviceType() ``` -### SbSystemGetErrorString ### +### SbSystemGetErrorString Generates a human-readable string for an error. The return value specifies the total desired length of the string. @@ -293,13 +293,13 @@ total desired length of the string. The generated string. This value may be null, and it is always terminated with a null byte. `string_length`: The maximum length of the error string. -#### Declaration #### +#### Declaration ``` int SbSystemGetErrorString(SbSystemError error, char *out_string, int string_length) ``` -### SbSystemGetExtension ### +### SbSystemGetExtension Returns pointer to a constant global struct implementing the extension named `name`, if it is implemented. Otherwise return NULL. The `name` string must not @@ -321,25 +321,25 @@ application may only get the extension once, meaning updated values would be ignored. As the version of extensions are incremented, fields may be added to the end of the struct, but never removed (only deprecated). -#### Declaration #### +#### Declaration ``` const void* SbSystemGetExtension(const char *name) ``` -### SbSystemGetLastError ### +### SbSystemGetLastError Gets the last platform-specific error code produced by any Starboard call in the current thread for diagnostic purposes. Semantic reactions to Starboard function call results should be modeled explicitly. -#### Declaration #### +#### Declaration ``` SbSystemError SbSystemGetLastError() ``` -### SbSystemGetLocaleId ### +### SbSystemGetLocaleId Gets the system's current POSIX-style Locale ID. The locale represents the location, language, and cultural conventions that the system wants to use, which @@ -356,25 +356,25 @@ RFC 5646 describes BCP 47 language codes: [https://tools.ietf.org/html/bcp47](ht For more information than you probably want about POSIX locales, see: [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html) -#### Declaration #### +#### Declaration ``` const char* SbSystemGetLocaleId() ``` -### SbSystemGetNumberOfProcessors ### +### SbSystemGetNumberOfProcessors Returns the number of processor cores available to this application. If the process is sandboxed to a subset of the physical cores, the function returns that sandboxed limit. -#### Declaration #### +#### Declaration ``` int SbSystemGetNumberOfProcessors() ``` -### SbSystemGetProperty ### +### SbSystemGetProperty Retrieves the platform-defined system property specified by `property_id` and places its value as a zero-terminated string into the user-allocated `out_value` @@ -395,13 +395,13 @@ returns `false` under any of the following conditions and, in any such case, defined system property specified by `property_id`. `value_length`: The length of the system property. -#### Declaration #### +#### Declaration ``` bool SbSystemGetProperty(SbSystemPropertyId property_id, char *out_value, int value_length) ``` -### SbSystemGetRandomData ### +### SbSystemGetRandomData A cryptographically secure random number generator that produces an arbitrary, non-negative number of `buffer_size` random, non-negative bytes. The generated @@ -410,24 +410,24 @@ number is placed in `out_buffer`. This function does not require manual seeding. `out_buffer`: A pointer for the generated random number. This value must not be null. `buffer_size`: The size of the random number, in bytes. -#### Declaration #### +#### Declaration ``` void SbSystemGetRandomData(void *out_buffer, int buffer_size) ``` -### SbSystemGetRandomUInt64 ### +### SbSystemGetRandomUInt64 A cryptographically secure random number generator that gets 64 random bits and returns them as an `uint64_t`. This function does not require manual seeding. -#### Declaration #### +#### Declaration ``` uint64_t SbSystemGetRandomUInt64() ``` -### SbSystemGetStack ### +### SbSystemGetStack Places up to `stack_size` instruction pointer addresses of the current execution stack into `out_stack`. The return value specifies the number of entries added. @@ -444,62 +444,62 @@ what it means to be async-signal-safe on POSIX: [http://pubs.opengroup.org/onlin `stack_size`: The maximum number of instruction pointer addresses to be placed into `out_stack` from the current execution stack. -#### Declaration #### +#### Declaration ``` int SbSystemGetStack(void **out_stack, int stack_size) ``` -### SbSystemGetTotalCPUMemory ### +### SbSystemGetTotalCPUMemory Returns the total CPU memory (in bytes) potentially available to this application. If the process is sandboxed to a maximum allowable limit, the function returns the lesser of the physical and sandbox limits. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalCPUMemory() ``` -### SbSystemGetTotalGPUMemory ### +### SbSystemGetTotalGPUMemory Returns the total GPU memory (in bytes) available for use by this application. This function may only be called the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalGPUMemory() ``` -### SbSystemGetUsedCPUMemory ### +### SbSystemGetUsedCPUMemory Returns the total physical CPU memory (in bytes) used by this application. This value should always be less than (or, in particularly exciting situations, equal to) SbSystemGetTotalCPUMemory(). -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedCPUMemory() ``` -### SbSystemGetUsedGPUMemory ### +### SbSystemGetUsedGPUMemory Returns the current amount of GPU memory (in bytes) that is currently being used by this application. This function may only be called if the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedGPUMemory() ``` -### SbSystemHasCapability ### +### SbSystemHasCapability Returns whether the platform has the runtime capability specified by `capability_id`. Returns false for any unknown capabilities. This implementation @@ -507,48 +507,48 @@ must be thread-safe. `capability_id`: The runtime capability to check. -#### Declaration #### +#### Declaration ``` bool SbSystemHasCapability(SbSystemCapabilityId capability_id) ``` -### SbSystemHideSplashScreen ### +### SbSystemHideSplashScreen Hides the system splash screen on systems that support a splash screen that is displayed while the application is loading. This function may be called from any thread and must be idempotent. -#### Declaration #### +#### Declaration ``` void SbSystemHideSplashScreen() ``` -### SbSystemIsDebuggerAttached ### +### SbSystemIsDebuggerAttached Attempts to determine whether the current program is running inside or attached to a debugger. The function returns `false` if neither of those cases is true. -#### Declaration #### +#### Declaration ``` bool SbSystemIsDebuggerAttached() ``` -### SbSystemNetworkIsDisconnected ### +### SbSystemNetworkIsDisconnected Returns if the device is disconnected from network. "Disconnected" is chosen over connected because disconnection can be determined with more certainty than connection usually. -#### Declaration #### +#### Declaration ``` bool SbSystemNetworkIsDisconnected() ``` -### SbSystemRaisePlatformError ### +### SbSystemRaisePlatformError Cobalt calls this function to notify the platform that an error has occurred in the application that the platform may need to handle. The platform is expected @@ -570,13 +570,13 @@ caller know that the user has reacted to the error. `user_data`: An opaque pointer that the platform should pass as an argument to the callback function, if it is called. -#### Declaration #### +#### Declaration ``` bool SbSystemRaisePlatformError(SbSystemPlatformErrorType type, SbSystemPlatformErrorCallback callback, void *user_data) ``` -### SbSystemRequestBlur ### +### SbSystemRequestBlur Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to "unfocused application" in a @@ -586,13 +586,13 @@ This function eventually causes a `kSbEventTypeBlur` event to be dispatched to the application. Before the `kSbEventTypeBlur` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestBlur() ``` -### SbSystemRequestConceal ### +### SbSystemRequestConceal Requests that the application move into the Concealed state at the next convenient point. This should roughly correspond to "minimization" in a @@ -607,13 +607,13 @@ In the Concealed state, the application will be invisible, but probably still be running background tasks. The expectation is that an external system event will bring the application out of the Concealed state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestConceal() ``` -### SbSystemRequestFocus ### +### SbSystemRequestFocus Requests that the application move into the Started state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -624,13 +624,13 @@ This function eventually causes a `kSbEventTypeFocus` event to be dispatched to the application. Before `kSbEventTypeFocus` is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFocus() ``` -### SbSystemRequestFreeze ### +### SbSystemRequestFreeze Requests that the application move into the Frozen state at the next convenient point. @@ -643,13 +643,13 @@ In the Frozen state, the application will be resident, but probably not running. The expectation is that an external system event will bring the application out of the Frozen state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFreeze() ``` -### SbSystemRequestReveal ### +### SbSystemRequestReveal Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -660,13 +660,13 @@ This function eventually causes a `kSbEventTypeReveal` event to be dispatched to the application. Before the `kSbEventTypeReveal` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestReveal() ``` -### SbSystemRequestStop ### +### SbSystemRequestStop Requests that the application be terminated gracefully at the next convenient point. In the meantime, some work may continue to be done, and unrelated system @@ -677,13 +677,13 @@ it returns `error_level`, if that has any meaning on the current platform. `error_level`: An integer that serves as the return value for the process that is eventually terminated as a result of a call to this function. -#### Declaration #### +#### Declaration ``` void SbSystemRequestStop(int error_level) ``` -### SbSystemSignWithCertificationSecretKey ### +### SbSystemSignWithCertificationSecretKey Computes a HMAC-SHA256 digest of `message` into `digest` using the application's certification secret. The `message` and the `digest` pointers must not be NULL. @@ -693,13 +693,13 @@ greater), since 32-bytes will be written into it. Returns false in the case of an error, or if it is not implemented. In this case the contents of `digest` will be undefined. -#### Declaration #### +#### Declaration ``` bool SbSystemSignWithCertificationSecretKey(const uint8_t *message, size_t message_size_in_bytes, uint8_t *digest, size_t digest_size_in_bytes) ``` -### SbSystemSupportsResume ### +### SbSystemSupportsResume Returns false if the platform doesn't need resume after suspend support. In such case Cobalt will free up the resource it retains for resume after suspend. Note @@ -707,13 +707,13 @@ that if this function returns false, the Starboard implementation cannot send kSbEventTypeResume to the event handler. The return value of this function cannot change over the life time of the application. -#### Declaration #### +#### Declaration ``` bool SbSystemSupportsResume() ``` -### SbSystemSymbolize ### +### SbSystemSymbolize Looks up `address` as an instruction pointer and places up to (`buffer_size - 1`) characters of the symbol associated with it in `out_buffer`, which must not @@ -725,7 +725,7 @@ The return value indicates whether the function found a reasonable match for This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals. -#### Declaration #### +#### Declaration ``` 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 844047739b61..81a8697bbf96 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/13/thread.md @@ -1,35 +1,35 @@ ---- -layout: doc -title: "Starboard Module Reference: thread.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `thread.h` Defines functionality related to thread creation and cleanup. -## Macros ## +## Macros -### kSbThreadContextInvalid ### +### kSbThreadContextInvalid Well-defined value for an invalid thread context. -### kSbThreadInvalidId ### +### kSbThreadInvalidId Well-defined constant value to mean "no thread ID." -### kSbThreadLocalKeyInvalid ### +### kSbThreadLocalKeyInvalid Well-defined constant value to mean "no thread local key." -### kSbThreadNoAffinity ### +### kSbThreadNoAffinity Well-defined constant value to mean "no affinity." -### kSbThreadSamplerInvalid ### +### kSbThreadSamplerInvalid Well-defined value for an invalid thread sampler. -## Enums ## +## Enums -### SbThreadPriority ### +### SbThreadPriority A spectrum of thread priorities. Platforms map them appropriately to their own priority system. Note that scheduling is platform-specific, and what these @@ -39,7 +39,7 @@ In particular, several of these priority values can map to the same priority on a given platform. The only guarantee is that each lower priority should be treated less-than-or-equal-to a higher priority. -#### Values #### +#### Values * `kSbThreadPriorityLowest` @@ -79,116 +79,116 @@ treated less-than-or-equal-to a higher priority. inherit the priority of the spawning thread, or it may mean a specific default priority, or it may mean something else, depending on the platform. -## Typedefs ## +## Typedefs -### SbThread ### +### SbThread An opaque handle to a thread type. -#### Definition #### +#### Definition ``` typedef void* SbThread ``` -### SbThreadAffinity ### +### SbThreadAffinity Type for thread core affinity. This generally will be a single cpu (or core or hyperthread) identifier. Some platforms may not support affinity, and some may have specific rules about how it must be used. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadAffinity ``` -### SbThreadContext ### +### SbThreadContext A handle to the context of a frozen thread. -#### Definition #### +#### Definition ``` typedef SbThreadContextPrivate* SbThreadContext ``` -### SbThreadEntryPoint ### +### SbThreadEntryPoint Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of data passed in from the calling thread. -#### Definition #### +#### Definition ``` typedef void*(* SbThreadEntryPoint) (void *context) ``` -### SbThreadId ### +### SbThreadId An ID type that is unique per thread. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadId ``` -### SbThreadLocalDestructor ### +### SbThreadLocalDestructor Function pointer type for Thread-Local destructors. -#### Definition #### +#### Definition ``` typedef void(* SbThreadLocalDestructor) (void *value) ``` -### SbThreadLocalKey ### +### SbThreadLocalKey A handle to a thread-local key. -#### Definition #### +#### Definition ``` typedef SbThreadLocalKeyPrivate* SbThreadLocalKey ``` -### SbThreadSampler ### +### SbThreadSampler A handle to a thread sampler. -#### Definition #### +#### Definition ``` typedef SbThreadSamplerPrivate* SbThreadSampler ``` -## Functions ## +## Functions -### SbThreadContextGetPointer ### +### SbThreadContextGetPointer Gets the specified pointer-type `property` from the specified `context`. Returns `true` if successful and `out_value` has been modified, otherwise returns `false` and `out_value` is not modified. -#### Declaration #### +#### Declaration ``` bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) ``` -### SbThreadContextIsValid ### +### SbThreadContextIsValid Returns whether the given thread context is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadContextIsValid(SbThreadContext context) ``` -### SbThreadCreate ### +### SbThreadCreate Creates a new thread, which starts immediately. @@ -214,13 +214,13 @@ used in production builds. `entry_point`: A pointer to a function that will be executed on the newly created thread. `context`: This value will be passed to the `entry_point` function. -#### Declaration #### +#### Declaration ``` SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) ``` -### SbThreadCreateLocalKey ### +### SbThreadCreateLocalKey Creates and returns a new, unique key for thread local data. If the function does not succeed, the function returns `kSbThreadLocalKeyInvalid`. @@ -233,13 +233,13 @@ value is not NULL. `destructor`: A pointer to a function. The value may be NULL if no clean up is needed. -#### Declaration #### +#### Declaration ``` SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) ``` -### SbThreadDestroyLocalKey ### +### SbThreadDestroyLocalKey Destroys thread local data for the specified key. The function is a no-op if the key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This @@ -247,13 +247,13 @@ function does NOT call the destructor on any stored values. `key`: The key for which to destroy thread local data. -#### Declaration #### +#### Declaration ``` void SbThreadDestroyLocalKey(SbThreadLocalKey key) ``` -### SbThreadDetach ### +### SbThreadDetach Detaches `thread`, which prevents it from being joined. This is sort of like a non-blocking join. This function is a no-op if the thread is already detached or @@ -261,33 +261,33 @@ if the thread is already being joined by another thread. `thread`: The thread to be detached. -#### Declaration #### +#### Declaration ``` void SbThreadDetach(SbThread thread) ``` -### SbThreadGetCurrent ### +### SbThreadGetCurrent Returns the handle of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThread SbThreadGetCurrent() ``` -### SbThreadGetId ### +### SbThreadGetId Returns the Thread ID of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThreadId SbThreadGetId() ``` -### SbThreadGetLocalValue ### +### SbThreadGetLocalValue Returns the pointer-sized value for `key` in the currently executing thread's local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key @@ -295,97 +295,97 @@ has already been destroyed. `key`: The key for which to return the value. -#### Declaration #### +#### Declaration ``` void* SbThreadGetLocalValue(SbThreadLocalKey key) ``` -### SbThreadGetName ### +### SbThreadGetName Returns the debug name of the currently executing thread. -#### Declaration #### +#### Declaration ``` void SbThreadGetName(char *buffer, int buffer_size) ``` -### SbThreadIsCurrent ### +### SbThreadIsCurrent Returns whether `thread` is the current thread. `thread`: The thread to check. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsCurrent(SbThread thread) ``` -### SbThreadIsEqual ### +### SbThreadIsEqual Indicates whether `thread1` and `thread2` refer to the same thread. `thread1`: The first thread to compare. `thread2`: The second thread to compare. -#### Declaration #### +#### Declaration ``` bool SbThreadIsEqual(SbThread thread1, SbThread thread2) ``` -### SbThreadIsValid ### +### SbThreadIsValid Returns whether the given thread handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValid(SbThread thread) ``` -### SbThreadIsValidAffinity ### +### SbThreadIsValidAffinity Returns whether the given thread affinity is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) ``` -### SbThreadIsValidId ### +### SbThreadIsValidId Returns whether the given thread ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidId(SbThreadId id) ``` -### SbThreadIsValidLocalKey ### +### SbThreadIsValidLocalKey Returns whether the given thread local variable key is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) ``` -### SbThreadIsValidPriority ### +### SbThreadIsValidPriority Returns whether the given thread priority is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidPriority(SbThreadPriority priority) ``` -### SbThreadJoin ### +### SbThreadJoin Joins the thread on which this function is called with joinable `thread`. This function blocks the caller until the designated thread exits, and then cleans up @@ -403,36 +403,36 @@ must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, then the SbThreadJoin function populates it with the return value of the thread's `main` function. -#### Declaration #### +#### Declaration ``` bool SbThreadJoin(SbThread thread, void **out_return) ``` -### SbThreadSamplerCreate ### +### SbThreadSamplerCreate Creates a new thread sampler for the specified `thread`. If successful, this function returns the newly created handle. If unsuccessful, this function returns `kSbThreadSamplerInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadSampler SbThreadSamplerCreate(SbThread thread) ``` -### SbThreadSamplerDestroy ### +### SbThreadSamplerDestroy Destroys the `sampler` and frees whatever resources it was using. -#### Declaration #### +#### Declaration ``` void SbThreadSamplerDestroy(SbThreadSampler sampler) ``` -### SbThreadSamplerFreeze ### +### SbThreadSamplerFreeze Suspends execution of the thread that `sampler` was created for. @@ -440,47 +440,47 @@ If successful, this function returns a `SbThreadContext` for the frozen thread, from which properties may be read while the thread remains frozen. If unsuccessful, this function returns `kSbThreadContextInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) ``` -### SbThreadSamplerIsSupported ### +### SbThreadSamplerIsSupported Whether the current platform supports thread sampling. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. If this returns false, `SbThreadSamplerCreate` will return an invalid sampler. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerIsSupported() ``` -### SbThreadSamplerIsValid ### +### SbThreadSamplerIsValid Returns whether the given thread sampler is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadSamplerIsValid(SbThreadSampler sampler) ``` -### SbThreadSamplerThaw ### +### SbThreadSamplerThaw Resumes execution of the thread that `sampler` was created for. This invalidates the context returned from `SbThreadSamplerFreeze`. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerThaw(SbThreadSampler sampler) ``` -### SbThreadSetLocalValue ### +### SbThreadSetLocalValue Sets the pointer-sized value for `key` in the currently executing thread's local storage. The return value indicates whether `key` is valid and has not already @@ -489,26 +489,26 @@ been destroyed. `key`: The key for which to set the key value. `value`: The new pointer-sized key value. -#### Declaration #### +#### Declaration ``` bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) ``` -### SbThreadSetName ### +### SbThreadSetName Sets the debug name of the currently executing thread by copying the specified name string. `name`: The name to assign to the thread. -#### Declaration #### +#### Declaration ``` void SbThreadSetName(const char *name) ``` -### SbThreadSleep ### +### SbThreadSleep Sleeps the currently executing thread. @@ -516,17 +516,17 @@ Sleeps the currently executing thread. executing thread should sleep. The function is a no-op if this value is negative or `0`. -#### Declaration #### +#### Declaration ``` void SbThreadSleep(SbTime duration) ``` -### SbThreadYield ### +### SbThreadYield Yields the currently executing thread, so another thread has a chance to run. -#### Declaration #### +#### Declaration ``` void SbThreadYield() diff --git a/cobalt/site/docs/reference/starboard/modules/13/time.md b/cobalt/site/docs/reference/starboard/modules/13/time.md index 17ea6ad5d004..e5c8cd2fedd0 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/time.md +++ b/cobalt/site/docs/reference/starboard/modules/13/time.md @@ -1,59 +1,59 @@ ---- -layout: doc -title: "Starboard Module Reference: time.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time.h` Provides access to system time and timers. -## Macros ## +## Macros -### kSbTimeDay ### +### kSbTimeDay One day in SbTime units (microseconds). -### kSbTimeHour ### +### kSbTimeHour One hour in SbTime units (microseconds). -### kSbTimeMax ### +### kSbTimeMax The maximum value of an SbTime. -### kSbTimeMillisecond ### +### kSbTimeMillisecond One millisecond in SbTime units (microseconds). -### kSbTimeMinute ### +### kSbTimeMinute One minute in SbTime units (microseconds). -### kSbTimeNanosecondsPerMicrosecond ### +### kSbTimeNanosecondsPerMicrosecond How many nanoseconds in one SbTime unit (microseconds). -### kSbTimeSecond ### +### kSbTimeSecond One second in SbTime units (microseconds). -### kSbTimeToPosixDelta ### +### kSbTimeToPosixDelta A term that can be added to an SbTime to convert it into the number of microseconds since the POSIX epoch. -## Typedefs ## +## Typedefs -### SbTime ### +### SbTime The number of microseconds since the epoch of January 1, 1601 UTC, or the number of microseconds between two times. Always microseconds, ALWAYS UTC. -#### Definition #### +#### Definition ``` typedef int64_t SbTime ``` -### SbTimeMonotonic ### +### SbTimeMonotonic A number of microseconds from some point. The main property of this time is that it increases monotonically. It should also be as high-resolution a timer as we @@ -61,38 +61,38 @@ can get on a platform. So, it is good for measuring the time between two calls without worrying about a system clock adjustment. It's not good for getting the wall clock time. -#### Definition #### +#### Definition ``` typedef int64_t SbTimeMonotonic ``` -## Functions ## +## Functions -### SbTimeFromPosix ### +### SbTimeFromPosix Converts microseconds from the POSIX epoch into an `SbTime`. `time`: A time that measures the number of microseconds since January 1, 1970, 00:00:00, UTC. -#### Declaration #### +#### Declaration ``` static SbTime SbTimeFromPosix(int64_t time) ``` -### SbTimeGetMonotonicNow ### +### SbTimeGetMonotonicNow Gets a monotonically increasing time representing right now. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicNow() ``` -### SbTimeGetMonotonicThreadNow ### +### SbTimeGetMonotonicThreadNow Gets a monotonically increasing time representing how long the current thread has been in the executing state (i.e. not pre-empted nor waiting on an event). @@ -100,44 +100,44 @@ This is not necessarily total time and is intended to allow measuring thread execution time between two timestamps. If this is not available then SbTimeGetMonotonicNow() should be used. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicThreadNow() ``` -### SbTimeGetNow ### +### SbTimeGetNow Gets the current system time as an `SbTime`. -#### Declaration #### +#### Declaration ``` SbTime SbTimeGetNow() ``` -### SbTimeIsTimeThreadNowSupported ### +### SbTimeIsTimeThreadNowSupported Returns whether the current platform supports time thread now -#### Declaration #### +#### Declaration ``` bool SbTimeIsTimeThreadNowSupported() ``` -### SbTimeNarrow ### +### SbTimeNarrow Safely narrows a number from a more precise unit to a less precise one. This function rounds negative values toward negative infinity. -#### Declaration #### +#### Declaration ``` static int64_t SbTimeNarrow(int64_t time, int64_t divisor) ``` -### SbTimeToPosix ### +### SbTimeToPosix Converts `SbTime` into microseconds from the POSIX epoch. @@ -145,7 +145,7 @@ Converts `SbTime` into microseconds from the POSIX epoch. January 1, 1601, UTC, or that measures the number of microseconds between two times. -#### Declaration #### +#### Declaration ``` 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 5768bc358b3b..e82ca6dcbfe2 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/13/time_zone.md @@ -1,38 +1,38 @@ ---- -layout: doc -title: "Starboard Module Reference: time_zone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time_zone.h` Provides access to the system time zone information. -## Typedefs ## +## Typedefs -### SbTimeZone ### +### SbTimeZone 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). -#### Definition #### +#### Definition ``` typedef int SbTimeZone ``` -## Functions ## +## Functions -### SbTimeZoneGetCurrent ### +### SbTimeZoneGetCurrent Gets the system's current SbTimeZone in minutes. -#### Declaration #### +#### Declaration ``` SbTimeZone SbTimeZoneGetCurrent() ``` -### SbTimeZoneGetName ### +### 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 @@ -40,7 +40,7 @@ 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". -#### Declaration #### +#### Declaration ``` const char* SbTimeZoneGetName() diff --git a/cobalt/site/docs/reference/starboard/modules/13/types.md b/cobalt/site/docs/reference/starboard/modules/13/types.md index 90867a69542f..e1f372cc60c4 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/types.md +++ b/cobalt/site/docs/reference/starboard/modules/13/types.md @@ -1,15 +1,15 @@ ---- -layout: doc -title: "Starboard Module Reference: types.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `types.h` Provides a suite of standard types that should be universally available on all platforms, specifically focused on explicitly-sized integer types and booleans. This module also includes some related ubiquitous definitions like limits of the explicitly-sized integer types, and standard pointer and int32 sentinel values. -## Macros ## +## Macros -### kSbInvalidInt ### +### kSbInvalidInt A value that represents an int that is probably invalid. 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 a0ecfb1eafb8..cb4176713005 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/13/ui_navigation.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: ui_navigation.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `ui_navigation.h` API to allow applications to take advantage of the platform's native UI engine. This is mainly to drive the animation of visual elements and to signal which of @@ -19,20 +19,20 @@ SbUiNavItem in case the native UI engine moves individual items in response to user interaction. If the navigation item is a container, then the content offset will also be queried to determine the placement of its content items. -## Macros ## +## Macros -### kSbUiNavItemInvalid ### +### kSbUiNavItemInvalid Well-defined value for an invalid navigation item. -## Enums ## +## Enums -### SbUiNavItemType ### +### SbUiNavItemType Navigation items may be one of the following types. This must be specified upon item creation and may not change during the item's lifespan. -#### Values #### +#### Values * `kSbUiNavItemTypeFocus` @@ -42,29 +42,29 @@ item creation and may not change during the item's lifespan. This is a container of navigation items which can also be containers themselves or focusable items. Containers themselves cannot be focused. -## Typedefs ## +## Typedefs -### SbUiNavItem ### +### SbUiNavItem An opaque handle to an implementation-private structure representing a navigation item. -#### Definition #### +#### Definition ``` typedef struct SbUiNavItemPrivate* SbUiNavItem ``` -## Structs ## +## Structs -### SbUiNavCallbacks ### +### SbUiNavCallbacks This structure specifies all the callbacks which the platform UI engine should invoke for various interaction events on navigation items. These callbacks may be invoked from any thread at any frequency. The `callback_context` is the value that was passed on creation of the relevant SbUiNavItem. -#### Members #### +#### Members * `void(*onblur)(SbUiNavItem item, void *callback_context)` @@ -77,12 +77,12 @@ that was passed on creation of the relevant SbUiNavItem. Invoke when an item's content offset is changed. This is only used with container items. -### SbUiNavInterface ### +### SbUiNavInterface This structure declares the interface to the UI navigation implementation. All function pointers must be specified if the platform supports UI navigation. -#### Members #### +#### Members * `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks *callbacks, void *callback_context)` @@ -237,7 +237,7 @@ function pointers must be specified if the platform supports UI navigation. Call `update_function` with `context` to perform a series of UI navigation changes atomically before returning. -### SbUiNavItemDir ### +### SbUiNavItemDir Navigation items of type kSbUiNavItemTypeContainer have directionality. If directionality is not specified for a container, it should default to left-to- @@ -270,12 +270,12 @@ right and top-to-bottom. Bottom-to-top is similar to right-to-left, but for the Y position. ``` -#### Members #### +#### Members * `bool is_left_to_right` * `bool is_top_to_bottom` -### SbUiNavMatrix2x3 ### +### SbUiNavMatrix2x3 This represents a 2x3 transform matrix in row-major order. @@ -284,38 +284,38 @@ This represents a 2x3 transform matrix in row-major order. /// | c d ty | ``` -#### Members #### +#### Members * `float m` -### SbUiNavMatrix4 ### +### SbUiNavMatrix4 This represents a 4x4 transform matrix in row-major order. -#### Members #### +#### Members * `float m` -## Functions ## +## Functions -### SbUiNavGetInterface ### +### SbUiNavGetInterface Retrieve the platform's UI navigation implementation. If the platform does not provide one, then return false without modifying `out_interface`. Otherwise, initialize all members of `out_interface` and return true. The `out_interface` pointer must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbUiNavGetInterface(SbUiNavInterface *out_interface) ``` -### SbUiNavItemIsValid ### +### SbUiNavItemIsValid Returns whether the given navigation item handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbUiNavItemIsValid(SbUiNavItem item) diff --git a/cobalt/site/docs/reference/starboard/modules/13/user.md b/cobalt/site/docs/reference/starboard/modules/13/user.md index a30cc95b00f9..9442ced8f978 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/user.md +++ b/cobalt/site/docs/reference/starboard/modules/13/user.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: user.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `user.h` Defines a user management API. This module defines functions only for managing signed-in users. Platforms that do not have users must still implement this API, @@ -10,19 +10,19 @@ always reporting a single user that is current and signed in. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbUserInvalid ### +### kSbUserInvalid Well-defined value for an invalid user. -## Enums ## +## Enums -### SbUserPropertyId ### +### SbUserPropertyId A set of string properties that can be queried on a user. -#### Values #### +#### Values * `kSbUserPropertyAvatarUrl` @@ -38,21 +38,21 @@ A set of string properties that can be queried on a user. A unique user ID of a user. -## Typedefs ## +## Typedefs -### SbUser ### +### SbUser A handle to a user. -#### Definition #### +#### Definition ``` typedef SbUserPrivate* SbUser ``` -## Functions ## +## Functions -### SbUserGetCurrent ### +### SbUserGetCurrent Gets the current primary user, if one exists. This is the user that is determined, in a platform-specific way, to be the primary user controlling the @@ -63,13 +63,13 @@ appropriate for the platform. It is expected that there will be a unique SbUser per signed-in user, and that the referenced objects will persist for the lifetime of the app. -#### Declaration #### +#### Declaration ``` SbUser SbUserGetCurrent() ``` -### SbUserGetProperty ### +### SbUserGetProperty Retrieves the value of `property_id` for `user` and places it in `out_value`. The function returns: @@ -83,13 +83,13 @@ The function returns: The property for which the data is requested. `out_value`: The retrieved property value. `value_size`: The size of the retrieved property value. -#### Declaration #### +#### Declaration ``` bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) ``` -### SbUserGetPropertySize ### +### SbUserGetPropertySize Returns the size of the value of `property_id` for `user`, INCLUDING the terminating null character. The function returns `0` if `user` is invalid or if @@ -98,13 +98,13 @@ terminating null character. The function returns `0` if `user` is invalid or if `user`: The user for which property size data is being retrieved. `property_id`: The property for which the data is requested. -#### Declaration #### +#### Declaration ``` int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) ``` -### SbUserGetSignedIn ### +### SbUserGetSignedIn Gets a list of up to `users_size` signed-in users and places the results in `out_users`. The return value identifies the actual number of signed-in users, @@ -116,17 +116,17 @@ the referenced objects will persist for the lifetime of the app. `out_users`: Handles for the retrieved users. `users_size`: The maximum number of signed-in users to retrieve. -#### Declaration #### +#### Declaration ``` int SbUserGetSignedIn(SbUser *out_users, int users_size) ``` -### SbUserIsValid ### +### SbUserIsValid Returns whether the given user handle is valid. -#### Declaration #### +#### Declaration ``` 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 53cda4a6d17e..af49c22be727 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/window.md +++ b/cobalt/site/docs/reference/starboard/modules/13/window.md @@ -1,40 +1,40 @@ ---- -layout: doc -title: "Starboard Module Reference: window.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `window.h` Provides functionality to handle Window creation and management. -## Macros ## +## Macros -### kSbEventOnScreenKeyboardInvalidTicket ### +### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value kSbEventOnScreenKeyboardInvalidTicket. -### kSbWindowInvalid ### +### kSbWindowInvalid Well-defined value for an invalid window handle. -## Typedefs ## +## Typedefs -### SbWindow ### +### SbWindow A handle to a window. -#### Definition #### +#### Definition ``` typedef SbWindowPrivate* SbWindow ``` -## Structs ## +## Structs -### SbWindowOptions ### +### SbWindowOptions Options that can be requested at window creation time. -#### Members #### +#### Members * `SbWindowSize size` @@ -48,25 +48,25 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect ### +### SbWindowRect Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. -#### Members #### +#### Members * `float x` * `float y` * `float width` * `float height` -### SbWindowSize ### +### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window. -#### Members #### +#### Members * `int width` @@ -93,9 +93,9 @@ that would be created to back that window. A value of 0.0f means the ratio could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f). -## Functions ## +## Functions -### SbWindowBlurOnScreenKeyboard ### +### SbWindowBlurOnScreenKeyboard Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred. kSbEventTypeOnScreenKeyboardBlurred has data `ticket`. Calling @@ -103,13 +103,13 @@ 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 #### +#### Declaration ``` void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowCreate ### +### SbWindowCreate Creates and returns a new system window with the given `options`, which may be `NULL`. The function returns `kSbWindowInvalid` if it cannot create the @@ -131,25 +131,25 @@ entry point. `options`: Options that specify parameters for the window being created. -#### Declaration #### +#### Declaration ``` SbWindow SbWindowCreate(const SbWindowOptions *options) ``` -### SbWindowDestroy ### +### SbWindowDestroy Destroys `window`, reclaiming associated resources. `window`: The `SbWindow` to destroy. -#### Declaration #### +#### Declaration ``` bool SbWindowDestroy(SbWindow window) ``` -### SbWindowFocusOnScreenKeyboard ### +### SbWindowFocusOnScreenKeyboard Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused. kSbEventTypeOnScreenKeyboardFocused has data `ticket`. Calling @@ -157,38 +157,38 @@ 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 #### +#### Declaration ``` void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowGetDiagonalSizeInInches ### +### SbWindowGetDiagonalSizeInInches Gets the size of the diagonal between two opposing screen corners. A return value of 0 means that starboard does not know what the screen diagonal is. -#### Declaration #### +#### Declaration ``` float SbWindowGetDiagonalSizeInInches(SbWindow window) ``` -### SbWindowGetOnScreenKeyboardBoundingRect ### +### 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 #### +#### Declaration ``` bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect) ``` -### SbWindowGetPlatformHandle ### +### SbWindowGetPlatformHandle Gets the platform-specific handle for `window`, which can be passed as an EGLNativeWindowType to initialize EGL/GLES. This return value is entirely @@ -196,13 +196,13 @@ platform-specific, so there are no constraints about expected ranges. `window`: The SbWindow to retrieve the platform handle for. -#### Declaration #### +#### Declaration ``` void* SbWindowGetPlatformHandle(SbWindow window) ``` -### SbWindowGetSize ### +### SbWindowGetSize Retrieves the dimensions of `window` and sets `size` accordingly. This function returns `true` if it completes successfully. If the function returns `false`, @@ -210,81 +210,81 @@ then `size` will not have been modified. `window`: The SbWindow to retrieve the size of. `size`: The retrieved size. -#### Declaration #### +#### Declaration ``` bool SbWindowGetSize(SbWindow window, SbWindowSize *size) ``` -### SbWindowHideOnScreenKeyboard ### +### 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 #### +#### Declaration ``` void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowIsOnScreenKeyboardShown ### +### SbWindowIsOnScreenKeyboardShown Determine if the on screen keyboard is shown. -#### Declaration #### +#### Declaration ``` bool SbWindowIsOnScreenKeyboardShown(SbWindow window) ``` -### SbWindowIsValid ### +### SbWindowIsValid Returns whether the given window handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbWindowIsValid(SbWindow window) ``` -### SbWindowOnScreenKeyboardIsSupported ### +### SbWindowOnScreenKeyboardIsSupported Return whether the current platform supports an on screen keyboard -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardIsSupported() ``` -### SbWindowOnScreenKeyboardSuggestionsSupported ### +### SbWindowOnScreenKeyboardSuggestionsSupported Determine if the on screen keyboard has suggestions implemented. If this returns false, then calling SbWindowUpdateOnScreenKeyboardSuggestions() will be undefined. -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardSuggestionsSupported(SbWindow window) ``` -### SbWindowSetDefaultOptions ### +### SbWindowSetDefaultOptions Sets the default options for system windows. `options`: The option values to use as default values. This object must not be `NULL`. -#### Declaration #### +#### Declaration ``` void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` -### SbWindowSetOnScreenKeyboardKeepFocus ### +### 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 @@ -293,13 +293,13 @@ OnScreenKeyboard via input; focus may only be moved via events sent by the app. OnScreenKeyboard via input. `keepFocus` is initialized to false in the OnScreenKeyboard constructor. -#### Declaration #### +#### Declaration ``` void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus) ``` -### SbWindowShowOnScreenKeyboard ### +### SbWindowShowOnScreenKeyboard Show the on screen keyboard and populate the input with text `input_text`. Fire kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary. @@ -309,13 +309,13 @@ 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 #### +#### Declaration ``` void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket) ``` -### SbWindowUpdateOnScreenKeyboardSuggestions ### +### SbWindowUpdateOnScreenKeyboardSuggestions Update the on screen keyboard custom suggestions. Fire kSbEventTypeOnScreenKeyboardSuggestionsUpdated. @@ -323,7 +323,7 @@ kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data `ticket`. The suggestions should remain up-to-date when the keyboard is shown after being hidden. -#### Declaration #### +#### Declaration ``` 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 1a5adcbb873e..5c66ba442803 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/14/accessibility.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: accessibility.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `accessibility.h` Provides access to the system options and settings related to accessibility. -## Enums ## +## Enums -### SbAccessibilityCaptionCharacterEdgeStyle ### +### SbAccessibilityCaptionCharacterEdgeStyle Enum for possible closed captioning character edge styles. -#### Values #### +#### Values * `kSbAccessibilityCaptionCharacterEdgeStyleNone` * `kSbAccessibilityCaptionCharacterEdgeStyleRaised` @@ -19,11 +19,11 @@ Enum for possible closed captioning character edge styles. * `kSbAccessibilityCaptionCharacterEdgeStyleUniform` * `kSbAccessibilityCaptionCharacterEdgeStyleDropShadow` -### SbAccessibilityCaptionColor ### +### SbAccessibilityCaptionColor Enum for possible closed captioning colors. -#### Values #### +#### Values * `kSbAccessibilityCaptionColorBlue` * `kSbAccessibilityCaptionColorBlack` @@ -34,11 +34,11 @@ Enum for possible closed captioning colors. * `kSbAccessibilityCaptionColorWhite` * `kSbAccessibilityCaptionColorYellow` -### SbAccessibilityCaptionFontFamily ### +### SbAccessibilityCaptionFontFamily Enum for possible closed captioning font families -#### Values #### +#### Values * `kSbAccessibilityCaptionFontFamilyCasual` * `kSbAccessibilityCaptionFontFamilyCursive` @@ -48,11 +48,11 @@ Enum for possible closed captioning font families * `kSbAccessibilityCaptionFontFamilyProportionalSerif` * `kSbAccessibilityCaptionFontFamilySmallCapitals` -### SbAccessibilityCaptionFontSizePercentage ### +### SbAccessibilityCaptionFontSizePercentage Enum for possible closed captioning font size percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionFontSizePercentage25` * `kSbAccessibilityCaptionFontSizePercentage50` @@ -67,11 +67,11 @@ Enum for possible closed captioning font size percentages. * `kSbAccessibilityCaptionFontSizePercentage275` * `kSbAccessibilityCaptionFontSizePercentage300` -### SbAccessibilityCaptionOpacityPercentage ### +### SbAccessibilityCaptionOpacityPercentage Enum for possible closed captioning opacity percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionOpacityPercentage0` * `kSbAccessibilityCaptionOpacityPercentage25` @@ -79,11 +79,11 @@ Enum for possible closed captioning opacity percentages. * `kSbAccessibilityCaptionOpacityPercentage75` * `kSbAccessibilityCaptionOpacityPercentage100` -### SbAccessibilityCaptionState ### +### SbAccessibilityCaptionState Enum for possible states of closed captioning properties. -#### Values #### +#### Values * `kSbAccessibilityCaptionStateUnsupported` @@ -115,14 +115,14 @@ Enum for possible states of closed captioning properties. SbAccessibilityCaptionSettings.supportsOverride contains false, then no fields of SbAccessibilityCaptionSettings will ever contain this value. -## Structs ## +## Structs -### SbAccessibilityCaptionSettings ### +### SbAccessibilityCaptionSettings A group of settings related to system-level closed captioning settings, for platforms that expose closed captioning settings. -#### Members #### +#### Members * `SbAccessibilityCaptionColor background_color` * `SbAccessibilityCaptionState background_color_state` @@ -166,9 +166,9 @@ platforms that expose closed captioning settings. false, the values of `SbAccessibilityCaptionState` should be interpreted differently. -### SbAccessibilityDisplaySettings ### +### SbAccessibilityDisplaySettings -#### Members #### +#### Members * `bool has_high_contrast_text_setting` @@ -177,12 +177,12 @@ platforms that expose closed captioning settings. Whether the high contrast text setting is enabled or not. -### SbAccessibilityTextToSpeechSettings ### +### SbAccessibilityTextToSpeechSettings A group of settings related to text-to-speech functionality, for platforms that expose system settings for text-to-speech. -#### Members #### +#### Members * `bool has_text_to_speech_setting` @@ -192,9 +192,9 @@ expose system settings for text-to-speech. Whether the text-to-speech setting is enabled or not. This setting is only valid if `has_text_to_speech_setting` is set to true. -## Functions ## +## Functions -### SbAccessibilityGetCaptionSettings ### +### SbAccessibilityGetCaptionSettings Get the platform's settings for system-level closed captions. This function returns false if `caption_settings` is NULL or if it is not zero-initialized. @@ -202,13 +202,13 @@ returns false if `caption_settings` is NULL or if it is not zero-initialized. `caption_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetCaptionSettings(SbAccessibilityCaptionSettings *caption_settings) ``` -### SbAccessibilityGetDisplaySettings ### +### SbAccessibilityGetDisplaySettings Get the platform settings related to high contrast text. This function returns false if `out_settings` is NULL or if it is not zero-initialized. @@ -216,13 +216,13 @@ false if `out_settings` is NULL or if it is not zero-initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityDisplaySettings* struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetDisplaySettings(SbAccessibilityDisplaySettings *out_settings) ``` -### SbAccessibilityGetTextToSpeechSettings ### +### SbAccessibilityGetTextToSpeechSettings Get the platform settings related to the text-to-speech accessibility feature. This function returns false if `out_settings` is NULL or if it is not zero- @@ -231,13 +231,13 @@ initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetTextToSpeechSettings(SbAccessibilityTextToSpeechSettings *out_settings) ``` -### SbAccessibilitySetCaptionsEnabled ### +### SbAccessibilitySetCaptionsEnabled Modifies whether closed captions are enabled at a system level. This function returns false if this feature is not supported by the platform, or if changing @@ -246,7 +246,7 @@ the setting is unsuccessful. This function will modify the setting system-wide. `enabled`: A boolean indicating whether captions should be turned on (true) or off (false). -#### Declaration #### +#### Declaration ``` 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 9741f3cd7302..0ed31cb649ec 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/14/atomic.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: atomic.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `atomic.h` Defines a set of atomic integer operations that can be used as lightweight synchronization or as building blocks for heavier synchronization primitives. @@ -9,32 +9,32 @@ Their use is very subtle and requires detailed understanding of the behavior of supported architectures, so their direct use is not recommended except when rigorously deemed absolutely necessary for performance reasons. -## Typedefs ## +## Typedefs -### SbAtomic64 ### +### SbAtomic64 64-bit atomic operations (only available on 64-bit processors). -#### Definition #### +#### Definition ``` typedef int64_t SbAtomic64 ``` -### SbAtomicPtr ### +### SbAtomicPtr Pointer-sized atomic operations. Forwards to either 32-bit or 64-bit functions as appropriate. -#### Definition #### +#### Definition ``` typedef SbAtomic32 SbAtomicPtr ``` -## Functions ## +## Functions -### SbAtomicAcquire_CompareAndSwap ### +### SbAtomicAcquire_CompareAndSwap These following lower-level operations are typically useful only to people implementing higher-level synchronization operations like spinlocks, mutexes, @@ -45,23 +45,23 @@ operations ensure that no previous memory access can be reordered after the operation. "Barrier" operations have both "Acquire" and "Release" semantics. A SbAtomicMemoryBarrier() has "Barrier" semantics, but does no memory access. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicAcquire_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicBarrier_Increment ### +### SbAtomicBarrier_Increment Same as SbAtomicNoBarrier_Increment, but with a memory barrier. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicNoBarrier_CompareAndSwap ### +### SbAtomicNoBarrier_CompareAndSwap Atomically execute: result = *ptr; if (*ptr == old_value) *ptr = new_value; return result; @@ -71,39 +71,39 @@ return the old value of "*ptr" This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Exchange ### +### SbAtomicNoBarrier_Exchange Atomically store new_value into *ptr, returning the previous value held in *ptr. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Exchange(volatile SbAtomic32 *ptr, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Increment ### +### SbAtomicNoBarrier_Increment Atomically increment *ptr by "increment". Returns the new value of *ptr with the increment applied. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicRelease_CompareAndSwap8 ### +### SbAtomicRelease_CompareAndSwap8 Overloaded functions for Atomic8. -#### Declaration #### +#### Declaration ``` 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 b0e652f50e92..9277c70837b0 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/14/audio_sink.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: audio_sink.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `audio_sink.h` Provides an interface to output raw audio data. -## Macros ## +## Macros -### kSbAudioSinkInvalid ### +### kSbAudioSinkInvalid Well-defined value for an invalid audio sink. -## Typedefs ## +## Typedefs -### SbAudioSink ### +### SbAudioSink An opaque handle to an implementation-private structure representing an audio sink. -#### Definition #### +#### Definition ``` typedef struct SbAudioSinkPrivate* SbAudioSink ``` -### SbAudioSinkConsumeFramesFunc ### +### SbAudioSinkConsumeFramesFunc Callback used to report frames consumed. The consumed frames will be removed from the source frame buffer to free space for new audio frames. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkConsumeFramesFunc) (int frames_consumed, void *context) ``` -### SbAudioSinkFrameBuffers ### +### SbAudioSinkFrameBuffers An array of frame buffers. For interleaved audio streams, there will be only one element in the array. For planar audio streams, the number of elements in the array equal to the number of channels. -#### Definition #### +#### Definition ``` typedef void** SbAudioSinkFrameBuffers ``` -### SbAudioSinkUpdateSourceStatusFunc ### +### SbAudioSinkUpdateSourceStatusFunc Callback being called periodically to retrieve the status of the audio source. The first two output parameters indicating the filling level of the audio frame @@ -64,15 +64,15 @@ usually this is caused by a seek. All parameters except `context` cannot be NULL. Note that this function only reports the status of the source, it doesn't remove audio data from the source frame buffer. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkUpdateSourceStatusFunc) (int *frames_in_buffer, int *offset_in_frames, bool *is_playing, bool *is_eos_reached, void *context) ``` -## Functions ## +## Functions -### SbAudioSinkCreate ### +### SbAudioSinkCreate Creates an audio sink for the specified `channels` and `sampling_frequency_hz`, acquires all resources needed to operate the audio sink, and returns an opaque @@ -113,13 +113,13 @@ to sample data. value that is passed back to all callbacks and is generally used to point at a class or struct that contains state associated with the audio sink. -#### Declaration #### +#### Declaration ``` SbAudioSink SbAudioSinkCreate(int channels, int sampling_frequency_hz, SbMediaAudioSampleType audio_sample_type, SbMediaAudioFrameStorageType audio_frame_storage_type, SbAudioSinkFrameBuffers frame_buffers, int frames_per_channel, SbAudioSinkUpdateSourceStatusFunc update_source_status_func, SbAudioSinkConsumeFramesFunc consume_frames_func, void *context) ``` -### SbAudioSinkDestroy ### +### SbAudioSinkDestroy Destroys `audio_sink`, freeing all associated resources. Before returning, the function waits until all callbacks that are in progress have finished. After the @@ -132,24 +132,24 @@ any of the callbacks passed into SbAudioSinkCreate. `audio_sink`: The audio sink to destroy. -#### Declaration #### +#### Declaration ``` void SbAudioSinkDestroy(SbAudioSink audio_sink) ``` -### SbAudioSinkGetMaxChannels ### +### SbAudioSinkGetMaxChannels Returns the maximum number of channels supported on the platform. For example, the number would be `2` if the platform only supports stereo. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMaxChannels() ``` -### SbAudioSinkGetMinBufferSizeInFrames ### +### SbAudioSinkGetMinBufferSizeInFrames Returns the minimum frames required by audio sink to play without underflows. Returns -1, if `channels`, `sample_type` or `sampling_frequency_hz` is not @@ -162,52 +162,52 @@ stereo audio. `audio_sample_type`: The type of each sample of the audio data – audio data being streamed. For example, 22,000 Hz means 22,000 sample elements represents one second of audio data. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMinBufferSizeInFrames(int channels, SbMediaAudioSampleType sample_type, int sampling_frequency_hz) ``` -### SbAudioSinkGetNearestSupportedSampleFrequency ### +### SbAudioSinkGetNearestSupportedSampleFrequency Returns the supported sample rate closest to `sampling_frequency_hz`. On platforms that don't support all sample rates, it is the caller's responsibility to resample the audio frames into the supported sample rate returned by this function. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetNearestSupportedSampleFrequency(int sampling_frequency_hz) ``` -### SbAudioSinkIsAudioFrameStorageTypeSupported ### +### SbAudioSinkIsAudioFrameStorageTypeSupported Indicates whether `audio_frame_storage_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioFrameStorageTypeSupported(SbMediaAudioFrameStorageType audio_frame_storage_type) ``` -### SbAudioSinkIsAudioSampleTypeSupported ### +### SbAudioSinkIsAudioSampleTypeSupported Indicates whether `audio_sample_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioSampleTypeSupported(SbMediaAudioSampleType audio_sample_type) ``` -### SbAudioSinkIsValid ### +### SbAudioSinkIsValid Indicates whether the given audio sink handle is valid. `audio_sink`: The audio sink handle to check. -#### Declaration #### +#### Declaration ``` 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 c83927d5132d..72dc9327ed1e 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/14/byte_swap.md @@ -1,74 +1,74 @@ ---- -layout: doc -title: "Starboard Module Reference: byte_swap.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `byte_swap.h` Specifies functions for swapping byte order. These functions are used to deal with endianness when performing I/O. -## Functions ## +## Functions -### SbByteSwapS16 ### +### SbByteSwapS16 Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int16_t SbByteSwapS16(int16_t value) ``` -### SbByteSwapS32 ### +### SbByteSwapS32 Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int32_t SbByteSwapS32(int32_t value) ``` -### SbByteSwapS64 ### +### SbByteSwapS64 Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int64_t SbByteSwapS64(int64_t value) ``` -### SbByteSwapU16 ### +### SbByteSwapU16 Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint16_t SbByteSwapU16(uint16_t value) ``` -### SbByteSwapU32 ### +### SbByteSwapU32 Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint32_t SbByteSwapU32(uint32_t value) ``` -### SbByteSwapU64 ### +### SbByteSwapU64 Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` 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 e58e10652156..2d8f30b5fdce 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/14/condition_variable.md @@ -1,23 +1,23 @@ ---- -layout: doc -title: "Starboard Module Reference: condition_variable.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `condition_variable.h` Defines an interface for condition variables. -## Macros ## +## Macros -### SB_CONDITION_VARIABLE_MAX_SIZE ### +### SB_CONDITION_VARIABLE_MAX_SIZE Max size of the SbConditionVariable type. -## Enums ## +## Enums -### SbConditionVariableResult ### +### SbConditionVariableResult Enumeration of possible results from waiting on a condvar. -#### Values #### +#### Values * `kSbConditionVariableSignaled` @@ -30,22 +30,22 @@ Enumeration of possible results from waiting on a condvar. The wait failed, either because a parameter wasn't valid, or the condition variable has already been destroyed, or something similar. -## Typedefs ## +## Typedefs -### SbConditionVariable ### +### SbConditionVariable An opaque handle to a condition variable type with reserved memory buffer of size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbConditionVariable SbConditionVariable ``` -## Functions ## +## Functions -### SbConditionVariableBroadcast ### +### SbConditionVariableBroadcast Broadcasts to all current waiters of `condition` to stop waiting. This function wakes all of the threads waiting on `condition` while SbConditionVariableSignal @@ -53,26 +53,26 @@ wakes a single thread. `condition`: The condition that should no longer be waited for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableBroadcast(SbConditionVariable *condition) ``` -### SbConditionVariableCreate ### +### SbConditionVariableCreate Creates a new condition variable to work with `opt_mutex`, which may be null, placing the newly created condition variable in `out_condition`. The return value indicates whether the condition variable could be created. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) ``` -### SbConditionVariableDestroy ### +### SbConditionVariableDestroy Destroys the specified SbConditionVariable . The return value indicates whether the destruction was successful. The behavior is undefined if other threads are @@ -81,23 +81,23 @@ currently waiting on this condition variable. `condition`: The SbConditionVariable to be destroyed. This invalidates the condition variable. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableDestroy(SbConditionVariable *condition) ``` -### SbConditionVariableIsSignaled ### +### SbConditionVariableIsSignaled Returns whether the given result is a success. -#### Declaration #### +#### Declaration ``` static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) ``` -### SbConditionVariableSignal ### +### SbConditionVariableSignal Signals the next waiter of `condition` to stop waiting. This function wakes a single thread waiting on `condition` while SbConditionVariableBroadcast wakes @@ -105,24 +105,24 @@ all threads waiting on it. `condition`: The condition that the waiter should stop waiting for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableSignal(SbConditionVariable *condition) ``` -### SbConditionVariableWait ### +### SbConditionVariableWait Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, and returning the result. Behavior is undefined if `mutex` is not held. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) ``` -### SbConditionVariableWaitTimed ### +### SbConditionVariableWaitTimed Waits for `condition`, releasing the held lock `mutex`, blocking up to `timeout_duration`, and returning the acquisition result. Behavior is undefined @@ -133,7 +133,7 @@ if `mutex` is not held. function returns as quickly as possible with a kSbConditionVariableTimedOut result. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime 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 630f1cf32228..d0ba3c7196f8 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/14/configuration.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration.h` Provides a description of the current platform in lurid detail so that common code never needs to actually know what the current operating system and @@ -13,117 +13,117 @@ Configuration feature instead. This implies the continued existence of very narrowly-defined configuration features, but it retains porting control in Starboard. -## Macros ## +## Macros -### SB_ALIGNAS(byte_alignment) ### +### SB_ALIGNAS(byte_alignment) Specifies the alignment for a class, struct, union, enum, class/struct field, or stack variable. -### SB_ALIGNOF(type) ### +### SB_ALIGNOF(type) Returns the alignment required for any instance of the type indicated by `type`. -### SB_ARRAY_SIZE(array) ### +### SB_ARRAY_SIZE(array) A constant expression that evaluates to the size_t size of a statically-sized array. -### SB_ARRAY_SIZE_INT(array) ### +### SB_ARRAY_SIZE_INT(array) A constant expression that evaluates to the int size of a statically-sized array. -### SB_CAN(SB_FEATURE) ### +### SB_CAN(SB_FEATURE) Determines a compile-time capability of the system. -### SB_COMPILE_ASSERT(expr, msg) ### +### SB_COMPILE_ASSERT(expr, msg) Will cause a compiler error with `msg` if `expr` is false. `msg` must be a valid identifier, and must be a unique type in the scope of the declaration. -### SB_DEPRECATED(FUNC) ### +### SB_DEPRECATED(FUNC) SB_DEPRECATED(int Foo(int bar)); Annotates the function as deprecated, which will trigger a compiler warning when referenced. -### SB_DEPRECATED_EXTERNAL(FUNC) ### +### SB_DEPRECATED_EXTERNAL(FUNC) SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION ### +### 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 ### +### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for logging. -### SB_HAS(SB_FEATURE) ### +### SB_HAS(SB_FEATURE) Determines at compile-time whether this platform has a standard feature or header available. -### SB_HAS_64_BIT_ATOMICS ### +### SB_HAS_64_BIT_ATOMICS Whether the current platform has 64-bit atomic operations. -### SB_HAS_GLES2 ### +### SB_HAS_GLES2 Specifies whether this platform has a performant OpenGL ES 2 implementation, which allows client applications to use GL rendering paths. Derived from the gyp variable `gl_type` gl_type which indicates what kind of GL implementation is available. -### SB_HAS_QUIRK(SB_FEATURE) ### +### SB_HAS_QUIRK(SB_FEATURE) Determines at compile-time whether this platform has a quirk. -### SB_INT64_C(x) ### +### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. -### SB_IS(SB_FEATURE) ### +### SB_IS(SB_FEATURE) Determines at compile-time an inherent aspect of this platform. -### SB_LIKELY(x) ### +### SB_LIKELY(x) Macro for hinting that an expression is likely to be true. -### SB_MAXIMUM_API_VERSION ### +### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, inclusive. -### SB_MINIMUM_API_VERSION ### +### SB_MINIMUM_API_VERSION The minimum API version allowed by this version of the Starboard headers, inclusive. -### SB_NORETURN ### +### SB_NORETURN Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE ### +### SB_OVERRIDE Declares a function as overriding a virtual function on compilers that support it. -### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA ### +### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. Setting this up properly means avoiding slow color swizzles when passing pixel data from one library to another. Note that these definitions are in byte-order and so are endianness-independent. -### SB_PRINTF_FORMAT(format_param, dots_param) ### +### SB_PRINTF_FORMAT(format_param, dots_param) Tells the compiler a function is using a printf-style format string. `format_param` is the one-based index of the format string parameter; @@ -132,7 +132,7 @@ functions (which take a va_list), pass 0 for dots_param. (This is undocumented but matches what the system C headers do.) (Partially taken from base/compiler_specific.h) -### SB_RESTRICT ### +### SB_RESTRICT 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 @@ -140,29 +140,29 @@ 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. -### SB_SIZE_OF(DATATYPE) ### +### SB_SIZE_OF(DATATYPE) Determines at compile-time the size of a data type, or 0 if the data type that was specified was invalid. -### SB_STRINGIFY(x) ### +### SB_STRINGIFY(x) Standard CPP trick to stringify an evaluated macro definition. -### SB_UINT64_C(x) ### +### SB_UINT64_C(x) Declare numeric literals of unsigned 64-bit type. -### SB_UNLIKELY(x) ### +### SB_UNLIKELY(x) Macro for hinting that an expression is likely to be false. -### SB_UNREFERENCED_PARAMETER(x) ### +### SB_UNREFERENCED_PARAMETER(x) Trivially references a parameter that is otherwise unreferenced, preventing a compiler warning on some platforms. -### SB_WARN_UNUSED_RESULT ### +### SB_WARN_UNUSED_RESULT Causes the annotated (at the end) function to generate a warning if the result is not accessed. diff --git a/cobalt/site/docs/reference/starboard/modules/14/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/14/configuration_constants.md index 51212e9cebe5..0f61ebfbe2a7 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/14/configuration_constants.md @@ -1,117 +1,117 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration_constants.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration_constants.h` Declares all configuration variables we will need to use at runtime. These variables describe the current platform in detail to allow cobalt to make runtime decisions based on per platform configurations. -## Variables ## +## Variables -### kSbDefaultMmapThreshold ### +### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if available), rather than allocated within the core heap. -### kSbFileAltSepChar ### +### kSbFileAltSepChar The current platform's alternate file path component separator character. This is like SB_FILE_SEP_CHAR, except if your platform supports an alternate character, then you can place that here. For example, on windows machines, the primary separator character is probably '\', but the alternate is '/'. -### kSbFileAltSepString ### +### kSbFileAltSepString The string form of SB_FILE_ALT_SEP_CHAR. -### kSbFileMaxName ### +### kSbFileMaxName The current platform's maximum length of the name of a single directory entry, not including the absolute path. -### kSbFileMaxOpen ### +### kSbFileMaxOpen The current platform's maximum number of files that can be opened at the same time by one process. -### kSbFileMaxPath ### +### kSbFileMaxPath The current platform's maximum length of an absolute path. -### kSbFileSepChar ### +### kSbFileSepChar The current platform's file path component separator character. This is the character that appears after a directory in a file path. For example, the absolute canonical path of the file "/path/to/a/file.txt" uses '/' as a path component separator character. -### kSbFileSepString ### +### kSbFileSepString The string form of SB_FILE_SEP_CHAR. -### kSbHasAc3Audio ### +### kSbHasAc3Audio Allow ac3 and ec3 support -### kSbHasMediaWebmVp9Support ### +### kSbHasMediaWebmVp9Support Specifies whether this platform has webm/vp9 support. This should be set to non- zero on platforms with webm/vp9 support. -### kSbHasThreadPrioritySupport ### +### kSbHasThreadPrioritySupport Whether the current platform supports thread priorities. -### kSbMallocAlignment ### +### kSbMallocAlignment Determines the alignment that allocations should have on this platform. -### kSbMaxSystemPathCacheDirectorySize ### +### kSbMaxSystemPathCacheDirectorySize The maximum size the cache directory is allowed to use in bytes. -### kSbMaxThreadLocalKeys ### +### kSbMaxThreadLocalKeys The maximum number of thread local storage keys supported by this platform. This comes from _POSIX_THREAD_KEYS_MAX. The value of PTHREAD_KEYS_MAX is higher, but unit tests show that the implementation doesn't support nearly as many keys. -### kSbMaxThreadNameLength ### +### kSbMaxThreadNameLength The maximum length of the name for a thread, including the NULL-terminator. -### kSbMaxThreads ### +### kSbMaxThreads Defines the maximum number of simultaneous threads for this platform. Some platforms require sharing thread handles with other kinds of system handles, like mutexes, so we want to keep this manageable. -### kSbMediaMaxAudioBitrateInBitsPerSecond ### +### kSbMediaMaxAudioBitrateInBitsPerSecond The maximum audio bitrate the platform can decode. The following value equals to 5M bytes per seconds which is more than enough for compressed audio. -### kSbMediaMaxVideoBitrateInBitsPerSecond ### +### kSbMediaMaxVideoBitrateInBitsPerSecond The maximum video bitrate the platform can decode. The following value equals to 8M bytes per seconds which is more than enough for compressed video. -### kSbMediaVideoFrameAlignment ### +### kSbMediaVideoFrameAlignment Specifies how video frame buffers must be aligned on this platform. -### kSbMemoryLogPath ### +### kSbMemoryLogPath Defines the path where memory debugging logs should be written to. -### kSbMemoryPageSize ### +### kSbMemoryPageSize The memory page size, which controls the size of chunks on memory that allocators deal with, and the alignment of those chunks. This doesn't have to be the hardware-defined physical page size, but it should be a multiple of it. -### kSbNetworkReceiveBufferSize ### +### kSbNetworkReceiveBufferSize Specifies the network receive buffer size in bytes, set via SbSocketSetReceiveBufferSize(). @@ -126,7 +126,7 @@ affect throughput in the presence of latency. If your platform does not have a good TCP auto-tuning mechanism, a setting of (128 * 1024) here is recommended. -### kSbPathSepChar ### +### kSbPathSepChar The current platform's search path component separator character. When specifying an ordered list of absolute paths of directories to search for a @@ -134,16 +134,16 @@ given reason, this is the character that appears between entries. For example, the search path of "/etc/search/first:/etc/search/second" uses ':' as a search path component separator character. -### kSbPathSepString ### +### kSbPathSepString The string form of SB_PATH_SEP_CHAR. -### kSbPreferredRgbaByteOrder ### +### kSbPreferredRgbaByteOrder Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. -### kSbUserMaxSignedIn ### +### kSbUserMaxSignedIn The maximum number of users that can be signed in at the same time. 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 7a4bcc05ddd0..e2aa35f2bb1a 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/14/cpu_features.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: cpu_features.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml -## Structs ## +# Starboard Module Reference: `cpu_features.h` -### SbCPUFeatures ### +## Structs -#### Members #### +### SbCPUFeatures + +#### Members * `SbCPUFeaturesArchitecture architecture` @@ -54,9 +54,9 @@ title: "Starboard Module Reference: cpu_features.h" defined as a macro. * `SbCPUFeaturesX86 x86` -### SbCPUFeaturesARM ### +### SbCPUFeaturesARM -#### Members #### +#### Members * `int16_t implementer` @@ -98,7 +98,7 @@ title: "Starboard Module Reference: cpu_features.h" SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags ###### + ###### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -114,17 +114,17 @@ title: "Starboard Module Reference: cpu_features.h" 64-bit PMULL and PMULL2 instructions. -### SbCPUFeaturesMIPS ### +### SbCPUFeaturesMIPS -#### Members #### +#### Members * `bool has_msa` MIPS SIMD Architecture (MSA). -### SbCPUFeaturesX86 ### +### SbCPUFeaturesX86 -#### Members #### +#### Members * `const char * vendor` @@ -244,9 +244,9 @@ title: "Starboard Module Reference: cpu_features.h" SAHF in long mode. -## Functions ## +## Functions -### SbCPUFeaturesGet ### +### SbCPUFeaturesGet Retrieve the underlying CPU features and place it in `features`, which must not be NULL. @@ -254,7 +254,7 @@ be NULL. If this function returns false, it means the CPU architecture is unknown and all fields in `features` are invalid. -#### Declaration #### +#### Declaration ``` 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 a237ad98c81b..1e98db5db54d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/14/decode_target.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: decode_target.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `decode_target.h` A target for decoding image and video data into. This corresponds roughly to an EGLImage, but that extension may not be fully supported on all GL platforms. @@ -12,7 +12,7 @@ data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. -## SbDecodeTargetFormat ## +## SbDecodeTargetFormat SbDecodeTargets support several different formats that can be used to decode into and render from. Some formats may be easier to decode into, and others may @@ -21,7 +21,7 @@ the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. -## SbDecodeTargetGraphicsContextProvider ## +## SbDecodeTargetGraphicsContextProvider Some components may need to acquire SbDecodeTargets compatible with a certain rendering context, which may need to be created on a particular thread. The @@ -36,7 +36,7 @@ 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 ## +## 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. @@ -79,15 +79,15 @@ GLuint texture = info.planes[kSbDecodeTargetPlaneRGBA].texture; ``` -## Macros ## +## Macros -### kSbDecodeTargetInvalid ### +### kSbDecodeTargetInvalid Well-defined value for an invalid decode target handle. -## Enums ## +## Enums -### SbDecodeTargetFormat ### +### SbDecodeTargetFormat The list of all possible decoder target formats. An SbDecodeTarget consists of one or more planes of data, each plane corresponding with a surface. For some @@ -96,7 +96,7 @@ formats, different planes will be different sizes for the same dimensions. NOTE: For enumeration entries with an alpha component, the alpha will always be premultiplied unless otherwise explicitly specified. -#### Values #### +#### Values * `kSbDecodeTargetFormat1PlaneRGBA` @@ -137,11 +137,11 @@ premultiplied unless otherwise explicitly specified. An invalid decode target format. -### SbDecodeTargetPlane ### +### SbDecodeTargetPlane All the planes supported by SbDecodeTarget. -#### Values #### +#### Values * `kSbDecodeTargetPlaneRGBA` @@ -162,45 +162,45 @@ All the planes supported by SbDecodeTarget. The V plane for 3-plane YUV formats. -## Typedefs ## +## Typedefs -### SbDecodeTarget ### +### SbDecodeTarget A handle to a target for image data decoding. -#### Definition #### +#### Definition ``` typedef SbDecodeTargetPrivate* SbDecodeTarget ``` -### SbDecodeTargetGlesContextRunner ### +### SbDecodeTargetGlesContextRunner Signature for a function provided by the application to the Starboard implementation that will let the Starboard implementation run arbitrary code on the application's renderer thread with the application's EGLContext held current. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunner) (struct SbDecodeTargetGraphicsContextProvider *graphics_context_provider, SbDecodeTargetGlesContextRunnerTarget target_function, void *target_function_context) ``` -### SbDecodeTargetGlesContextRunnerTarget ### +### SbDecodeTargetGlesContextRunnerTarget Signature for a Starboard implementation function that is to be run by a SbDecodeTargetGlesContextRunner callback. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunnerTarget) (void *gles_context_runner_target_context) ``` -## Structs ## +## Structs -### SbDecodeTargetGraphicsContextProvider ### +### SbDecodeTargetGraphicsContextProvider In general, the SbDecodeTargetGraphicsContextProvider structure provides information about the graphics context that will be used to render @@ -210,7 +210,7 @@ References to SbDecodeTargetGraphicsContextProvider objects should be provided to all Starboard functions that might create SbDecodeTargets (e.g. SbImageDecode()). -#### Members #### +#### Members * `void * egl_display` @@ -233,12 +233,12 @@ SbImageDecode()). Context data that is to be passed in to `gles_context_runner` when it is invoked. -### SbDecodeTargetInfo ### +### SbDecodeTargetInfo Contains all information about a decode target, including all of its planes. This can be queried via calls to SbDecodeTargetGetInfo(). -#### Members #### +#### Members * `SbDecodeTargetFormat format` @@ -267,11 +267,11 @@ This can be queried via calls to SbDecodeTargetGetInfo(). kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode target. -### SbDecodeTargetInfoContentRegion ### +### SbDecodeTargetInfoContentRegion Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. -#### Members #### +#### Members * `float left` @@ -283,11 +283,11 @@ Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. * `float right` * `float bottom` -### SbDecodeTargetInfoPlane ### +### SbDecodeTargetInfoPlane Defines an image plane within a SbDecodeTargetInfo object. -#### Members #### +#### Members * `uint32_t texture` @@ -317,53 +317,53 @@ Defines an image plane within a SbDecodeTargetInfo object. these parameters are number of pixels. The range for left/right is [0, width], and for top/bottom it is [0, height]. -## Functions ## +## Functions -### PrivateDecodeTargetReleaser ### +### PrivateDecodeTargetReleaser This function is just an implementation detail of SbDecodeTargetReleaseInGlesContext() and should not be called directly. -#### Declaration #### +#### Declaration ``` static void PrivateDecodeTargetReleaser(void *context) ``` -### SbDecodeTargetGetInfo ### +### SbDecodeTargetGetInfo Writes all information about `decode_target` into `out_info`. The `decode_target` must not be kSbDecodeTargetInvalid. The `out_info` pointer must not be NULL. Returns false if the provided `out_info` structure is not zero initialized. -#### Declaration #### +#### Declaration ``` bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target, SbDecodeTargetInfo *out_info) ``` -### SbDecodeTargetIsFormatValid ### +### SbDecodeTargetIsFormatValid Returns whether a given format is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsFormatValid(SbDecodeTargetFormat format) ``` -### SbDecodeTargetIsValid ### +### SbDecodeTargetIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsValid(SbDecodeTarget handle) ``` -### SbDecodeTargetRelease ### +### SbDecodeTargetRelease Returns ownership of `decode_target` to the Starboard implementation. This function will likely result in the destruction of the SbDecodeTarget and all its @@ -371,31 +371,31 @@ 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 -#### Declaration #### +#### Declaration ``` void SbDecodeTargetRelease(SbDecodeTarget decode_target) ``` -### SbDecodeTargetReleaseInGlesContext ### +### SbDecodeTargetReleaseInGlesContext Helper function that is possibly useful to Starboard implementations that will release a decode target on the thread with the GLES context current. -#### Declaration #### +#### Declaration ``` static void SbDecodeTargetReleaseInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTarget decode_target) ``` -### SbDecodeTargetRunInGlesContext ### +### SbDecodeTargetRunInGlesContext Inline convenience function to run an arbitrary SbDecodeTargetGlesContextRunnerTarget function through a SbDecodeTargetGraphicsContextProvider . This is intended to be called by Starboard implementations, if it is necessary. -#### Declaration #### +#### Declaration ``` 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 dcdf48a0e479..6f845f6567a9 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/14/directory.md @@ -1,56 +1,56 @@ ---- -layout: doc -title: "Starboard Module Reference: directory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `directory.h` Provides directory listing functions. -## Macros ## +## Macros -### kSbDirectoryInvalid ### +### kSbDirectoryInvalid Well-defined value for an invalid directory stream handle. -## Typedefs ## +## Typedefs -### SbDirectory ### +### SbDirectory A handle to an open directory stream. -#### Definition #### +#### Definition ``` typedef struct SbDirectoryPrivate* SbDirectory ``` -## Functions ## +## Functions -### SbDirectoryCanOpen ### +### SbDirectoryCanOpen Indicates whether SbDirectoryOpen is allowed for the given `path`. `path`: The path to be checked. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCanOpen(const char *path) ``` -### SbDirectoryClose ### +### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the directory was closed successfully. `directory`: The directory stream handle to close. -#### Declaration #### +#### Declaration ``` bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate ### +### SbDirectoryCreate Creates the directory `path`, assuming the parent directory already exists. This function returns `true` if the directory now exists (even if it existed before) @@ -58,13 +58,13 @@ and returns `false` if the directory does not exist. `path`: The path to be created. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCreate(const char *path) ``` -### SbDirectoryGetNext ### +### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and moves the stream forward by one entry. @@ -83,23 +83,23 @@ entry. The space allocated for this string should be equal to `out_entry_size`. `out_entry_size`: The size of the space allocated for `out_entry`. This should be at least equal to kSbFileMaxName. -#### Declaration #### +#### Declaration ``` bool SbDirectoryGetNext(SbDirectory directory, char *out_entry, size_t out_entry_size) ``` -### SbDirectoryIsValid ### +### SbDirectoryIsValid Returns whether the given directory stream handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDirectoryIsValid(SbDirectory directory) ``` -### SbDirectoryOpen ### +### SbDirectoryOpen Opens the given existing directory for listing. This function returns kSbDirectoryInvalidHandle if it is not successful. @@ -110,7 +110,7 @@ SbFileError code on failure. `out_error`: An output parameter that, in case of an error, is set to the reason that the directory could not be opened. -#### Declaration #### +#### Declaration ``` 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 fbb92f9ec841..f42e43bf3db7 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/14/drm.md @@ -1,37 +1,37 @@ ---- -layout: doc -title: "Starboard Module Reference: drm.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `drm.h` Provides definitions that allow for DRM support, which are common between Player and Decoder interfaces. -## Macros ## +## Macros -### kSbDrmSystemInvalid ### +### kSbDrmSystemInvalid An invalid SbDrmSystem. -### kSbDrmTicketInvalid ### +### kSbDrmTicketInvalid A ticket for callback invocations initiated by the DRM system. -## Enums ## +## Enums -### SbDrmEncryptionScheme ### +### SbDrmEncryptionScheme Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. -#### Values #### +#### Values * `kSbDrmEncryptionSchemeAesCtr` * `kSbDrmEncryptionSchemeAesCbc` -### SbDrmKeyStatus ### +### SbDrmKeyStatus Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) -#### Values #### +#### Values * `kSbDrmKeyStatusUsable` * `kSbDrmKeyStatusExpired` @@ -41,24 +41,24 @@ Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-de * `kSbDrmKeyStatusPending` * `kSbDrmKeyStatusError` -### SbDrmSessionRequestType ### +### SbDrmSessionRequestType The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype) -#### Values #### +#### Values * `kSbDrmSessionRequestTypeLicenseRequest` * `kSbDrmSessionRequestTypeLicenseRenewal` * `kSbDrmSessionRequestTypeLicenseRelease` * `kSbDrmSessionRequestTypeIndividualizationRequest` -### SbDrmStatus ### +### SbDrmStatus The status of session related operations. Used by `SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and `SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names) -#### Values #### +#### Values * `kSbDrmStatusSuccess` * `kSbDrmStatusTypeError` @@ -70,42 +70,42 @@ The status of session related operations. Used by The following error can be used when the error status cannot be mapped to one of the above errors. -## Typedefs ## +## Typedefs -### SbDrmServerCertificateUpdatedFunc ### +### SbDrmServerCertificateUpdatedFunc A callback to notify the caller of SbDrmUpdateServerCertificate() whether the update has been successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message) ``` -### SbDrmSessionClosedFunc ### +### SbDrmSessionClosedFunc A callback for signalling that a session has been closed by the SbDrmSystem -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size) ``` -### SbDrmSessionKeyStatusesChangedFunc ### +### SbDrmSessionKeyStatusesChangedFunc A callback for notifications that the status of one or more keys in a session has been changed. All keys of the session and their new status will be passed along. Any keys not in the list is considered as deleted. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses) ``` -### SbDrmSessionUpdateRequestFunc ### +### SbDrmSessionUpdateRequestFunc A callback that will receive generated session update request when requested from a SbDrmSystem. `drm_system` will be the DRM system that @@ -128,13 +128,13 @@ there was an error generating the request. This allows Cobalt to find and reject the correct Promise corresponding to the associated SbDrmGenerateSessionUpdateRequest(). -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url) ``` -### SbDrmSessionUpdatedFunc ### +### SbDrmSessionUpdatedFunc A callback for notifications that a session has been added, and subsequent encrypted samples are actively ready to be decoded. `drm_system` will be the DRM @@ -150,37 +150,37 @@ context passed into that call to SbDrmCreateSystem(). `status` is `kSbDrmStatusSuccess` or if no error message can be provided. `succeeded` is whether the session was successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size) ``` -### SbDrmSystem ### +### SbDrmSystem A handle to a DRM system which can be used with either an SbDecoder or an SbPlayer. -#### Definition #### +#### Definition ``` typedef struct SbDrmSystemPrivate* SbDrmSystem ``` -## Structs ## +## Structs -### SbDrmEncryptionPattern ### +### SbDrmEncryptionPattern Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. -#### Members #### +#### Members * `uint32_t crypt_byte_block` * `uint32_t skip_byte_block` -### SbDrmKeyId ### +### SbDrmKeyId -#### Members #### +#### Members * `uint8_t identifier` @@ -188,11 +188,11 @@ Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. PlayReady, this is the license GUID in packed little-endian binary form. * `int identifier_size` -### SbDrmSampleInfo ### +### SbDrmSampleInfo All the optional information needed per sample for encrypted samples. -#### Members #### +#### Members * `SbDrmEncryptionScheme encryption_scheme` @@ -217,13 +217,13 @@ All the optional information needed per sample for encrypted samples. The clear/encrypted mapping of each subsample in this sample. This must be an array of `subsample_count` mappings. -### SbDrmSubSampleMapping ### +### SbDrmSubSampleMapping A mapping of clear and encrypted bytes for a single subsample. All subsamples within a sample must be encrypted with the same encryption parameters. The clear bytes always appear first in the sample. -#### Members #### +#### Members * `int32_t clear_byte_count` @@ -232,21 +232,21 @@ bytes always appear first in the sample. How many bytes of the corresponding subsample are encrypted. -## Functions ## +## Functions -### SbDrmCloseSession ### +### SbDrmCloseSession Clear any internal states/resources related to the specified `session_id`. `drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` -### SbDrmDestroySystem ### +### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and invalidates all outstanding session update requests. A DRM system cannot be @@ -258,13 +258,13 @@ SbDrmCreateSystem(), a deadlock will occur. `drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` void SbDrmDestroySystem(SbDrmSystem drm_system) ``` -### SbDrmGenerateSessionUpdateRequest ### +### SbDrmGenerateSessionUpdateRequest Asynchronously generates a session update request payload for `initialization_data`, of `initialization_data_size`, in case sensitive `type`, @@ -296,13 +296,13 @@ be NULL. `initialization_data`: The data for which the session update request payload is created. Must not be NULL. `initialization_data_size`: The size of the session update request payload. -#### Declaration #### +#### Declaration ``` void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size) ``` -### SbDrmGetMetrics ### +### SbDrmGetMetrics Get the metrics of the underlying drm system. @@ -326,13 +326,13 @@ system, or when the drm system implementation fails to retrieve the metrics. `drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL. -#### Declaration #### +#### Declaration ``` const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size) ``` -### SbDrmIsServerCertificateUpdatable ### +### SbDrmIsServerCertificateUpdatable Returns true if server certificate of `drm_system` can be updated via SbDrmUpdateServerCertificate(). The return value should remain the same during @@ -341,33 +341,33 @@ the life time of `drm_system`. `drm_system`: The DRM system to check if its server certificate is updatable. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system) ``` -### SbDrmSystemIsValid ### +### SbDrmSystemIsValid Indicates whether `drm_system` is a valid SbDrmSystem. -#### Declaration #### +#### Declaration ``` static bool SbDrmSystemIsValid(SbDrmSystem drm) ``` -### SbDrmTicketIsValid ### +### SbDrmTicketIsValid Indicates whether `ticket` is a valid ticket. -#### Declaration #### +#### Declaration ``` static bool SbDrmTicketIsValid(int ticket) ``` -### SbDrmUpdateServerCertificate ### +### SbDrmUpdateServerCertificate Update the server certificate of `drm_system`. The function can be called multiple times. It is possible that a call to it happens before the callback of @@ -384,13 +384,13 @@ requests with the same ticket may result in undefined behavior. The value certificate data. Must not be NULL. `certificate_size`: Size of the server certificate data. -#### Declaration #### +#### Declaration ``` void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size) ``` -### SbDrmUpdateSession ### +### SbDrmUpdateSession Update session with `key`, in `drm_system`'s key system, from the license server response. Calls `session_updated_callback` with `context` and whether the update @@ -410,7 +410,7 @@ with that DRM key system will be able to decrypt encrypted samples. thread before this function returns or from another thread. The `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` 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 c8c2120b0acf..4afff1aa236e 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/14/egl.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: egl.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `egl.h` The EGL API provides an interface with accompanying type declarations and defines that together provide a single consistent method of EGL usage across @@ -11,67 +11,67 @@ 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 functions from EGL 1.5 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_EGL_ALPHA_FORMAT ### +### SB_EGL_ALPHA_FORMAT EGL_VERSION_1_2 -### SB_EGL_ALPHA_SIZE ### +### SB_EGL_ALPHA_SIZE EGL_VERSION_1_0 -### SB_EGL_BACK_BUFFER ### +### SB_EGL_BACK_BUFFER EGL_VERSION_1_1 -### SB_EGL_CONFORMANT ### +### SB_EGL_CONFORMANT EGL_VERSION_1_3 -### SB_EGL_CONTEXT_MAJOR_VERSION ### +### SB_EGL_CONTEXT_MAJOR_VERSION EGL_VERSION_1_5 -### SB_EGL_DEFAULT_DISPLAY ### +### SB_EGL_DEFAULT_DISPLAY EGL_VERSION_1_4 -## Typedefs ## +## Typedefs -### SbEglCastsToProperFunctionPointerType ### +### SbEglCastsToProperFunctionPointerType The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/egl.h](https://www.khronos.org/registry/EGL/api/EGL/egl.h) . -#### Definition #### +#### Definition ``` typedef void(* SbEglCastsToProperFunctionPointerType) (void) ``` -### SbEglInt32 ### +### SbEglInt32 The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h](https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h) . -#### Definition #### +#### Definition ``` typedef int32_t SbEglInt32 ``` -## Structs ## +## Structs -### SbEglInterface ### +### SbEglInterface -#### Members #### +#### Members * `SbEglBoolean(*eglChooseConfig)(SbEglDisplay dpy, const SbEglInt32 *attrib_list, SbEglConfig *configs, SbEglInt32 config_size, SbEglInt32 diff --git a/cobalt/site/docs/reference/starboard/modules/14/event.md b/cobalt/site/docs/reference/starboard/modules/14/event.md index 01a9d24cadbf..7887d8d235f7 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/event.md +++ b/cobalt/site/docs/reference/starboard/modules/14/event.md @@ -1,11 +1,11 @@ ---- -layout: doc -title: "Starboard Module Reference: event.h" ---- +Project: /youtube/cobalt/_project.yaml +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 ``` * ---------- @@ -78,15 +78,15 @@ for a more graceful shutdown. Note that the application is always expected to transition through `BLURRED`, `CONCEALED` to `FROZEN` before receiving `Stop` or being killed. -## Enums ## +## Enums -### SbEventType ### +### SbEventType An enumeration of all possible event types dispatched directly by the system. Each event is accompanied by a void* data argument, and each event must define the type of the value pointed to by that data argument, if any. -#### Values #### +#### Values * `kSbEventTypePreload` @@ -273,55 +273,55 @@ the type of the value pointed to by that data argument, if any. change in the timezone setting). This should trigger the application to re- query the relevant APIs to update the date and time. -## Typedefs ## +## Typedefs -### SbEventCallback ### +### SbEventCallback A function that can be called back from the main Starboard event pump. -#### Definition #### +#### Definition ``` typedef void(* SbEventCallback) (void *context) ``` -### SbEventDataDestructor ### +### SbEventDataDestructor A function that will cleanly destroy an event data instance of a specific type. -#### Definition #### +#### Definition ``` typedef void(* SbEventDataDestructor) (void *data) ``` -### SbEventId ### +### SbEventId An ID that can be used to refer to a scheduled event. -#### Definition #### +#### Definition ``` typedef uint32_t SbEventId ``` -## Structs ## +## Structs -### SbEvent ### +### SbEvent Structure representing a Starboard event and its data. -#### Members #### +#### Members * `SbEventType type` * `SbTimeMonotonic timestamp` * `void * data` -### SbEventStartData ### +### SbEventStartData Event data for kSbEventTypeStart events. -#### Members #### +#### Members * `char ** argument_values` @@ -333,31 +333,31 @@ Event data for kSbEventTypeStart events. The startup link, if any. -### SbEventWindowSizeChangedData ### +### SbEventWindowSizeChangedData Event data for kSbEventTypeWindowSizeChanged events. -#### Members #### +#### Members * `SbWindow window` * `SbWindowSize size` -## Functions ## +## Functions -### SbEventCancel ### +### SbEventCancel Cancels the specified `event_id`. Note that this function is a no-op if the event already fired. This function can be safely called from any thread, but the only way to guarantee that the event does not run anyway is to call it from the main Starboard event loop thread. -#### Declaration #### +#### Declaration ``` void SbEventCancel(SbEventId event_id) ``` -### SbEventHandle ### +### SbEventHandle The entry point that Starboard applications MUST implement. Any memory pointed at by `event` or the `data` field inside `event` is owned by the system, and @@ -370,23 +370,23 @@ specification about what other work might happen on this thread, so the application should generally do as little work as possible on this thread, and just dispatch it over to another thread. -#### Declaration #### +#### Declaration ``` SB_IMPORT void SbEventHandle(const SbEvent *event) ``` -### SbEventIsIdValid ### +### SbEventIsIdValid Returns whether the given event handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbEventIsIdValid(SbEventId handle) ``` -### SbEventSchedule ### +### SbEventSchedule Schedules an event `callback` into the main Starboard event loop. This function may be called from any thread, but `callback` is always called from the main @@ -397,7 +397,7 @@ context that is passed to the `callback` function. `delay`: The minimum number of microseconds to wait before calling the `callback` function. Set `delay` to `0` to call the callback as soon as possible. -#### Declaration #### +#### Declaration ``` SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) diff --git a/cobalt/site/docs/reference/starboard/modules/14/export.md b/cobalt/site/docs/reference/starboard/modules/14/export.md index ff797770e824..a398d4ad0c85 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/export.md +++ b/cobalt/site/docs/reference/starboard/modules/14/export.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: export.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `export.h` Provides macros for properly exporting or importing symbols from shared libraries. -## Macros ## +## Macros -### SB_EXPORT ### +### SB_EXPORT Specification for a symbol that should be exported when building the DLL and imported when building code that uses the DLL. -### SB_EXPORT_PRIVATE ### +### SB_EXPORT_PRIVATE Specification for a symbol that should be exported or imported for testing purposes only. -### SB_IMPORT ### +### SB_IMPORT Specification for a symbol that is expected to be defined externally to this module. diff --git a/cobalt/site/docs/reference/starboard/modules/14/file.md b/cobalt/site/docs/reference/starboard/modules/14/file.md index 56eb415e677f..103af475ace1 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/file.md +++ b/cobalt/site/docs/reference/starboard/modules/14/file.md @@ -1,25 +1,25 @@ ---- -layout: doc -title: "Starboard Module Reference: file.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `file.h` Defines file system input/output functions. -## Macros ## +## Macros -### kSbFileInvalid ### +### kSbFileInvalid Well-defined value for an invalid file handle. -## Enums ## +## Enums -### SbFileError ### +### SbFileError kSbFileErrorAccessDenied is returned when a call fails because of a filesystem restriction. kSbFileErrorSecurity is returned when a security policy doesn't allow the operation to be executed. -#### Values #### +#### Values * `kSbFileOk` * `kSbFileErrorFailed` @@ -40,7 +40,7 @@ allow the operation to be executed. * `kSbFileErrorIO` * `kSbFileErrorMax` -### SbFileFlags ### +### SbFileFlags Flags that define how a file is used in the application. These flags should be or'd together when passed to SbFileOpen to open or create a file. @@ -66,7 +66,7 @@ In addition, one or more of the following flags must be specified: The `kSbFileAsync` flag is optional. -#### Values #### +#### Values * `kSbFileOpenOnly` * `kSbFileCreateOnly` @@ -85,35 +85,35 @@ The `kSbFileAsync` flag is optional. * `kSbFileWrite` * `kSbFileAsync` -### SbFileWhence ### +### SbFileWhence This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. -#### Values #### +#### Values * `kSbFileFromBegin` * `kSbFileFromCurrent` * `kSbFileFromEnd` -## Typedefs ## +## Typedefs -### SbFile ### +### SbFile A handle to an open file. -#### Definition #### +#### Definition ``` typedef SbFilePrivate* SbFile ``` -## Structs ## +## Structs -### SbFileInfo ### +### SbFileInfo Used to hold information about a file. -#### Members #### +#### Members * `int64_t size` @@ -134,9 +134,9 @@ Used to hold information about a file. The creation time of a file. -## Functions ## +## Functions -### SbFileAtomicReplace ### +### SbFileAtomicReplace Replaces the content of the file at `path` with `data`. Returns whether the contents of the file were replaced. The replacement of the content is an atomic @@ -146,39 +146,39 @@ operation. The file will either have all of the data, or none. to replace the file contents with. `data_size`: The amount of `data`, in bytes, to be written to the file. -#### Declaration #### +#### Declaration ``` bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size) ``` -### SbFileCanOpen ### +### SbFileCanOpen Indicates whether SbFileOpen() with the given `flags` is allowed for `path`. `path`: The absolute path to be checked. `flags`: The flags that are being evaluated for the given `path`. -#### Declaration #### +#### Declaration ``` bool SbFileCanOpen(const char *path, int flags) ``` -### SbFileClose ### +### SbFileClose Closes `file`. The return value indicates whether the file was closed successfully. `file`: The absolute path of the file to be closed. -#### Declaration #### +#### Declaration ``` bool SbFileClose(SbFile file) ``` -### SbFileDelete ### +### SbFileDelete Deletes the regular file, symlink, or empty directory at `path`. This function is used primarily to clean up after unit tests. On some platforms, this function @@ -186,38 +186,38 @@ fails if the file in question is being held open. `path`: The absolute path of the file, symlink, or directory to be deleted. -#### Declaration #### +#### Declaration ``` bool SbFileDelete(const char *path) ``` -### SbFileExists ### +### SbFileExists Indicates whether a file or directory exists at `path`. `path`: The absolute path of the file or directory being checked. -#### Declaration #### +#### Declaration ``` bool SbFileExists(const char *path) ``` -### SbFileFlush ### +### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed. `file`: The SbFile to which the write buffer is flushed. -#### Declaration #### +#### Declaration ``` bool SbFileFlush(SbFile file) ``` -### SbFileGetInfo ### +### SbFileGetInfo Retrieves information about `file`. The return value indicates whether the file information was retrieved successfully. @@ -226,13 +226,13 @@ information was retrieved successfully. into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetInfo(SbFile file, SbFileInfo *out_info) ``` -### SbFileGetPathInfo ### +### SbFileGetPathInfo Retrieves information about the file at `path`. The return value indicates whether the file information was retrieved successfully. @@ -241,36 +241,36 @@ whether the file information was retrieved successfully. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info) ``` -### SbFileIsValid ### +### SbFileIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbFileIsValid(SbFile file) ``` -### SbFileModeStringToFlags ### +### SbFileModeStringToFlags Converts an ISO `fopen()` mode string into flags that can be equivalently passed into SbFileOpen(). `mode`: The mode string to be converted into flags. -#### Declaration #### +#### Declaration ``` int SbFileModeStringToFlags(const char *mode) ``` -### SbFileOpen ### +### SbFileOpen Opens the file at `path`, which must be absolute, creating it if specified by `flags`. The read/write position is at the beginning of the file. @@ -287,13 +287,13 @@ which can happen if the `kSbFileCreateAlways` flag is set. Otherwise, Starboard sets this value to `false`. `out_error`: If `path` cannot be created, this is set to `kSbFileInvalid`. Otherwise, it is `NULL`. -#### Declaration #### +#### Declaration ``` SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error) ``` -### SbFileRead ### +### SbFileRead Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -306,13 +306,13 @@ However, this function can be run in a loop to make it a best-effort read. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` int SbFileRead(SbFile file, char *data, int size) ``` -### SbFileReadAll ### +### SbFileReadAll Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -326,13 +326,13 @@ be read unless there is an error. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` static int SbFileReadAll(SbFile file, char *data, int size) ``` -### SbFileSeek ### +### SbFileSeek Changes the current read/write position in `file`. The return value identifies the resultant current read/write position in the file (relative to the start) or @@ -344,13 +344,13 @@ The starting read/write position. The position is modified relative to this value. `offset`: The amount that the read/write position is changed, relative to `whence`. -#### Declaration #### +#### Declaration ``` int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset) ``` -### SbFileTruncate ### +### SbFileTruncate Truncates the given `file` to the given `length`. The return value indicates whether the file was truncated successfully. @@ -360,13 +360,13 @@ after it is truncated. If `length` is greater than the current size of the file, then the file is extended with zeros. If `length` is negative, then the function is a no-op and returns `false`. -#### Declaration #### +#### Declaration ``` bool SbFileTruncate(SbFile file, int64_t length) ``` -### SbFileWrite ### +### SbFileWrite Writes the given buffer into `file` at the file's current position, overwriting any data that was previously there. @@ -380,13 +380,13 @@ in a loop to ensure that all data is written. `file`: The SbFile to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` int SbFileWrite(SbFile file, const char *data, int size) ``` -### SbFileWriteAll ### +### SbFileWriteAll Writes the given buffer into `file`, starting at the beginning of the file, and overwriting any data that was previously there. Unlike SbFileWrite, this @@ -397,7 +397,7 @@ The return value identifies the number of bytes written, or `-1` on error. `file`: The file to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` 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 163d8d76aa41..77bc07e71c82 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/14/gles.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: gles.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `gles.h` The GLES API provides an interface with accompanying type declarations and defines that together provide a single consistent method of GLES usage across @@ -11,37 +11,37 @@ 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 the functions from GLES 3.0 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_GL_DEPTH_BUFFER_BIT ### +### SB_GL_DEPTH_BUFFER_BIT Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) -### SB_GL_READ_BUFFER ### +### SB_GL_READ_BUFFER Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h](https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h) . -## Typedefs ## +## Typedefs -### SbGlBoolean ### +### SbGlBoolean The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) . -#### Definition #### +#### Definition ``` typedef uint8_t SbGlBoolean ``` -### SbGlIntPtr ### +### SbGlIntPtr Some compilers will transform the intptr_t to an int transparently behind the scenes, which is not equivalent to a long int, or long long int, as far as the @@ -49,17 +49,17 @@ compiler is concerned. We check the Starboard configuration and set the types to those exact types used by OpenGL ES 2.0 ( [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h) ). -#### Definition #### +#### Definition ``` typedef long int SbGlIntPtr ``` -## Structs ## +## Structs -### SbGlesInterface ### +### SbGlesInterface -#### Members #### +#### Members * `void(*glActiveTexture)(SbGlEnum texture)` diff --git a/cobalt/site/docs/reference/starboard/modules/14/image.md b/cobalt/site/docs/reference/starboard/modules/14/image.md index 1427d3995d54..945938a09903 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/image.md +++ b/cobalt/site/docs/reference/starboard/modules/14/image.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: image.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `image.h` API for hardware accelerated image decoding. This module allows for the client to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It @@ -11,7 +11,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(); @@ -28,9 +28,9 @@ SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); ``` -## Functions ## +## Functions -### SbImageDecode ### +### SbImageDecode Attempt to decode encoded `mime_type` image data `data` of size `data_size` into an SbDecodeTarget of SbDecodeFormatType `format`, possibly using @@ -56,13 +56,13 @@ scenarios regarding the provider may happen: kSbDecodeTargetInvalid will be returned, with any intermediate allocations being cleaned up in the implementation. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) ``` -### SbImageIsDecodeSupported ### +### SbImageIsDecodeSupported Whether the current platform supports hardware accelerated decoding an image of mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must @@ -70,7 +70,7 @@ not be NULL. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. -#### Declaration #### +#### Declaration ``` 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 ec86793b7761..a858c73e3e89 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/input.md +++ b/cobalt/site/docs/reference/starboard/modules/14/input.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: input.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `input.h` Defines input events and associated data types. -## Enums ## +## Enums -### SbInputDeviceType ### +### SbInputDeviceType Identifies possible input subsystem types. The types of events that each device type produces correspond to `SbInputEventType` values. -#### Values #### +#### Values * `kSbInputDeviceTypeGesture` @@ -57,11 +57,11 @@ type produces correspond to `SbInputEventType` values. Produces `Input` events. -### SbInputEventType ### +### SbInputEventType The action that an input event represents. -#### Values #### +#### Values * `kSbInputEventTypeMove` @@ -86,13 +86,13 @@ The action that an input event represents. [https://w3c.github.io/uievents/#event-type-input](https://w3c.github.io/uievents/#event-type-input) -## Structs ## +## Structs -### SbInputData ### +### SbInputData Event data for `kSbEventTypeInput` events. -#### Members #### +#### Members * `SbWindow window` @@ -160,11 +160,11 @@ Event data for `kSbEventTypeInput` events. Set to true if the input event is part of a composition event. -### SbInputVector ### +### SbInputVector A 2-dimensional vector used to represent points and motion vectors. -#### Members #### +#### Members * `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 bf8583c2d7eb..dd7712fd81bb 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/key.md +++ b/cobalt/site/docs/reference/starboard/modules/14/key.md @@ -1,19 +1,19 @@ ---- -layout: doc -title: "Starboard Module Reference: key.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `key.h` Defines the canonical set of Starboard key codes. -## Enums ## +## Enums -### SbKey ### +### SbKey A standard set of key codes, ordered by value, that represent each possible input key across all kinds of devices. Starboard uses the semi-standard Windows virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx) -#### Values #### +#### Values * `kSbKeyUnknown` * `kSbKeyCancel` @@ -274,11 +274,11 @@ virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windo * `kSbKeyGamepadRightStickLeft` * `kSbKeyGamepadRightStickRight` -### SbKeyModifiers ### +### SbKeyModifiers Bit-mask of key modifiers. -#### Values #### +#### Values * `kSbKeyModifiersNone` * `kSbKeyModifiersAlt` diff --git a/cobalt/site/docs/reference/starboard/modules/14/log.md b/cobalt/site/docs/reference/starboard/modules/14/log.md index 42de5138c303..6cf3a491a2a7 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/log.md +++ b/cobalt/site/docs/reference/starboard/modules/14/log.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: log.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `log.h` Defines core debug logging functions. -## Enums ## +## Enums -### SbLogPriority ### +### SbLogPriority The priority at which a message should be logged. The platform may be configured to filter logs by priority, or render them differently. -#### Values #### +#### Values * `kSbLogPriorityUnknown` * `kSbLogPriorityInfo` @@ -20,9 +20,9 @@ to filter logs by priority, or render them differently. * `kSbLogPriorityError` * `kSbLogPriorityFatal` -## Functions ## +## Functions -### SbLog ### +### SbLog Writes `message` to the platform's debug output log. This method is thread-safe, and responsible for ensuring that the output from multiple threads is not mixed. @@ -35,55 +35,55 @@ NULL. No formatting is required to be done on the value, including newline termination. That said, platforms can adjust the message to be more suitable for their output method by wrapping the text, stripping unprintable characters, etc. -#### Declaration #### +#### Declaration ``` void SbLog(SbLogPriority priority, const char *message) ``` -### SbLogFlush ### +### SbLogFlush Flushes the log buffer on some platforms. This method is safe to call from multiple threads. -#### Declaration #### +#### Declaration ``` void SbLogFlush() ``` -### SbLogFormat ### +### SbLogFormat A log output method that additionally performs a string format on the data being logged. -#### Declaration #### +#### Declaration ``` void SbLogFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogFormatF ### +### SbLogFormatF Inline wrapper of SbLogFormat that converts from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` void static void static void SbLogFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` -### SbLogIsTty ### +### SbLogIsTty Indicates whether the log output goes to a TTY or is being redirected. -#### Declaration #### +#### Declaration ``` bool SbLogIsTty() ``` -### SbLogRaw ### +### SbLogRaw A bare-bones log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). It should not do any @@ -91,13 +91,13 @@ additional formatting. `message`: The message to be logged. Must not be NULL. -#### Declaration #### +#### Declaration ``` void SbLogRaw(const char *message) ``` -### SbLogRawDumpStack ### +### SbLogRawDumpStack Dumps the stack of the current thread to the log in an async-signal-safe manner, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` @@ -108,28 +108,28 @@ dumping the current thread to the log. This parameter lets you remove noise from helper functions that might end up on top of every stack dump so that the stack dump is just the relevant function stack where the problem occurred. -#### Declaration #### +#### Declaration ``` void SbLogRawDumpStack(int frames_to_skip) ``` -### SbLogRawFormat ### +### SbLogRawFormat A formatted log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). -#### Declaration #### +#### Declaration ``` void SbLogRawFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogRawFormatF ### +### SbLogRawFormatF Inline wrapper of SbLogFormat to convert from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` 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 f7ccacdb3cba..e6202bf8e0bd 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/media.md +++ b/cobalt/site/docs/reference/starboard/modules/14/media.md @@ -1,28 +1,28 @@ ---- -layout: doc -title: "Starboard Module Reference: media.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `media.h` Provides media definitions that are common between the Decoder and Player interfaces. -## Macros ## +## Macros -### kSbMediaBitsPerPixelInvalid ### +### kSbMediaBitsPerPixelInvalid Value used when a video's bits per pixel is not known. -### kSbMediaVideoResolutionDimensionInvalid ### +### kSbMediaVideoResolutionDimensionInvalid Value used when a video's resolution is not known. -## Enums ## +## Enums -### SbMediaAudioCodec ### +### SbMediaAudioCodec Types of audio elementary streams that can be supported. -#### Values #### +#### Values * `kSbMediaAudioCodecNone` * `kSbMediaAudioCodecAac` @@ -34,11 +34,11 @@ Types of audio elementary streams that can be supported. * `kSbMediaAudioCodecFlac` * `kSbMediaAudioCodecPcm` -### SbMediaAudioCodingType ### +### SbMediaAudioCodingType Possible audio coding types. -#### Values #### +#### Values * `kSbMediaAudioCodingTypeNone` * `kSbMediaAudioCodingTypeAac` @@ -52,11 +52,11 @@ Possible audio coding types. * `kSbMediaAudioCodingTypeMpeg3` * `kSbMediaAudioCodingTypePcm` -### SbMediaAudioConnector ### +### SbMediaAudioConnector Possible audio connector types. -#### Values #### +#### Values * `kSbMediaAudioConnectorNone` * `kSbMediaAudioConnectorAnalog` @@ -66,11 +66,11 @@ Possible audio connector types. * `kSbMediaAudioConnectorSpdif` * `kSbMediaAudioConnectorUsb` -### SbMediaAudioFrameStorageType ### +### SbMediaAudioFrameStorageType Possible audio frame storage types. -#### Values #### +#### Values * `kSbMediaAudioFrameStorageTypeInterleaved` @@ -86,22 +86,22 @@ Possible audio frame storage types. with timestamps 0, 1, 2, etc., the samples are stored in two buffers "L0 L1 L2 ..." and "R0 R1 R2 ...". -### SbMediaAudioSampleType ### +### SbMediaAudioSampleType Possible audio sample types. -#### Values #### +#### Values * `kSbMediaAudioSampleTypeInt16Deprecated` * `kSbMediaAudioSampleTypeFloat32` -### SbMediaRangeId ### +### SbMediaRangeId This corresponds to the WebM Range enum which is part of WebM color data (see [http://www.webmproject.org/docs/container/#Range](http://www.webmproject.org/docs/container/#Range) ). H.264 only uses a bool, which corresponds to the LIMITED/FULL values. Chrome- specific values start at 1000. -#### Values #### +#### Values * `kSbMediaRangeIdUnspecified` @@ -117,13 +117,13 @@ specific values start at 1000. Range is defined by TransferId/MatrixId. * `kSbMediaRangeIdLast` -### SbMediaSupportType ### +### SbMediaSupportType Indicates how confident the device is that it can play media resources of the given type. The values are a direct map of the canPlayType() method specified at the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype](https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype) -#### Values #### +#### Values * `kSbMediaSupportTypeNotSupported` @@ -135,11 +135,11 @@ the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom The media type seems to be playable. -### SbMediaType ### +### SbMediaType Types of media component streams. -#### Values #### +#### Values * `kSbMediaTypeAudio` @@ -148,11 +148,11 @@ Types of media component streams. Value used for video streams. -### SbMediaVideoCodec ### +### SbMediaVideoCodec Types of video elementary streams that could be supported. -#### Values #### +#### Values * `kSbMediaVideoCodecNone` * `kSbMediaVideoCodecH264` @@ -164,14 +164,14 @@ Types of video elementary streams that could be supported. * `kSbMediaVideoCodecVp8` * `kSbMediaVideoCodecVp9` -## Structs ## +## Structs -### SbMediaAudioConfiguration ### +### SbMediaAudioConfiguration A structure describing the audio configuration parameters of a single audio output. -#### Members #### +#### Members * `int index` @@ -193,7 +193,7 @@ output. `0` if this device cannot provide this information, in which case the caller can probably assume stereo output. -### SbMediaAudioSampleInfo ### +### SbMediaAudioSampleInfo An audio sample info, which is a description of a given audio sample. This acts as a set of instructions to the audio decoder. @@ -203,7 +203,7 @@ structure, as well as other information for the audio decoder, including the Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at [http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx](http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx)x) . -#### Members #### +#### Members * `SbMediaAudioCodec codec` @@ -238,14 +238,14 @@ Audio-specific configuration field. The `WAVEFORMATEX` structure is specified at The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1: [http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF](http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF) -### SbMediaColorMetadata ### +### SbMediaColorMetadata HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR formats, together with the ColorSpace. HDR reproduces a greater dynamic range of luminosity than is possible with standard digital imaging. See the Consumer Electronics Association press release: [https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) -#### Members #### +#### Members * `unsigned int bits_per_channel` @@ -326,7 +326,7 @@ Electronics Association press release: [https://www.cta.tech/News/Press-Releases a row-major ordered 3 x 4 submatrix of the 4 x 4 transform matrix. The 4th row is completed as (0, 0, 0, 1). -### SbMediaMasteringMetadata ### +### SbMediaMasteringMetadata SMPTE 2086 mastering data [http://ieeexplore.ieee.org/document/7291707/](http://ieeexplore.ieee.org/document/7291707/) This standard specifies the metadata items to specify the color volume (the @@ -335,7 +335,7 @@ in mastering video content. The metadata is specified as a set of values independent of any specific digital representation. Also see the WebM container guidelines: [https://www.webmproject.org/docs/container/](https://www.webmproject.org/docs/container/) -#### Members #### +#### Members * `float primary_r_chromaticity_x` @@ -370,11 +370,11 @@ guidelines: [https://www.webmproject.org/docs/container/](https://www.webmprojec Minimum luminance. Shall be represented in candelas per square meter (cd/m^2). In range [0, 9999.99]. -### SbMediaVideoSampleInfo ### +### SbMediaVideoSampleInfo The set of information required by the decoder or player for each video sample. -#### Members #### +#### Members * `SbMediaVideoCodec codec` @@ -420,9 +420,9 @@ The set of information required by the decoder or player for each video sample. . This will only be specified on frames where the HDR metadata and color / color space might have changed (e.g. keyframes). -## Functions ## +## Functions -### SbMediaCanPlayMimeAndKeySystem ### +### SbMediaCanPlayMimeAndKeySystem Returns information about whether the playback of the specific media described by `mime` and encrypted using `key_system` can be played. @@ -466,13 +466,13 @@ return `kSbMediaSupportTypeProbably` kSbMediaSupportTypeProbably when implementation supports key system with attributes on one key system, it has to support key system with attributes on all key systems supported. -#### Declaration #### +#### Declaration ``` SbMediaSupportType SbMediaCanPlayMimeAndKeySystem(const char *mime, const char *key_system) ``` -### SbMediaGetAudioBufferBudget ### +### SbMediaGetAudioBufferBudget Specifies the maximum amount of memory used by audio buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -480,13 +480,13 @@ being used by audio buffers but will also make the app less likely to re- download audio data. Note that the app may experience significant difficulty if this value is too low. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioBufferBudget() ``` -### SbMediaGetAudioConfiguration ### +### SbMediaGetAudioConfiguration Retrieves the current physical audio configuration of audio output `output_index` on this device and places it in `out_configuration`, which must @@ -498,37 +498,37 @@ if `output_index` does not exist on this device. `out_configuration`: The variable that holds the audio configuration information. -#### Declaration #### +#### Declaration ``` bool SbMediaGetAudioConfiguration(int output_index, SbMediaAudioConfiguration *out_configuration) ``` -### SbMediaGetAudioOutputCount ### +### SbMediaGetAudioOutputCount Returns the number of audio outputs currently available on this device. Even if the number of outputs or their audio configurations can't be determined, it is expected that the platform will at least return a single output that supports at least stereo. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioOutputCount() ``` -### SbMediaGetBufferAlignment ### +### 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 #### +#### Declaration ``` int SbMediaGetBufferAlignment() ``` -### SbMediaGetBufferAllocationUnit ### +### SbMediaGetBufferAllocationUnit When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can @@ -536,13 +536,13 @@ 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferAllocationUnit() ``` -### SbMediaGetBufferGarbageCollectionDurationThreshold ### +### SbMediaGetBufferGarbageCollectionDurationThreshold Specifies the duration threshold of media source garbage collection. When the accumulated duration in a source buffer exceeds this value, the media source @@ -553,25 +553,25 @@ 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 #### +#### Declaration ``` SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() ``` -### SbMediaGetBufferPadding ### +### 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferPadding() ``` -### SbMediaGetBufferStorageType ### +### SbMediaGetBufferStorageType Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored @@ -581,26 +581,26 @@ by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when its value is "file" the media stack will still allocate memory to cache the the buffers in use. -#### Declaration #### +#### Declaration ``` SbMediaBufferStorageType SbMediaGetBufferStorageType() ``` -### SbMediaGetInitialBufferCapacity ### +### SbMediaGetInitialBufferCapacity The amount of memory that will be used to store media buffers allocated during system startup. To allocate a large chunk at startup helps with reducing fragmentation and can avoid failures to allocate incrementally. This can return 0. -#### Declaration #### +#### Declaration ``` int SbMediaGetInitialBufferCapacity() ``` -### SbMediaGetMaxBufferCapacity ### +### SbMediaGetMaxBufferCapacity The maximum amount of memory that will be used to store media buffers. This must be larger than sum of the video budget and audio budget. This is a soft limit @@ -615,13 +615,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetProgressiveBufferBudget ### +### SbMediaGetProgressiveBufferBudget The memory used when playing mp4 videos that is not in DASH format. The resolution of such videos shouldn't go beyond 1080p. Its value should be less @@ -633,13 +633,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetVideoBufferBudget ### +### SbMediaGetVideoBufferBudget Specifies the maximum amount of memory used by video buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -652,13 +652,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaIsBufferPoolAllocateOnDemand ### +### SbMediaIsBufferPoolAllocateOnDemand When either SbMediaGetInitialBufferCapacity or SbMediaGetBufferAllocationUnit isn't zero, media buffers will be allocated using a memory pool. Set the @@ -669,24 +669,24 @@ SbMediaGetInitialBufferCapacity bytes for media buffer on startup and will not release any media buffer memory back to the system even if there is no media buffers allocated. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferPoolAllocateOnDemand() ``` -### SbMediaIsBufferUsingMemoryPool ### +### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer pools should be allocated on demand, as opposed to using SbMemory* functions. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferUsingMemoryPool() ``` -### SbMediaSetAudioWriteDuration ### +### SbMediaSetAudioWriteDuration Communicate to the platform how far past `current_playback_position` the app will write audio samples. The app will write all samples between @@ -698,7 +698,7 @@ in general. The platform is responsible for guaranteeing that when only as transient or indefinite hanging). The platform may assume `duration` >= 0.5 seconds. -#### Declaration #### +#### Declaration ``` void SbMediaSetAudioWriteDuration(SbTime duration) diff --git a/cobalt/site/docs/reference/starboard/modules/14/memory.md b/cobalt/site/docs/reference/starboard/modules/14/memory.md index a094a66ff135..22b80168adbc 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/14/memory.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: memory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. -## Porters ## +## 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 @@ -26,14 +26,14 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. * The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). -## Enums ## +## Enums -### SbMemoryMapFlags ### +### SbMemoryMapFlags The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used. -#### Values #### +#### Values * `kSbMemoryMapProtectReserved` @@ -44,9 +44,9 @@ the mapped memory can be used. * `kSbMemoryMapProtectExec` * `kSbMemoryMapProtectReadWrite` -## Functions ## +## Functions -### SbMemoryAllocate ### +### SbMemoryAllocate Allocates and returns a chunk of memory of at least `size` bytes. This function should be called from the client codebase. It is intended to be a drop-in @@ -58,13 +58,13 @@ Note that this function returns `NULL` if it is unable to allocate the memory. return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocate(size_t size) ``` -### SbMemoryAllocateAligned ### +### SbMemoryAllocateAligned Allocates and returns a chunk of memory of at least `size` bytes, aligned to `alignment`. This function should be called from the client codebase. It is @@ -78,87 +78,87 @@ must be a power of two. `size`: The size of the memory to be allocated. If `size` is `0`, the function may return `NULL` or it may return a unique aligned pointer value that can be passed to SbMemoryDeallocateAligned. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAligned(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedChecked ### +### SbMemoryAllocateAlignedChecked Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedUnchecked ### +### SbMemoryAllocateAlignedUnchecked This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateChecked ### +### SbMemoryAllocateChecked Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateChecked(size_t size) ``` -### SbMemoryAllocateNoReport ### +### SbMemoryAllocateNoReport Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateNoReport(size_t size) ``` -### SbMemoryAllocateUnchecked ### +### SbMemoryAllocateUnchecked This is the implementation of SbMemoryAllocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateUnchecked(size_t size) ``` -### SbMemoryCalloc ### +### SbMemoryCalloc A wrapper that implements a drop-in replacement for `calloc`, which is used in some packages. -#### Declaration #### +#### Declaration ``` static void* SbMemoryCalloc(size_t count, size_t size) ``` -### SbMemoryDeallocate ### +### SbMemoryDeallocate Frees a previously allocated chunk of memory. If `memory` is NULL, then the operation is a no-op. This function should be called from the client codebase. @@ -166,87 +166,87 @@ It is meant to be a drop-in replacement for `free`. `memory`: The chunk of memory to be freed. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocate(void *memory) ``` -### SbMemoryDeallocateAligned ### +### SbMemoryDeallocateAligned `memory`: The chunk of memory to be freed. If `memory` is NULL, then the function is a no-op. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateAligned(void *memory) ``` -### SbMemoryDeallocateNoReport ### +### SbMemoryDeallocateNoReport Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport(). -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateNoReport(void *memory) ``` -### SbMemoryFlush ### +### SbMemoryFlush Flushes any data in the given virtual address range that is cached locally in the current processor core to physical memory, ensuring that data and instruction caches are cleared. This is required to be called on executable memory that has been written to and might be executed in the future. -#### Declaration #### +#### Declaration ``` void SbMemoryFlush(void *virtual_address, int64_t size_bytes) ``` -### SbMemoryFree ### +### SbMemoryFree This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocate(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFree(void *memory) ``` -### SbMemoryFreeAligned ### +### SbMemoryFreeAligned This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFreeAligned(void *memory) ``` -### SbMemoryGetStackBounds ### +### SbMemoryGetStackBounds Gets the stack bounds for the current thread. `out_high`: The highest addressable byte + 1 for the current thread. `out_low`: The lowest addressable byte for the current thread. -#### Declaration #### +#### Declaration ``` void SbMemoryGetStackBounds(void **out_high, void **out_low) ``` -### SbMemoryMap ### +### SbMemoryMap Allocates `size_bytes` worth of physical memory pages and maps them into an available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on @@ -261,24 +261,24 @@ used, the address space will not be accessible and, if possible, the platform should not count it against any memory budget. `name`: A value that appears in the debugger on some platforms. The value can be up to 32 bytes. -#### Declaration #### +#### Declaration ``` void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) ``` -### SbMemoryProtect ### +### SbMemoryProtect Change the protection of `size_bytes` of memory regions, starting from `virtual_address`, to `flags`, returning `true` on success. -#### Declaration #### +#### Declaration ``` bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) ``` -### SbMemoryReallocate ### +### SbMemoryReallocate Attempts to resize `memory` to be at least `size` bytes, without touching the contents of memory. @@ -298,39 +298,39 @@ it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which `memory` will be resized. If `size` is `0`, the function may return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocate(void *memory, size_t size) ``` -### SbMemoryReallocateChecked ### +### SbMemoryReallocateChecked Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateChecked(void *memory, size_t size) ``` -### SbMemoryReallocateUnchecked ### +### SbMemoryReallocateUnchecked This is the implementation of SbMemoryReallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateUnchecked(void *memory, size_t size) ``` -### SbMemoryUnmap ### +### SbMemoryUnmap Unmap `size_bytes` of physical pages starting from `virtual_address`, returning `true` on success. After this function completes, [virtual_address, @@ -340,7 +340,7 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns `(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns `(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. -#### Declaration #### +#### Declaration ``` 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 d67ef1aada3e..d1273c6cfc50 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md +++ b/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md @@ -1,57 +1,57 @@ ---- -layout: doc -title: "Starboard Module Reference: memory_reporter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory_reporter.h` Provides an interface for memory reporting. -## Typedefs ## +## Typedefs -### SbMemoryReporterOnAlloc ### +### SbMemoryReporterOnAlloc A function to report a memory allocation from SbMemoryAllocate(). Note that operator new calls SbMemoryAllocate which will delegate to this callback. -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnAlloc) (void *context, const void *memory, size_t size) ``` -### SbMemoryReporterOnDealloc ### +### SbMemoryReporterOnDealloc A function to report a memory deallocation from SbMemoryDeallcoate(). Note that operator delete calls SbMemoryDeallocate which will delegate to this callback. -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnDealloc) (void *context, const void *memory) ``` -### SbMemoryReporterOnMapMemory ### +### SbMemoryReporterOnMapMemory A function to report a memory mapping from SbMemoryMap(). -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnMapMemory) (void *context, const void *memory, size_t size) ``` -### SbMemoryReporterOnUnMapMemory ### +### SbMemoryReporterOnUnMapMemory A function to report a memory unmapping from SbMemoryUnmap(). -#### Definition #### +#### Definition ``` typedef void(* SbMemoryReporterOnUnMapMemory) (void *context, const void *memory, size_t size) ``` -## Structs ## +## Structs -### SbMemoryReporter ### +### 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 @@ -59,7 +59,7 @@ struct initialization is used so that the arguments can be typed check by the compiler. For example, SbMemoryReporter mem_reporter = { MallocCallback, .... context }; -#### Members #### +#### Members * `SbMemoryReporterOnAlloc on_alloc_cb` @@ -77,9 +77,9 @@ context }; Optional, is passed to callbacks as first argument. -## Functions ## +## Functions -### SbMemorySetReporter ### +### SbMemorySetReporter Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime management is done internally on input pointer. @@ -96,7 +96,7 @@ SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); SbMemoryReporter* mem_reporter = new ...; SbMemorySetReporter(&mem_reporter); ... SbMemorySetReporter(NULL); delete mem_reporter; // May crash. -#### Declaration #### +#### Declaration ``` 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 d760e1e7533f..bcf9e4355e65 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/14/microphone.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: microphone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `microphone.h` Defines functions for microphone creation, control, audio data fetching, and destruction. This module supports multiple calls to `SbMicrophoneOpen` and @@ -31,23 +31,23 @@ How to use this API: 1. Destroy the microphone with `SbMicrophoneDestroy`. -## Macros ## +## Macros -### kSbMicrophoneIdInvalid ### +### kSbMicrophoneIdInvalid Well-defined value for an invalid microphone ID handle. -### kSbMicrophoneInvalid ### +### kSbMicrophoneInvalid Well-defined value for an invalid microphone handle. -## Enums ## +## Enums -### SbMicrophoneType ### +### SbMicrophoneType All possible microphone types. -#### Values #### +#### Values * `kSbMicrophoneCamera` @@ -66,37 +66,37 @@ All possible microphone types. Unknown microphone type. The microphone could be different than the other enum descriptions or could fall under one of those descriptions. -## Typedefs ## +## Typedefs -### SbMicrophone ### +### SbMicrophone An opaque handle to an implementation-private structure that represents a microphone. -#### Definition #### +#### Definition ``` typedef struct SbMicrophonePrivate* SbMicrophone ``` -### SbMicrophoneId ### +### SbMicrophoneId An opaque handle to an implementation-private structure that represents a microphone ID. -#### Definition #### +#### Definition ``` typedef struct SbMicrophoneIdPrivate* SbMicrophoneId ``` -## Structs ## +## Structs -### SbMicrophoneInfo ### +### SbMicrophoneInfo Microphone information. -#### Members #### +#### Members * `SbMicrophoneId id` @@ -116,9 +116,9 @@ Microphone information. of the microphone type. For example, "Headset Microphone". The string must be null terminated. -## Functions ## +## Functions -### SbMicrophoneClose ### +### SbMicrophoneClose Closes the microphone port, stops recording audio on `microphone`, and clears the unread buffer if it is not empty. If the microphone has already been @@ -127,13 +127,13 @@ is closed. `microphone`: The microphone to close. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneClose(SbMicrophone microphone) ``` -### SbMicrophoneCreate ### +### SbMicrophoneCreate Creates a microphone with the specified ID, audio sample rate, and cached audio buffer size. Starboard only requires support for creating one microphone at a @@ -153,25 +153,25 @@ from the audio buffer if it has been read, and new audio data can be read from this buffer in smaller chunks than this size. This parameter must be set to a value greater than zero and the ideal size is `2^n`. -#### Declaration #### +#### Declaration ``` SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size_bytes) ``` -### SbMicrophoneDestroy ### +### SbMicrophoneDestroy Destroys a microphone. If the microphone is in started state, it is first stopped and then destroyed. Any data that has been recorded and not read is thrown away. -#### Declaration #### +#### Declaration ``` void SbMicrophoneDestroy(SbMicrophone microphone) ``` -### SbMicrophoneGetAvailable ### +### SbMicrophoneGetAvailable Retrieves all currently available microphone information and stores it in `out_info_array`. The return value is the number of the available microphones. @@ -184,43 +184,43 @@ indicates that an internal error occurred. placed into this output parameter. `info_array_size`: The size of `out_info_array`. -#### Declaration #### +#### Declaration ``` int SbMicrophoneGetAvailable(SbMicrophoneInfo *out_info_array, int info_array_size) ``` -### SbMicrophoneIdIsValid ### +### SbMicrophoneIdIsValid Indicates whether the given microphone ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIdIsValid(SbMicrophoneId id) ``` -### SbMicrophoneIsSampleRateSupported ### +### SbMicrophoneIsSampleRateSupported Indicates whether the microphone supports the sample rate. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz) ``` -### SbMicrophoneIsValid ### +### SbMicrophoneIsValid Indicates whether the given microphone is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIsValid(SbMicrophone microphone) ``` -### SbMicrophoneOpen ### +### SbMicrophoneOpen Opens the microphone port and starts recording audio on `microphone`. @@ -230,13 +230,13 @@ clears the unread buffer. The return value indicates whether the microphone is open. `microphone`: The microphone that will be opened and will start recording audio. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneOpen(SbMicrophone microphone) ``` -### SbMicrophoneRead ### +### SbMicrophoneRead Retrieves the recorded audio data from the microphone and writes that data to `out_audio_data`. @@ -255,7 +255,7 @@ audio data is thrown out. No audio data is read from a stopped microphone. smaller than `min_read_size` of `SbMicrophoneInfo`, the extra audio data that has already been read from the device is discarded. -#### Declaration #### +#### Declaration ``` 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 05dd810c1f94..82ff8500ab8d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/14/mutex.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: mutex.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `mutex.h` Defines a mutually exclusive lock that can be used to coordinate with other threads. -## Macros ## +## Macros -### SB_MUTEX_MAX_SIZE ### +### SB_MUTEX_MAX_SIZE Max size of the SbMutex type. -## Enums ## +## Enums -### SbMutexResult ### +### SbMutexResult Enumeration of possible results from acquiring a mutex. -#### Values #### +#### Values * `kSbMutexAcquired` @@ -30,22 +30,22 @@ Enumeration of possible results from acquiring a mutex. The mutex has already been destroyed. -## Typedefs ## +## Typedefs -### SbMutex ### +### SbMutex An opaque handle to a mutex type with reserved memory buffer of size SB_MUTEX_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbMutex SbMutex ``` -## Functions ## +## Functions -### SbMutexAcquire ### +### SbMutexAcquire Acquires `mutex`, blocking indefinitely. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition @@ -53,13 +53,13 @@ blocks forever. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquire(SbMutex *mutex) ``` -### SbMutexAcquireTry ### +### SbMutexAcquireTry Acquires `mutex`, without blocking. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition has undefined @@ -67,52 +67,52 @@ behavior. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquireTry(SbMutex *mutex) ``` -### SbMutexCreate ### +### SbMutexCreate Creates a new mutex. The return value indicates whether the function was able to create a new mutex. `out_mutex`: The handle to the newly created mutex. -#### Declaration #### +#### Declaration ``` bool SbMutexCreate(SbMutex *out_mutex) ``` -### SbMutexDestroy ### +### SbMutexDestroy Destroys a mutex. The return value indicates whether the destruction was successful. Destroying a locked mutex results in undefined behavior. `mutex`: The mutex to be invalidated. -#### Declaration #### +#### Declaration ``` bool SbMutexDestroy(SbMutex *mutex) ``` -### SbMutexIsSuccess ### +### SbMutexIsSuccess Indicates whether the given result is a success. A value of `true` indicates that the mutex was acquired. `result`: The result being checked. -#### Declaration #### +#### Declaration ``` static bool SbMutexIsSuccess(SbMutexResult result) ``` -### SbMutexRelease ### +### SbMutexRelease Releases `mutex` held by the current thread. The return value indicates whether the release was successful. Releases should always be successful if `mutex` is @@ -120,7 +120,7 @@ held by the current thread. `mutex`: The mutex to be released. -#### Declaration #### +#### Declaration ``` 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 2ad1959cd50e..d77302467f8b 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/once.md +++ b/cobalt/site/docs/reference/starboard/modules/14/once.md @@ -1,43 +1,43 @@ ---- -layout: doc -title: "Starboard Module Reference: once.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `once.h` Onces represent initializations that should only ever happen once per process, in a thread-safe way. -## Macros ## +## Macros -### SB_ONCE_MAX_SIZE ### +### SB_ONCE_MAX_SIZE Max size of the SbOnceControl type. -## Typedefs ## +## Typedefs -### SbOnceControl ### +### SbOnceControl An opaque handle to a once control type with reserved memory buffer of size SB_ONCE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbOnceControl SbOnceControl ``` -### SbOnceInitRoutine ### +### SbOnceInitRoutine Function pointer type for methods that can be called via the SbOnce() system. -#### Definition #### +#### Definition ``` typedef void(* SbOnceInitRoutine) (void) ``` -## Functions ## +## Functions -### SbOnce ### +### SbOnce Thread-safely runs `init_routine` only once. @@ -50,7 +50,7 @@ Thread-safely runs `init_routine` only once. * If `once_control` or `init_routine` is invalid, the function returns `false`. -#### Declaration #### +#### Declaration ``` 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 3fd955dfe85c..807597d4be20 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/player.md +++ b/cobalt/site/docs/reference/starboard/modules/14/player.md @@ -1,45 +1,45 @@ ---- -layout: doc -title: "Starboard Module Reference: player.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `player.h` Defines an interface for controlling playback of media elementary streams. -## Macros ## +## Macros -### SB_PLAYER_INITIAL_TICKET ### +### SB_PLAYER_INITIAL_TICKET The value of the initial ticket held by the player before the first seek. The player will use this ticket value to make the first call to SbPlayerStatusFunc with kSbPlayerStateInitialized. -### SB_PLAYER_NO_DURATION ### +### SB_PLAYER_NO_DURATION The value to pass into SbPlayerCreate's `duration_pts` argument for cases where the duration is unknown, such as for live streams. -### kSbPlayerInvalid ### +### kSbPlayerInvalid Well-defined value for an invalid player. -## Enums ## +## Enums -### SbPlayerDecoderState ### +### SbPlayerDecoderState An indicator of whether the decoder can accept more samples. -#### Values #### +#### Values * `kSbPlayerDecoderStateNeedsData` The decoder is asking for one more sample. -### SbPlayerSampleSideDataType ### +### SbPlayerSampleSideDataType Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side data may come from multiple sources. -#### Values #### +#### Values * `kMatroskaBlockAdditional` @@ -48,11 +48,11 @@ data may come from multiple sources. . The first 8 bytes of the data contains the value of BlockAddID in big endian format, followed by the content of BlockAdditional. -### SbPlayerState ### +### SbPlayerState An indicator of the general playback state. -#### Values #### +#### Values * `kSbPlayerStateInitialized` @@ -76,31 +76,31 @@ An indicator of the general playback state. The player has been destroyed, and will send no more callbacks. -## Typedefs ## +## Typedefs -### SbPlayer ### +### SbPlayer An opaque handle to an implementation-private structure representing a player. -#### Definition #### +#### Definition ``` typedef struct SbPlayerPrivate* SbPlayer ``` -### SbPlayerDeallocateSampleFunc ### +### SbPlayerDeallocateSampleFunc Callback to free the given sample buffer data. When more than one buffer are sent in SbPlayerWriteSample(), the implementation only has to call this callback with `sample_buffer` points to the the first buffer. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) ``` -### SbPlayerDecoderStatusFunc ### +### SbPlayerDecoderStatusFunc Callback for decoder status updates, called in response to a call to SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called @@ -114,45 +114,45 @@ player will make at most one call to SbPlayerWriteSample() or SbPlayerWriteEndOfStream(). The player implementation should update the decoder status again after such call to notify its user to continue writing more frames. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) ``` -### SbPlayerErrorFunc ### +### SbPlayerErrorFunc Callback for player errors, that may set a `message`. `error`: indicates the error code. `message`: provides specific informative diagnostic message about the error condition encountered. It is ok for the message to be an empty string or NULL if no information is available. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) ``` -### SbPlayerStatusFunc ### +### SbPlayerStatusFunc Callback for player status updates. These callbacks will happen on a different thread than the calling thread, and it is not valid to call SbPlayer functions from within this callback. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) ``` -## Structs ## +## Structs -### SbPlayerCreationParam ### +### SbPlayerCreationParam The playback related parameters to pass into SbPlayerCreate() and SbPlayerGetPreferredOutputMode(). -#### Members #### +#### Members * `SbDrmSystem drm_system` @@ -178,11 +178,11 @@ SbPlayerGetPreferredOutputMode(). should be made available for the application to pull via calls to SbPlayerGetCurrentFrame(). -### SbPlayerInfo2 ### +### SbPlayerInfo2 Information about the current media playback state. -#### Members #### +#### Members * `SbTime current_media_timestamp` @@ -229,11 +229,11 @@ Information about the current media playback state. faster than normal speed. When it is less than one, the video is played in a slower than normal speed. Negative speeds are not supported. -### SbPlayerSampleInfo ### +### SbPlayerSampleInfo Information about the samples to be written into SbPlayerWriteSamples(). -#### Members #### +#### Members * `SbMediaType type` * `const void * buffer` @@ -266,12 +266,12 @@ Information about the samples to be written into SbPlayerWriteSamples(). The DRM system related info for the media sample. This value is required for encrypted samples. Otherwise, it must be `NULL`. -### SbPlayerSampleSideData ### +### SbPlayerSampleSideData Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data coming from multiple sources. -#### Members #### +#### Members * `SbPlayerSampleSideDataType type` * `const uint8_t * data` @@ -282,9 +282,9 @@ coming from multiple sources. The size of the data pointed by `data`, in bytes. -## Functions ## +## Functions -### SbPlayerDestroy ### +### SbPlayerDestroy Destroys `player`, freeing all associated resources. @@ -299,13 +299,13 @@ Destroys `player`, freeing all associated resources. SbPlayerDestroy has been called on that player. `player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` void SbPlayerDestroy(SbPlayer player) ``` -### SbPlayerGetCurrentFrame ### +### SbPlayerGetCurrentFrame Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, it will return a SbDecodeTarget representing the current frame to be rasterized. @@ -317,13 +317,13 @@ kSbDecodeTargetInvalid is returned. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` -### SbPlayerGetMaximumNumberOfSamplesPerWrite ### +### 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 @@ -337,13 +337,13 @@ to retain from those structures. of sample for which the number is retrieved. See the `SbMediaType` enum in media.h. -#### Declaration #### +#### Declaration ``` int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) ``` -### SbPlayerGetPreferredOutputMode ### +### SbPlayerGetPreferredOutputMode Returns the preferred output mode of the implementation when a video described by `creation_param` is played. It is assumed that it is okay to call @@ -361,23 +361,23 @@ whether the video described by `creation_param` can be played on the platform, and the implementation should try its best effort to return a valid output mode. `creation_param` must not be NULL. -#### Declaration #### +#### Declaration ``` SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) ``` -### SbPlayerIsValid ### +### SbPlayerIsValid Returns whether the given player handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbPlayerIsValid(SbPlayer player) ``` -### SbPlayerSetBounds ### +### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do not take effect until the next graphics frame buffer swap. The default bounds @@ -398,13 +398,13 @@ smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. `y`: The y-coordinate of the upper-left corner of the player. `width`: The width of the player, in pixels. `height`: The height of the player, in pixels. -#### Declaration #### +#### Declaration ``` void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) ``` -### SbPlayerSetPlaybackRate ### +### SbPlayerSetPlaybackRate Set the playback rate of the `player`. `rate` is default to 1.0 which indicates the playback is at its original speed. A `rate` greater than one will make the @@ -419,13 +419,13 @@ to support. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) ``` -### SbPlayerSetVolume ### +### SbPlayerSetVolume Sets the player's volume. @@ -434,13 +434,13 @@ Sets the player's volume. `0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be muted, and a value of `1.0` means that it should be played at full volume. -#### Declaration #### +#### Declaration ``` void SbPlayerSetVolume(SbPlayer player, double volume) ``` -### SbPlayerWriteEndOfStream ### +### SbPlayerWriteEndOfStream Writes a marker to `player`'s input stream of `stream_type` indicating that there are no more samples for that media type for the remainder of this media @@ -450,13 +450,13 @@ contents, after a call to SbPlayerSeek. `player`: The player to which the marker is written. `stream_type`: The type of stream for which the marker is written. -#### Declaration #### +#### Declaration ``` void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ``` -### SbPlayerWriteSample2 ### +### SbPlayerWriteSample2 `sample_type`: The type of sample being written. See the `SbMediaType` enum in media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with @@ -468,7 +468,7 @@ be copied if its content will be used after SbPlayerWriteSamples() returns. `sample_infos`. It has to be at least one, and less than the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). -#### Declaration #### +#### Declaration ``` void SbPlayerWriteSample2(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) diff --git a/cobalt/site/docs/reference/starboard/modules/14/socket.md b/cobalt/site/docs/reference/starboard/modules/14/socket.md index 9e0f81b98334..744c04e3847d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/14/socket.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket.h` Defines Starboard socket I/O functions. Starboard supports IPv4 and IPv6, TCP and UDP, server and client sockets. Some platforms may not support IPv6, some @@ -18,19 +18,19 @@ the connection, thus requiring use of either an SbSocketWaiter or spin-polling. TODO: For platforms that do not support sockets at all, they must support at least a high-level HTTP client API (to be defined later). -## Macros ## +## Macros -### kSbSocketInvalid ### +### kSbSocketInvalid Well-defined value for an invalid socket handle. -## Enums ## +## Enums -### SbSocketAddressType ### +### SbSocketAddressType All possible address types. -#### Values #### +#### Values * `kSbSocketAddressTypeIpv4` @@ -39,13 +39,13 @@ All possible address types. An IPv6 address, which uses 16 entries of the address buffer. -### SbSocketError ### +### SbSocketError Enumeration of all Starboard socket operation results. Despite the enum name, note that the value actually describes the outcome of an operation, which is not always an error. -#### Values #### +#### Values * `kSbSocketOk` @@ -63,11 +63,11 @@ always an error. The operation failed for some other reason not specified above. -### SbSocketProtocol ### +### SbSocketProtocol All possible IP socket types. -#### Values #### +#### Values * `kSbSocketProtocolTcp` @@ -77,11 +77,11 @@ All possible IP socket types. The UDP/IP protocol, an unreliable, connectionless, discrete packet (datagram) protocol. -### SbSocketResolveFilter ### +### SbSocketResolveFilter Bits that can be set when calling SbSocketResolve to filter the results. -#### Values #### +#### Values * `kSbSocketResolveFilterNone` @@ -93,25 +93,25 @@ Bits that can be set when calling SbSocketResolve to filter the results. Include Ipv6 addresses. -## Typedefs ## +## Typedefs -### SbSocket ### +### SbSocket A handle to a socket. -#### Definition #### +#### Definition ``` typedef SbSocketPrivate* SbSocket ``` -## Structs ## +## Structs -### SbSocketAddress ### +### SbSocketAddress A representation of any possible supported address type. -#### Members #### +#### Members * `uint8_t address` @@ -126,11 +126,11 @@ A representation of any possible supported address type. The port component of this socket address. If not specified, it will be zero, which is officially undefined. -### SbSocketResolution ### +### SbSocketResolution The result of a host name resolution. -#### Members #### +#### Members * `SbSocketAddress* addresses` @@ -139,9 +139,9 @@ The result of a host name resolution. The length of the `addresses` array. -## Functions ## +## Functions -### SbSocketAccept ### +### SbSocketAccept Accepts a pending connection on `socket` and returns a new SbSocket representing that connection. This function sets the error on `socket` and returns @@ -149,13 +149,13 @@ that connection. This function sets the error on `socket` and returns `socket`: The SbSocket that is accepting a pending connection. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketAccept(SbSocket socket) ``` -### SbSocketBind ### +### SbSocketBind Binds `socket` to a specific local interface and port specified by `local_address`. This function sets and returns the socket error if it is unable @@ -170,24 +170,24 @@ local address to which the socket is to be bound. This value must not be `NULL`. * Setting the IP address to `0.0.0.0` means that the socket should be bound to all interfaces. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address) ``` -### SbSocketClearLastError ### +### SbSocketClearLastError Clears the last error set on `socket`. The return value indicates whether the socket error was cleared. -#### Declaration #### +#### Declaration ``` bool SbSocketClearLastError(SbSocket socket) ``` -### SbSocketConnect ### +### SbSocketConnect Opens a connection of `socket`'s type to the host and port specified by `address`. This function sets and returns the socket error if it is unable to @@ -197,13 +197,13 @@ successfully.) `socket`: The type of connection that should be opened. `address`: The host and port to which the socket should connect. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketCreate ### +### SbSocketCreate Creates a new non-blocking socket for protocol `protocol` using address family `address_type`. @@ -216,13 +216,13 @@ Creates a new non-blocking socket for protocol `protocol` using address family `address_type`: The type of IP address to use for the socket. `protocol`: The protocol to use for the socket. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol) ``` -### SbSocketDestroy ### +### SbSocketDestroy Destroys the `socket` by flushing it, closing any connection that may be active on it, and reclaiming any resources associated with it, including any @@ -234,25 +234,25 @@ more. `socket`: The SbSocket to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketDestroy(SbSocket socket) ``` -### SbSocketFreeResolution ### +### SbSocketFreeResolution Frees a resolution allocated by SbSocketResolve. `resolution`: The resolution to be freed. -#### Declaration #### +#### Declaration ``` void SbSocketFreeResolution(SbSocketResolution *resolution) ``` -### SbSocketGetInterfaceAddress ### +### SbSocketGetInterfaceAddress Gets the source address and the netmask that would be used to connect to the destination. The netmask parameter is optional, and only populated if a non-NULL @@ -288,26 +288,26 @@ this output variable. `out_netmask`: This parameter is optional. If a non-NULL value is passed in, this function places the netmask associated with the source address in this output variable. -#### Declaration #### +#### Declaration ``` bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask) ``` -### SbSocketGetLastError ### +### SbSocketGetLastError Returns the last error set on `socket`. If `socket` is not valid, this function returns `kSbSocketErrorFailed`. `socket`: The SbSocket that the last error is returned for. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketGetLastError(SbSocket socket) ``` -### SbSocketGetLocalAddress ### +### SbSocketGetLocalAddress Gets the address that this socket is bound to locally, if the socket is connected. The return value indicates whether the address was retrieved @@ -316,59 +316,59 @@ successfully. `socket`: The SbSocket for which the local address is retrieved. `out_address`: The SbSocket's local address. -#### Declaration #### +#### Declaration ``` bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address) ``` -### SbSocketIsConnected ### +### SbSocketIsConnected Indicates whether `socket` is connected to anything. Invalid sockets are not connected. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnected(SbSocket socket) ``` -### SbSocketIsConnectedAndIdle ### +### SbSocketIsConnectedAndIdle Returns whether `socket` is connected to anything, and, if so, whether it is receiving any data. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnectedAndIdle(SbSocket socket) ``` -### SbSocketIsIpv6Supported ### +### SbSocketIsIpv6Supported Returns whether IPV6 is supported on the current platform. -#### Declaration #### +#### Declaration ``` bool SbSocketIsIpv6Supported() ``` -### SbSocketIsValid ### +### SbSocketIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketIsValid(SbSocket socket) ``` -### SbSocketJoinMulticastGroup ### +### SbSocketJoinMulticastGroup Joins `socket` to an IP multicast group identified by `address`. The equivalent of IP_ADD_MEMBERSHIP. The return value indicates whether the socket was joined @@ -377,13 +377,13 @@ to the group successfully. `socket`: The SbSocket to be joined to the IP multicast group. `address`: The location of the IP multicast group. -#### Declaration #### +#### Declaration ``` bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketListen ### +### SbSocketListen Causes `socket` to listen on the local address that `socket` was previously bound to by SbSocketBind. This function sets and returns the socket error if it @@ -392,13 +392,13 @@ connection successfully.) `socket`: The SbSocket on which the function operates. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketListen(SbSocket socket) ``` -### SbSocketReceiveFrom ### +### SbSocketReceiveFrom Reads up to `data_size` bytes from `socket` into `out_data` and places the source address of the packet in `out_source` if out_source is not NULL. Returns @@ -420,13 +420,13 @@ the address is unnecessary, but allowed. the socket. Must not be NULL. `data_size`: The number of bytes to read. `out_source`: The source address of the packet. -#### Declaration #### +#### Declaration ``` int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source) ``` -### SbSocketResolve ### +### SbSocketResolve Synchronously resolves `hostname` into the returned SbSocketResolution , which must be freed with SbSocketFreeResolution. The function returns `NULL` if it is @@ -438,13 +438,13 @@ not specify an IP address family filter, all address families are included. However, if one IP address family filter is specified, only that address family is included. The function ignores unrecognized filter bits. -#### Declaration #### +#### Declaration ``` SbSocketResolution* SbSocketResolve(const char *hostname, int filters) ``` -### SbSocketSendTo ### +### SbSocketSendTo Writes up to `data_size` bytes of `data` to `destination` via `socket`. Returns the number of bytes written, or a negative number if there is an error, in which @@ -466,13 +466,13 @@ to multiple sources from a single UDP server socket. TCP has two endpoints connected persistently, so setting `destination` when sending to a TCP socket will cause an error. -#### Declaration #### +#### Declaration ``` int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination) ``` -### SbSocketSetBroadcast ### +### SbSocketSetBroadcast Sets the `SO_BROADCAST`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -483,13 +483,13 @@ the broadcast address. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetBroadcast(SbSocket socket, bool value) ``` -### SbSocketSetReceiveBufferSize ### +### SbSocketSetReceiveBufferSize Sets the `SO_RCVBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -497,13 +497,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetReuseAddress ### +### SbSocketSetReuseAddress Sets the `SO_REUSEADDR`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -514,13 +514,13 @@ to it. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReuseAddress(SbSocket socket, bool value) ``` -### SbSocketSetSendBufferSize ### +### SbSocketSetSendBufferSize Sets the `SO_SNDBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -528,13 +528,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetTcpKeepAlive ### +### SbSocketSetTcpKeepAlive Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -545,13 +545,13 @@ 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`. -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) ``` -### SbSocketSetTcpNoDelay ### +### SbSocketSetTcpNoDelay Sets the `TCP_NODELAY`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -564,13 +564,13 @@ behavior. `socket`: The SbSocket for which the option is set. `value`: Indicates whether the Nagle algorithm should be disabled (`value`=`true`). -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpNoDelay(SbSocket socket, bool value) ``` -### SbSocketSetTcpWindowScaling ### +### SbSocketSetTcpWindowScaling Sets the `SO_WINSCALE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -578,7 +578,7 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: The value for the option. -#### Declaration #### +#### Declaration ``` 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 855dcf8b9c72..f1c6bd8b9f2f 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/14/socket_waiter.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket_waiter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket_waiter.h` Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to: @@ -26,19 +26,19 @@ thread, it needs to call SbSocketWaiterWakeUp() on the SbSocketWaiter after queuing the work item, or the SbSocketWaiter is not otherwise guaranteed to wake up. -## Macros ## +## Macros -### kSbSocketWaiterInvalid ### +### kSbSocketWaiterInvalid Well-defined value for an invalid socket watcher handle. -## Enums ## +## Enums -### SbSocketWaiterInterest ### +### SbSocketWaiterInterest All the interests that a socket may register for on a waiter. -#### Values #### +#### Values * `kSbSocketWaiterInterestNone` @@ -50,11 +50,11 @@ All the interests that a socket may register for on a waiter. An interest in or readiness to write to a socket without blocking. -### SbSocketWaiterResult ### +### SbSocketWaiterResult Possible reasons why a call to SbSocketWaiterWaitTimed returned. -#### Values #### +#### Values * `kSbSocketWaiterResultInvalid` @@ -66,31 +66,31 @@ Possible reasons why a call to SbSocketWaiterWaitTimed returned. The wait stopped because a call to SbSocketWaiterWakeUp was consumed. -## Typedefs ## +## Typedefs -### SbSocketWaiter ### +### SbSocketWaiter A handle to a socket waiter. -#### Definition #### +#### Definition ``` typedef SbSocketWaiterPrivate* SbSocketWaiter ``` -### SbSocketWaiterCallback ### +### SbSocketWaiterCallback Function pointer for socket waiter callbacks. -#### Definition #### +#### Definition ``` typedef void(* SbSocketWaiterCallback) (SbSocketWaiter waiter, SbSocket socket, void *context, int ready_interests) ``` -## Functions ## +## Functions -### SbSocketWaiterAdd ### +### SbSocketWaiterAdd Adds a new socket to be waited on by the `waiter` with a bitfield of `interests`. This function should only be called on the thread that waits on @@ -120,25 +120,25 @@ socket: `callback`, even if not all registered `interests` became ready, which allows for adding it again in the `callback`. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterAdd(SbSocketWaiter waiter, SbSocket socket, void *context, SbSocketWaiterCallback callback, int interests, bool persistent) ``` -### SbSocketWaiterCreate ### +### SbSocketWaiterCreate The results of two threads waiting on the same waiter is undefined and will not work. Except for the SbSocketWaiterWakeUp() function, SbSocketWaiters are not thread-safe and don't expect to be modified concurrently. -#### Declaration #### +#### Declaration ``` SbSocketWaiter SbSocketWaiterCreate() ``` -### SbSocketWaiterDestroy ### +### SbSocketWaiterDestroy Destroys `waiter` and removes all sockets still registered by way of SbSocketWaiterAdd. This function may be called on any thread as long as there is @@ -146,23 +146,23 @@ no risk of concurrent access to the waiter. `waiter`: The SbSocketWaiter to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterDestroy(SbSocketWaiter waiter) ``` -### SbSocketWaiterIsValid ### +### SbSocketWaiterIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketWaiterIsValid(SbSocketWaiter watcher) ``` -### SbSocketWaiterRemove ### +### SbSocketWaiterRemove Removes a socket, previously added with SbSocketWaiterAdd(), from a waiter. This function should only be called on the thread that waits on this waiter. @@ -174,26 +174,26 @@ returns `true`. `waiter`: The waiter from which the socket is removed. `socket`: The socket to remove from the waiter. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket) ``` -### SbSocketWaiterWait ### +### SbSocketWaiterWait Waits on all registered sockets, calling the registered callbacks if and when the corresponding sockets become ready for an interested operation. This version exits only after SbSocketWaiterWakeUp() is called. This function should only be called on the thread that waits on this waiter. -#### Declaration #### +#### Declaration ``` void SbSocketWaiterWait(SbSocketWaiter waiter) ``` -### SbSocketWaiterWaitTimed ### +### SbSocketWaiterWaitTimed Behaves similarly to SbSocketWaiterWait(), but this function also causes `waiter` to exit on its own after at least `duration` has passed if @@ -207,13 +207,13 @@ 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 #### +#### Declaration ``` SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) ``` -### SbSocketWaiterWakeUp ### +### SbSocketWaiterWakeUp Wakes up `waiter` once. This is the only thread-safe waiter function. It can can be called from a SbSocketWaiterCallback to wake up its own waiter, and it can @@ -230,7 +230,7 @@ next 7 times they are called. `waiter`: The socket waiter to be woken up. -#### Declaration #### +#### Declaration ``` 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 16223184e784..0bd6e65b6379 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/14/speech_synthesis.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: speech_synthesis.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `speech_synthesis.h` A basic text-to-speech API intended to be used for audio accessibility. @@ -11,29 +11,29 @@ non-visual navigation of the application. Note that these functions do not have to be thread-safe. They must only be called from a single application thread. -## Functions ## +## Functions -### SbSpeechSynthesisCancel ### +### SbSpeechSynthesisCancel Cancels all speaking and queued speech synthesis audio. Must return immediately. -#### Declaration #### +#### Declaration ``` void SbSpeechSynthesisCancel() ``` -### SbSpeechSynthesisIsSupported ### +### SbSpeechSynthesisIsSupported Returns whether the platform supports speech synthesis -#### Declaration #### +#### Declaration ``` bool SbSpeechSynthesisIsSupported() ``` -### SbSpeechSynthesisSpeak ### +### SbSpeechSynthesisSpeak Enqueues `text`, a UTF-8 string, to be spoken. Returns immediately. @@ -44,7 +44,7 @@ If audio from previous SbSpeechSynthesisSpeak() invocations is still processing, the current speaking should continue and this new text should be queued to play when the previous utterances are complete. -#### Declaration #### +#### Declaration ``` 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 db7e9509bd2b..5c2b9624723d 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/14/storage.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: storage.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `storage.h` Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and retrieval API that is intended for robust long-term, per-user storage. Some @@ -15,27 +15,27 @@ record for a user will result in undefined behavior. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbStorageInvalidRecord ### +### kSbStorageInvalidRecord Well-defined value for an invalid storage record handle. -## Typedefs ## +## Typedefs -### SbStorageRecord ### +### SbStorageRecord A handle to an open storage record. -#### Definition #### +#### Definition ``` typedef SbStorageRecordPrivate* SbStorageRecord ``` -## Functions ## +## Functions -### SbStorageCloseRecord ### +### SbStorageCloseRecord Closes `record`, synchronously ensuring that all written data is flushed. This function performs blocking I/O on the calling thread. @@ -47,13 +47,13 @@ deleted (or, even better, untouched). `record`: The storage record to close. `record` is invalid after this point, and subsequent calls referring to `record` will fail. -#### Declaration #### +#### Declaration ``` bool SbStorageCloseRecord(SbStorageRecord record) ``` -### SbStorageDeleteRecord ### +### SbStorageDeleteRecord Deletes the `SbStorageRecord` for `user` named `name`. The return value indicates whether the record existed and was successfully deleted. If the record @@ -68,36 +68,36 @@ function performs blocking I/O on the calling thread. `user`: The user for whom the record will be deleted. `name`: The filesystem- safe name of the record to open. -#### Declaration #### +#### Declaration ``` bool SbStorageDeleteRecord(SbUser user, const char *name) ``` -### SbStorageGetRecordSize ### +### SbStorageGetRecordSize Returns the size of `record`, or `-1` if there is an error. This function performs blocking I/O on the calling thread. `record`: The record to retrieve the size of. -#### Declaration #### +#### Declaration ``` int64_t SbStorageGetRecordSize(SbStorageRecord record) ``` -### SbStorageIsValidRecord ### +### SbStorageIsValidRecord Returns whether the given storage record handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbStorageIsValidRecord(SbStorageRecord record) ``` -### SbStorageOpenRecord ### +### SbStorageOpenRecord Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on the calling thread until the open is completed. If `user` is not a valid @@ -111,13 +111,13 @@ would have been saved with the previous version of SbStorageOpenRecord. `user`: The user for which the storage record will be opened. `name`: The filesystem-safe name of the record to open. -#### Declaration #### +#### Declaration ``` SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) ``` -### SbStorageReadRecord ### +### SbStorageReadRecord Reads up to `data_size` bytes from `record`, starting at the beginning of the record. The function returns the actual number of bytes read, which must be <= @@ -128,13 +128,13 @@ the calling thread until the entire record is read or an error is encountered. `record`: The record to be read. `out_data`: The data read from the record. `data_size`: The amount of data, in bytes, to read. -#### Declaration #### +#### Declaration ``` int64_t SbStorageReadRecord(SbStorageRecord record, char *out_data, int64_t data_size) ``` -### SbStorageWriteRecord ### +### SbStorageWriteRecord Replaces the data in `record` with `data_size` bytes from `data`. This function always deletes any previous data in that record. The return value indicates @@ -151,7 +151,7 @@ after a short time, even if there is an unexpected process termination before `record`: The record to be written to. `data`: The data to write to the record. `data_size`: The amount of `data`, in bytes, to write to the record. -#### Declaration #### +#### Declaration ``` 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 685f5e8f5e5b..3fed809df461 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/string.md +++ b/cobalt/site/docs/reference/starboard/modules/14/string.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: string.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `string.h` Defines functions for interacting with c-style strings. -## Functions ## +## Functions -### SbStringCompareNoCase ### +### SbStringCompareNoCase Compares two strings, ignoring differences in case. The return value is: @@ -21,13 +21,13 @@ This function is meant to be a drop-in replacement for `strcasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCase(const char *string1, const char *string2) ``` -### SbStringCompareNoCaseN ### +### SbStringCompareNoCaseN Compares the first `count` characters of two strings, ignoring differences in case. The return value is: @@ -43,13 +43,13 @@ This function is meant to be a drop-in replacement for `strncasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. `count`: The number of characters to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) ``` -### SbStringDuplicate ### +### SbStringDuplicate Copies `source` into a buffer that is allocated by this function and that can be freed with SbMemoryDeallocate. This function is meant to be a drop-in @@ -57,13 +57,13 @@ replacement for `strdup`. `source`: The string to be copied. -#### Declaration #### +#### Declaration ``` char* SbStringDuplicate(const char *source) ``` -### SbStringFormat ### +### SbStringFormat Produces a string formatted with `format` and `arguments`, placing as much of the result that will fit into `out_buffer`. The return value specifies the @@ -76,13 +76,13 @@ This function is meant to be a drop-in replacement for `vsnprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatF ### +### SbStringFormatF An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This function is meant to be a drop-in replacement for `snprintf`. @@ -91,13 +91,13 @@ function is meant to be a drop-in replacement for `snprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatUnsafeF ### +### SbStringFormatUnsafeF An inline wrapper of SbStringFormat that is meant to be a drop-in replacement for the unsafe but commonly used `sprintf`. @@ -106,13 +106,13 @@ for the unsafe but commonly used `sprintf`. string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 ``` -### SbStringFormatWide ### +### SbStringFormatWide This function is identical to SbStringFormat, but is for wide characters. It is meant to be a drop-in replacement for `vswprintf`. @@ -121,13 +121,13 @@ meant to be a drop-in replacement for `vswprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF ### +### SbStringFormatWideF An inline wrapper of SbStringFormatWide that converts from ellipsis to `va_args`. @@ -136,13 +136,13 @@ An inline wrapper of SbStringFormatWide that converts from ellipsis to The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) ``` -### SbStringScan ### +### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The return value specifies the number of successfully matched items, which may be @@ -154,20 +154,20 @@ This function is meant to be a drop-in replacement for `vsscanf`. for in `buffer`. `arguments`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` int SbStringScan(const char *buffer, const char *pattern, va_list arguments) ``` -### SbStringScanF ### +### SbStringScanF An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` 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 5e4e076c50d7..59e70188e05a 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/system.md +++ b/cobalt/site/docs/reference/starboard/modules/14/system.md @@ -1,21 +1,21 @@ ---- -layout: doc -title: "Starboard Module Reference: system.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `system.h` Defines a broad set of APIs that allow the client application to query build and runtime properties of the enclosing system. -## Enums ## +## Enums -### SbSystemCapabilityId ### +### SbSystemCapabilityId Runtime capabilities are boolean properties of a platform that can't be determined at compile-time. They may vary from device to device, but they will not change over the course of a single execution. They often specify particular behavior of other APIs within the bounds of their operating range. -#### Values #### +#### Values * `kSbSystemCapabilityReversedEnterAndBack` @@ -26,11 +26,11 @@ behavior of other APIs within the bounds of their operating range. only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call. -### SbSystemDeviceType ### +### SbSystemDeviceType Enumeration of device types. -#### Values #### +#### Values * `kSbSystemDeviceTypeBlueRayDiskPlayer` @@ -63,11 +63,11 @@ Enumeration of device types. Unknown device. -### SbSystemPathId ### +### SbSystemPathId Enumeration of special paths that the platform can define. -#### Values #### +#### Values * `kSbSystemPathContentDirectory` @@ -103,22 +103,22 @@ Enumeration of special paths that the platform can define. for storing the updates. See starboard/doc/evergreen/cobalt_evergreen_overview.md -### SbSystemPlatformErrorResponse ### +### SbSystemPlatformErrorResponse Possible responses for `SbSystemPlatformErrorCallback`. -#### Values #### +#### Values * `kSbSystemPlatformErrorResponsePositive` * `kSbSystemPlatformErrorResponseNegative` * `kSbSystemPlatformErrorResponseCancel` -### SbSystemPlatformErrorType ### +### SbSystemPlatformErrorType Enumeration of possible values for the `type` parameter passed to the `SbSystemRaisePlatformError` function. -#### Values #### +#### Values * `kSbSystemPlatformErrorTypeConnectionError` @@ -127,12 +127,12 @@ Enumeration of possible values for the `type` parameter passed to the `kSbSystemPlatformErrorResponsePositive` then the request should be retried, otherwise the app should be stopped. -### SbSystemPropertyId ### +### SbSystemPropertyId System properties that can be queried for. Many of these are used in User-Agent string generation. -#### Values #### +#### Values * `kSbSystemPropertyCertificationScope` @@ -189,9 +189,9 @@ string generation. Limit advertising tracking, treated as boolean. Set to nonzero to indicate a true value. Corresponds to 'lmt' field. -## Typedefs ## +## Typedefs -### SbSystemComparator ### +### SbSystemComparator Pointer to a function to compare two items. The return value uses standard `*cmp` semantics: @@ -204,23 +204,23 @@ Pointer to a function to compare two items. The return value uses standard `a`: The first value to compare. `b`: The second value to compare. -#### Definition #### +#### Definition ``` typedef int(* SbSystemComparator) (const void *a, const void *b) ``` -### SbSystemError ### +### SbSystemError A type that can represent a system error code across all Starboard platforms. -#### Definition #### +#### Definition ``` typedef int SbSystemError ``` -### SbSystemPlatformErrorCallback ### +### SbSystemPlatformErrorCallback Type of callback function that may be called in response to an error notification from `SbSystemRaisePlatformError`. `response` is a code to indicate @@ -228,46 +228,46 @@ the user's response, e.g. if the platform raised a dialog to notify the user of the error. `user_data` is the opaque pointer that was passed to the call to `SbSystemRaisePlatformError`. -#### Definition #### +#### Definition ``` typedef void(* SbSystemPlatformErrorCallback) (SbSystemPlatformErrorResponse response, void *user_data) ``` -## Functions ## +## Functions -### SbSystemBreakIntoDebugger ### +### SbSystemBreakIntoDebugger Breaks the current program into the debugger, if a debugger is attached. If a debugger is not attached, this function aborts the program. -#### Declaration #### +#### Declaration ``` SB_NORETURN void SbSystemBreakIntoDebugger() ``` -### SbSystemClearLastError ### +### SbSystemClearLastError Clears the last error set by a Starboard call in the current thread. -#### Declaration #### +#### Declaration ``` void SbSystemClearLastError() ``` -### SbSystemGetDeviceType ### +### SbSystemGetDeviceType Returns the type of the device. -#### Declaration #### +#### Declaration ``` SbSystemDeviceType SbSystemGetDeviceType() ``` -### SbSystemGetErrorString ### +### SbSystemGetErrorString Generates a human-readable string for an error. The return value specifies the total desired length of the string. @@ -276,13 +276,13 @@ total desired length of the string. The generated string. This value may be null, and it is always terminated with a null byte. `string_length`: The maximum length of the error string. -#### Declaration #### +#### Declaration ``` int SbSystemGetErrorString(SbSystemError error, char *out_string, int string_length) ``` -### SbSystemGetExtension ### +### SbSystemGetExtension Returns pointer to a constant global struct implementing the extension named `name`, if it is implemented. Otherwise return NULL. The `name` string must not @@ -304,25 +304,25 @@ application may only get the extension once, meaning updated values would be ignored. As the version of extensions are incremented, fields may be added to the end of the struct, but never removed (only deprecated). -#### Declaration #### +#### Declaration ``` const void* SbSystemGetExtension(const char *name) ``` -### SbSystemGetLastError ### +### SbSystemGetLastError Gets the last platform-specific error code produced by any Starboard call in the current thread for diagnostic purposes. Semantic reactions to Starboard function call results should be modeled explicitly. -#### Declaration #### +#### Declaration ``` SbSystemError SbSystemGetLastError() ``` -### SbSystemGetLocaleId ### +### SbSystemGetLocaleId Gets the system's current POSIX-style Locale ID. The locale represents the location, language, and cultural conventions that the system wants to use, which @@ -339,25 +339,25 @@ RFC 5646 describes BCP 47 language codes: [https://tools.ietf.org/html/bcp47](ht For more information than you probably want about POSIX locales, see: [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html) -#### Declaration #### +#### Declaration ``` const char* SbSystemGetLocaleId() ``` -### SbSystemGetNumberOfProcessors ### +### SbSystemGetNumberOfProcessors Returns the number of processor cores available to this application. If the process is sandboxed to a subset of the physical cores, the function returns that sandboxed limit. -#### Declaration #### +#### Declaration ``` int SbSystemGetNumberOfProcessors() ``` -### SbSystemGetProperty ### +### SbSystemGetProperty Retrieves the platform-defined system property specified by `property_id` and places its value as a zero-terminated string into the user-allocated `out_value` @@ -378,13 +378,13 @@ returns `false` under any of the following conditions and, in any such case, defined system property specified by `property_id`. `value_length`: The length of the system property. -#### Declaration #### +#### Declaration ``` bool SbSystemGetProperty(SbSystemPropertyId property_id, char *out_value, int value_length) ``` -### SbSystemGetRandomData ### +### SbSystemGetRandomData A cryptographically secure random number generator that produces an arbitrary, non-negative number of `buffer_size` random, non-negative bytes. The generated @@ -393,24 +393,24 @@ number is placed in `out_buffer`. This function does not require manual seeding. `out_buffer`: A pointer for the generated random number. This value must not be null. `buffer_size`: The size of the random number, in bytes. -#### Declaration #### +#### Declaration ``` void SbSystemGetRandomData(void *out_buffer, int buffer_size) ``` -### SbSystemGetRandomUInt64 ### +### SbSystemGetRandomUInt64 A cryptographically secure random number generator that gets 64 random bits and returns them as an `uint64_t`. This function does not require manual seeding. -#### Declaration #### +#### Declaration ``` uint64_t SbSystemGetRandomUInt64() ``` -### SbSystemGetStack ### +### SbSystemGetStack Places up to `stack_size` instruction pointer addresses of the current execution stack into `out_stack`. The return value specifies the number of entries added. @@ -427,62 +427,62 @@ what it means to be async-signal-safe on POSIX: [http://pubs.opengroup.org/onlin `stack_size`: The maximum number of instruction pointer addresses to be placed into `out_stack` from the current execution stack. -#### Declaration #### +#### Declaration ``` int SbSystemGetStack(void **out_stack, int stack_size) ``` -### SbSystemGetTotalCPUMemory ### +### SbSystemGetTotalCPUMemory Returns the total CPU memory (in bytes) potentially available to this application. If the process is sandboxed to a maximum allowable limit, the function returns the lesser of the physical and sandbox limits. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalCPUMemory() ``` -### SbSystemGetTotalGPUMemory ### +### SbSystemGetTotalGPUMemory Returns the total GPU memory (in bytes) available for use by this application. This function may only be called the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalGPUMemory() ``` -### SbSystemGetUsedCPUMemory ### +### SbSystemGetUsedCPUMemory Returns the total physical CPU memory (in bytes) used by this application. This value should always be less than (or, in particularly exciting situations, equal to) SbSystemGetTotalCPUMemory(). -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedCPUMemory() ``` -### SbSystemGetUsedGPUMemory ### +### SbSystemGetUsedGPUMemory Returns the current amount of GPU memory (in bytes) that is currently being used by this application. This function may only be called if the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedGPUMemory() ``` -### SbSystemHasCapability ### +### SbSystemHasCapability Returns whether the platform has the runtime capability specified by `capability_id`. Returns false for any unknown capabilities. This implementation @@ -490,48 +490,48 @@ must be thread-safe. `capability_id`: The runtime capability to check. -#### Declaration #### +#### Declaration ``` bool SbSystemHasCapability(SbSystemCapabilityId capability_id) ``` -### SbSystemHideSplashScreen ### +### SbSystemHideSplashScreen Hides the system splash screen on systems that support a splash screen that is displayed while the application is loading. This function may be called from any thread and must be idempotent. -#### Declaration #### +#### Declaration ``` void SbSystemHideSplashScreen() ``` -### SbSystemIsDebuggerAttached ### +### SbSystemIsDebuggerAttached Attempts to determine whether the current program is running inside or attached to a debugger. The function returns `false` if neither of those cases is true. -#### Declaration #### +#### Declaration ``` bool SbSystemIsDebuggerAttached() ``` -### SbSystemNetworkIsDisconnected ### +### SbSystemNetworkIsDisconnected Returns if the device is disconnected from network. "Disconnected" is chosen over connected because disconnection can be determined with more certainty than connection usually. -#### Declaration #### +#### Declaration ``` bool SbSystemNetworkIsDisconnected() ``` -### SbSystemRaisePlatformError ### +### SbSystemRaisePlatformError Cobalt calls this function to notify the platform that an error has occurred in the application that the platform may need to handle. The platform is expected @@ -553,13 +553,13 @@ caller know that the user has reacted to the error. `user_data`: An opaque pointer that the platform should pass as an argument to the callback function, if it is called. -#### Declaration #### +#### Declaration ``` bool SbSystemRaisePlatformError(SbSystemPlatformErrorType type, SbSystemPlatformErrorCallback callback, void *user_data) ``` -### SbSystemRequestBlur ### +### SbSystemRequestBlur Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to "unfocused application" in a @@ -569,13 +569,13 @@ This function eventually causes a `kSbEventTypeBlur` event to be dispatched to the application. Before the `kSbEventTypeBlur` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestBlur() ``` -### SbSystemRequestConceal ### +### SbSystemRequestConceal Requests that the application move into the Concealed state at the next convenient point. This should roughly correspond to "minimization" in a @@ -590,13 +590,13 @@ In the Concealed state, the application will be invisible, but probably still be running background tasks. The expectation is that an external system event will bring the application out of the Concealed state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestConceal() ``` -### SbSystemRequestFocus ### +### SbSystemRequestFocus Requests that the application move into the Started state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -607,13 +607,13 @@ This function eventually causes a `kSbEventTypeFocus` event to be dispatched to the application. Before `kSbEventTypeFocus` is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFocus() ``` -### SbSystemRequestFreeze ### +### SbSystemRequestFreeze Requests that the application move into the Frozen state at the next convenient point. @@ -626,13 +626,13 @@ In the Frozen state, the application will be resident, but probably not running. The expectation is that an external system event will bring the application out of the Frozen state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFreeze() ``` -### SbSystemRequestReveal ### +### SbSystemRequestReveal Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -643,13 +643,13 @@ This function eventually causes a `kSbEventTypeReveal` event to be dispatched to the application. Before the `kSbEventTypeReveal` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestReveal() ``` -### SbSystemRequestStop ### +### SbSystemRequestStop Requests that the application be terminated gracefully at the next convenient point. In the meantime, some work may continue to be done, and unrelated system @@ -660,13 +660,13 @@ it returns `error_level`, if that has any meaning on the current platform. `error_level`: An integer that serves as the return value for the process that is eventually terminated as a result of a call to this function. -#### Declaration #### +#### Declaration ``` void SbSystemRequestStop(int error_level) ``` -### SbSystemSignWithCertificationSecretKey ### +### SbSystemSignWithCertificationSecretKey Computes a HMAC-SHA256 digest of `message` into `digest` using the application's certification secret. The `message` and the `digest` pointers must not be NULL. @@ -676,13 +676,13 @@ greater), since 32-bytes will be written into it. Returns false in the case of an error, or if it is not implemented. In this case the contents of `digest` will be undefined. -#### Declaration #### +#### Declaration ``` bool SbSystemSignWithCertificationSecretKey(const uint8_t *message, size_t message_size_in_bytes, uint8_t *digest, size_t digest_size_in_bytes) ``` -### SbSystemSupportsResume ### +### SbSystemSupportsResume Returns false if the platform doesn't need resume after suspend support. In such case Cobalt will free up the resource it retains for resume after suspend. Note @@ -690,13 +690,13 @@ that if this function returns false, the Starboard implementation cannot send kSbEventTypeResume to the event handler. The return value of this function cannot change over the life time of the application. -#### Declaration #### +#### Declaration ``` bool SbSystemSupportsResume() ``` -### SbSystemSymbolize ### +### SbSystemSymbolize Looks up `address` as an instruction pointer and places up to (`buffer_size - 1`) characters of the symbol associated with it in `out_buffer`, which must not @@ -708,7 +708,7 @@ The return value indicates whether the function found a reasonable match for This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals. -#### Declaration #### +#### Declaration ``` 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 1191e9a56c91..56c7898a12b4 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/14/thread.md @@ -1,35 +1,35 @@ ---- -layout: doc -title: "Starboard Module Reference: thread.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `thread.h` Defines functionality related to thread creation and cleanup. -## Macros ## +## Macros -### kSbThreadContextInvalid ### +### kSbThreadContextInvalid Well-defined value for an invalid thread context. -### kSbThreadInvalidId ### +### kSbThreadInvalidId Well-defined constant value to mean "no thread ID." -### kSbThreadLocalKeyInvalid ### +### kSbThreadLocalKeyInvalid Well-defined constant value to mean "no thread local key." -### kSbThreadNoAffinity ### +### kSbThreadNoAffinity Well-defined constant value to mean "no affinity." -### kSbThreadSamplerInvalid ### +### kSbThreadSamplerInvalid Well-defined value for an invalid thread sampler. -## Enums ## +## Enums -### SbThreadPriority ### +### SbThreadPriority A spectrum of thread priorities. Platforms map them appropriately to their own priority system. Note that scheduling is platform-specific, and what these @@ -39,7 +39,7 @@ In particular, several of these priority values can map to the same priority on a given platform. The only guarantee is that each lower priority should be treated less-than-or-equal-to a higher priority. -#### Values #### +#### Values * `kSbThreadPriorityLowest` @@ -79,116 +79,116 @@ treated less-than-or-equal-to a higher priority. inherit the priority of the spawning thread, or it may mean a specific default priority, or it may mean something else, depending on the platform. -## Typedefs ## +## Typedefs -### SbThread ### +### SbThread An opaque handle to a thread type. -#### Definition #### +#### Definition ``` typedef void* SbThread ``` -### SbThreadAffinity ### +### SbThreadAffinity Type for thread core affinity. This generally will be a single cpu (or core or hyperthread) identifier. Some platforms may not support affinity, and some may have specific rules about how it must be used. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadAffinity ``` -### SbThreadContext ### +### SbThreadContext A handle to the context of a frozen thread. -#### Definition #### +#### Definition ``` typedef SbThreadContextPrivate* SbThreadContext ``` -### SbThreadEntryPoint ### +### SbThreadEntryPoint Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of data passed in from the calling thread. -#### Definition #### +#### Definition ``` typedef void*(* SbThreadEntryPoint) (void *context) ``` -### SbThreadId ### +### SbThreadId An ID type that is unique per thread. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadId ``` -### SbThreadLocalDestructor ### +### SbThreadLocalDestructor Function pointer type for Thread-Local destructors. -#### Definition #### +#### Definition ``` typedef void(* SbThreadLocalDestructor) (void *value) ``` -### SbThreadLocalKey ### +### SbThreadLocalKey A handle to a thread-local key. -#### Definition #### +#### Definition ``` typedef SbThreadLocalKeyPrivate* SbThreadLocalKey ``` -### SbThreadSampler ### +### SbThreadSampler A handle to a thread sampler. -#### Definition #### +#### Definition ``` typedef SbThreadSamplerPrivate* SbThreadSampler ``` -## Functions ## +## Functions -### SbThreadContextGetPointer ### +### SbThreadContextGetPointer Gets the specified pointer-type `property` from the specified `context`. Returns `true` if successful and `out_value` has been modified, otherwise returns `false` and `out_value` is not modified. -#### Declaration #### +#### Declaration ``` bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) ``` -### SbThreadContextIsValid ### +### SbThreadContextIsValid Returns whether the given thread context is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadContextIsValid(SbThreadContext context) ``` -### SbThreadCreate ### +### SbThreadCreate Creates a new thread, which starts immediately. @@ -214,13 +214,13 @@ used in production builds. `entry_point`: A pointer to a function that will be executed on the newly created thread. `context`: This value will be passed to the `entry_point` function. -#### Declaration #### +#### Declaration ``` SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) ``` -### SbThreadCreateLocalKey ### +### SbThreadCreateLocalKey Creates and returns a new, unique key for thread local data. If the function does not succeed, the function returns `kSbThreadLocalKeyInvalid`. @@ -233,13 +233,13 @@ value is not NULL. `destructor`: A pointer to a function. The value may be NULL if no clean up is needed. -#### Declaration #### +#### Declaration ``` SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) ``` -### SbThreadDestroyLocalKey ### +### SbThreadDestroyLocalKey Destroys thread local data for the specified key. The function is a no-op if the key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This @@ -247,13 +247,13 @@ function does NOT call the destructor on any stored values. `key`: The key for which to destroy thread local data. -#### Declaration #### +#### Declaration ``` void SbThreadDestroyLocalKey(SbThreadLocalKey key) ``` -### SbThreadDetach ### +### SbThreadDetach Detaches `thread`, which prevents it from being joined. This is sort of like a non-blocking join. This function is a no-op if the thread is already detached or @@ -261,33 +261,33 @@ if the thread is already being joined by another thread. `thread`: The thread to be detached. -#### Declaration #### +#### Declaration ``` void SbThreadDetach(SbThread thread) ``` -### SbThreadGetCurrent ### +### SbThreadGetCurrent Returns the handle of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThread SbThreadGetCurrent() ``` -### SbThreadGetId ### +### SbThreadGetId Returns the Thread ID of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThreadId SbThreadGetId() ``` -### SbThreadGetLocalValue ### +### SbThreadGetLocalValue Returns the pointer-sized value for `key` in the currently executing thread's local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key @@ -295,97 +295,97 @@ has already been destroyed. `key`: The key for which to return the value. -#### Declaration #### +#### Declaration ``` void* SbThreadGetLocalValue(SbThreadLocalKey key) ``` -### SbThreadGetName ### +### SbThreadGetName Returns the debug name of the currently executing thread. -#### Declaration #### +#### Declaration ``` void SbThreadGetName(char *buffer, int buffer_size) ``` -### SbThreadIsCurrent ### +### SbThreadIsCurrent Returns whether `thread` is the current thread. `thread`: The thread to check. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsCurrent(SbThread thread) ``` -### SbThreadIsEqual ### +### SbThreadIsEqual Indicates whether `thread1` and `thread2` refer to the same thread. `thread1`: The first thread to compare. `thread2`: The second thread to compare. -#### Declaration #### +#### Declaration ``` bool SbThreadIsEqual(SbThread thread1, SbThread thread2) ``` -### SbThreadIsValid ### +### SbThreadIsValid Returns whether the given thread handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValid(SbThread thread) ``` -### SbThreadIsValidAffinity ### +### SbThreadIsValidAffinity Returns whether the given thread affinity is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) ``` -### SbThreadIsValidId ### +### SbThreadIsValidId Returns whether the given thread ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidId(SbThreadId id) ``` -### SbThreadIsValidLocalKey ### +### SbThreadIsValidLocalKey Returns whether the given thread local variable key is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) ``` -### SbThreadIsValidPriority ### +### SbThreadIsValidPriority Returns whether the given thread priority is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidPriority(SbThreadPriority priority) ``` -### SbThreadJoin ### +### SbThreadJoin Joins the thread on which this function is called with joinable `thread`. This function blocks the caller until the designated thread exits, and then cleans up @@ -403,36 +403,36 @@ must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, then the SbThreadJoin function populates it with the return value of the thread's `main` function. -#### Declaration #### +#### Declaration ``` bool SbThreadJoin(SbThread thread, void **out_return) ``` -### SbThreadSamplerCreate ### +### SbThreadSamplerCreate Creates a new thread sampler for the specified `thread`. If successful, this function returns the newly created handle. If unsuccessful, this function returns `kSbThreadSamplerInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadSampler SbThreadSamplerCreate(SbThread thread) ``` -### SbThreadSamplerDestroy ### +### SbThreadSamplerDestroy Destroys the `sampler` and frees whatever resources it was using. -#### Declaration #### +#### Declaration ``` void SbThreadSamplerDestroy(SbThreadSampler sampler) ``` -### SbThreadSamplerFreeze ### +### SbThreadSamplerFreeze Suspends execution of the thread that `sampler` was created for. @@ -440,47 +440,47 @@ If successful, this function returns a `SbThreadContext` for the frozen thread, from which properties may be read while the thread remains frozen. If unsuccessful, this function returns `kSbThreadContextInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) ``` -### SbThreadSamplerIsSupported ### +### SbThreadSamplerIsSupported Whether the current platform supports thread sampling. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. If this returns false, `SbThreadSamplerCreate` will return an invalid sampler. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerIsSupported() ``` -### SbThreadSamplerIsValid ### +### SbThreadSamplerIsValid Returns whether the given thread sampler is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadSamplerIsValid(SbThreadSampler sampler) ``` -### SbThreadSamplerThaw ### +### SbThreadSamplerThaw Resumes execution of the thread that `sampler` was created for. This invalidates the context returned from `SbThreadSamplerFreeze`. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerThaw(SbThreadSampler sampler) ``` -### SbThreadSetLocalValue ### +### SbThreadSetLocalValue Sets the pointer-sized value for `key` in the currently executing thread's local storage. The return value indicates whether `key` is valid and has not already @@ -489,26 +489,26 @@ been destroyed. `key`: The key for which to set the key value. `value`: The new pointer-sized key value. -#### Declaration #### +#### Declaration ``` bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) ``` -### SbThreadSetName ### +### SbThreadSetName Sets the debug name of the currently executing thread by copying the specified name string. `name`: The name to assign to the thread. -#### Declaration #### +#### Declaration ``` void SbThreadSetName(const char *name) ``` -### SbThreadSleep ### +### SbThreadSleep Sleeps the currently executing thread. @@ -516,17 +516,17 @@ Sleeps the currently executing thread. executing thread should sleep. The function is a no-op if this value is negative or `0`. -#### Declaration #### +#### Declaration ``` void SbThreadSleep(SbTime duration) ``` -### SbThreadYield ### +### SbThreadYield Yields the currently executing thread, so another thread has a chance to run. -#### Declaration #### +#### Declaration ``` 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 19a7e4f7c49c..a6228cc0de6c 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/time.md +++ b/cobalt/site/docs/reference/starboard/modules/14/time.md @@ -1,59 +1,59 @@ ---- -layout: doc -title: "Starboard Module Reference: time.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time.h` Provides access to system time and timers. -## Macros ## +## Macros -### kSbTimeDay ### +### kSbTimeDay One day in SbTime units (microseconds). -### kSbTimeHour ### +### kSbTimeHour One hour in SbTime units (microseconds). -### kSbTimeMax ### +### kSbTimeMax The maximum value of an SbTime. -### kSbTimeMillisecond ### +### kSbTimeMillisecond One millisecond in SbTime units (microseconds). -### kSbTimeMinute ### +### kSbTimeMinute One minute in SbTime units (microseconds). -### kSbTimeNanosecondsPerMicrosecond ### +### kSbTimeNanosecondsPerMicrosecond How many nanoseconds in one SbTime unit (microseconds). -### kSbTimeSecond ### +### kSbTimeSecond One second in SbTime units (microseconds). -### kSbTimeToPosixDelta ### +### kSbTimeToPosixDelta A term that can be added to an SbTime to convert it into the number of microseconds since the POSIX epoch. -## Typedefs ## +## Typedefs -### SbTime ### +### SbTime The number of microseconds since the epoch of January 1, 1601 UTC, or the number of microseconds between two times. Always microseconds, ALWAYS UTC. -#### Definition #### +#### Definition ``` typedef int64_t SbTime ``` -### SbTimeMonotonic ### +### SbTimeMonotonic A number of microseconds from some point. The main property of this time is that it increases monotonically. It should also be as high-resolution a timer as we @@ -61,38 +61,38 @@ can get on a platform. So, it is good for measuring the time between two calls without worrying about a system clock adjustment. It's not good for getting the wall clock time. -#### Definition #### +#### Definition ``` typedef int64_t SbTimeMonotonic ``` -## Functions ## +## Functions -### SbTimeFromPosix ### +### SbTimeFromPosix Converts microseconds from the POSIX epoch into an `SbTime`. `time`: A time that measures the number of microseconds since January 1, 1970, 00:00:00, UTC. -#### Declaration #### +#### Declaration ``` static SbTime SbTimeFromPosix(int64_t time) ``` -### SbTimeGetMonotonicNow ### +### SbTimeGetMonotonicNow Gets a monotonically increasing time representing right now. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicNow() ``` -### SbTimeGetMonotonicThreadNow ### +### SbTimeGetMonotonicThreadNow Gets a monotonically increasing time representing how long the current thread has been in the executing state (i.e. not pre-empted nor waiting on an event). @@ -100,44 +100,44 @@ This is not necessarily total time and is intended to allow measuring thread execution time between two timestamps. If this is not available then SbTimeGetMonotonicNow() should be used. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicThreadNow() ``` -### SbTimeGetNow ### +### SbTimeGetNow Gets the current system time as an `SbTime`. -#### Declaration #### +#### Declaration ``` SbTime SbTimeGetNow() ``` -### SbTimeIsTimeThreadNowSupported ### +### SbTimeIsTimeThreadNowSupported Returns whether the current platform supports time thread now -#### Declaration #### +#### Declaration ``` bool SbTimeIsTimeThreadNowSupported() ``` -### SbTimeNarrow ### +### SbTimeNarrow Safely narrows a number from a more precise unit to a less precise one. This function rounds negative values toward negative infinity. -#### Declaration #### +#### Declaration ``` static int64_t SbTimeNarrow(int64_t time, int64_t divisor) ``` -### SbTimeToPosix ### +### SbTimeToPosix Converts `SbTime` into microseconds from the POSIX epoch. @@ -145,7 +145,7 @@ Converts `SbTime` into microseconds from the POSIX epoch. January 1, 1601, UTC, or that measures the number of microseconds between two times. -#### Declaration #### +#### Declaration ``` 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 f9e3fcb1ca1d..74d48172d63e 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/14/time_zone.md @@ -1,38 +1,38 @@ ---- -layout: doc -title: "Starboard Module Reference: time_zone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time_zone.h` Provides access to the system time zone information. -## Typedefs ## +## Typedefs -### SbTimeZone ### +### SbTimeZone 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). -#### Definition #### +#### Definition ``` typedef int SbTimeZone ``` -## Functions ## +## Functions -### SbTimeZoneGetCurrent ### +### SbTimeZoneGetCurrent Gets the system's current SbTimeZone in minutes. -#### Declaration #### +#### Declaration ``` SbTimeZone SbTimeZoneGetCurrent() ``` -### SbTimeZoneGetName ### +### 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 @@ -40,7 +40,7 @@ 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". -#### Declaration #### +#### Declaration ``` const char* SbTimeZoneGetName() diff --git a/cobalt/site/docs/reference/starboard/modules/14/types.md b/cobalt/site/docs/reference/starboard/modules/14/types.md index 90867a69542f..e1f372cc60c4 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/types.md +++ b/cobalt/site/docs/reference/starboard/modules/14/types.md @@ -1,15 +1,15 @@ ---- -layout: doc -title: "Starboard Module Reference: types.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `types.h` Provides a suite of standard types that should be universally available on all platforms, specifically focused on explicitly-sized integer types and booleans. This module also includes some related ubiquitous definitions like limits of the explicitly-sized integer types, and standard pointer and int32 sentinel values. -## Macros ## +## Macros -### kSbInvalidInt ### +### kSbInvalidInt A value that represents an int that is probably invalid. 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 a0ecfb1eafb8..cb4176713005 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/14/ui_navigation.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: ui_navigation.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `ui_navigation.h` API to allow applications to take advantage of the platform's native UI engine. This is mainly to drive the animation of visual elements and to signal which of @@ -19,20 +19,20 @@ SbUiNavItem in case the native UI engine moves individual items in response to user interaction. If the navigation item is a container, then the content offset will also be queried to determine the placement of its content items. -## Macros ## +## Macros -### kSbUiNavItemInvalid ### +### kSbUiNavItemInvalid Well-defined value for an invalid navigation item. -## Enums ## +## Enums -### SbUiNavItemType ### +### SbUiNavItemType Navigation items may be one of the following types. This must be specified upon item creation and may not change during the item's lifespan. -#### Values #### +#### Values * `kSbUiNavItemTypeFocus` @@ -42,29 +42,29 @@ item creation and may not change during the item's lifespan. This is a container of navigation items which can also be containers themselves or focusable items. Containers themselves cannot be focused. -## Typedefs ## +## Typedefs -### SbUiNavItem ### +### SbUiNavItem An opaque handle to an implementation-private structure representing a navigation item. -#### Definition #### +#### Definition ``` typedef struct SbUiNavItemPrivate* SbUiNavItem ``` -## Structs ## +## Structs -### SbUiNavCallbacks ### +### SbUiNavCallbacks This structure specifies all the callbacks which the platform UI engine should invoke for various interaction events on navigation items. These callbacks may be invoked from any thread at any frequency. The `callback_context` is the value that was passed on creation of the relevant SbUiNavItem. -#### Members #### +#### Members * `void(*onblur)(SbUiNavItem item, void *callback_context)` @@ -77,12 +77,12 @@ that was passed on creation of the relevant SbUiNavItem. Invoke when an item's content offset is changed. This is only used with container items. -### SbUiNavInterface ### +### SbUiNavInterface This structure declares the interface to the UI navigation implementation. All function pointers must be specified if the platform supports UI navigation. -#### Members #### +#### Members * `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks *callbacks, void *callback_context)` @@ -237,7 +237,7 @@ function pointers must be specified if the platform supports UI navigation. Call `update_function` with `context` to perform a series of UI navigation changes atomically before returning. -### SbUiNavItemDir ### +### SbUiNavItemDir Navigation items of type kSbUiNavItemTypeContainer have directionality. If directionality is not specified for a container, it should default to left-to- @@ -270,12 +270,12 @@ right and top-to-bottom. Bottom-to-top is similar to right-to-left, but for the Y position. ``` -#### Members #### +#### Members * `bool is_left_to_right` * `bool is_top_to_bottom` -### SbUiNavMatrix2x3 ### +### SbUiNavMatrix2x3 This represents a 2x3 transform matrix in row-major order. @@ -284,38 +284,38 @@ This represents a 2x3 transform matrix in row-major order. /// | c d ty | ``` -#### Members #### +#### Members * `float m` -### SbUiNavMatrix4 ### +### SbUiNavMatrix4 This represents a 4x4 transform matrix in row-major order. -#### Members #### +#### Members * `float m` -## Functions ## +## Functions -### SbUiNavGetInterface ### +### SbUiNavGetInterface Retrieve the platform's UI navigation implementation. If the platform does not provide one, then return false without modifying `out_interface`. Otherwise, initialize all members of `out_interface` and return true. The `out_interface` pointer must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbUiNavGetInterface(SbUiNavInterface *out_interface) ``` -### SbUiNavItemIsValid ### +### SbUiNavItemIsValid Returns whether the given navigation item handle is valid. -#### Declaration #### +#### Declaration ``` 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 406e695c4a2e..309b939d066e 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/user.md +++ b/cobalt/site/docs/reference/starboard/modules/14/user.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: user.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `user.h` Defines a user management API. This module defines functions only for managing signed-in users. Platforms that do not have users must still implement this API, @@ -10,19 +10,19 @@ always reporting a single user that is current and signed in. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbUserInvalid ### +### kSbUserInvalid Well-defined value for an invalid user. -## Enums ## +## Enums -### SbUserPropertyId ### +### SbUserPropertyId A set of string properties that can be queried on a user. -#### Values #### +#### Values * `kSbUserPropertyAvatarUrl` @@ -38,21 +38,21 @@ A set of string properties that can be queried on a user. A unique user ID of a user. -## Typedefs ## +## Typedefs -### SbUser ### +### SbUser A handle to a user. -#### Definition #### +#### Definition ``` typedef SbUserPrivate* SbUser ``` -## Functions ## +## Functions -### SbUserGetCurrent ### +### SbUserGetCurrent Gets the current primary user, if one exists. This is the user that is determined, in a platform-specific way, to be the primary user controlling the @@ -63,13 +63,13 @@ appropriate for the platform. It is expected that there will be a unique SbUser per signed-in user, and that the referenced objects will persist for the lifetime of the app. -#### Declaration #### +#### Declaration ``` SbUser SbUserGetCurrent() ``` -### SbUserGetProperty ### +### SbUserGetProperty Retrieves the value of `property_id` for `user` and places it in `out_value`. The function returns: @@ -83,13 +83,13 @@ The function returns: The property for which the data is requested. `out_value`: The retrieved property value. `value_size`: The size of the retrieved property value. -#### Declaration #### +#### Declaration ``` bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) ``` -### SbUserGetPropertySize ### +### SbUserGetPropertySize Returns the size of the value of `property_id` for `user`, INCLUDING the terminating null character. The function returns `0` if `user` is invalid or if @@ -98,13 +98,13 @@ terminating null character. The function returns `0` if `user` is invalid or if `user`: The user for which property size data is being retrieved. `property_id`: The property for which the data is requested. -#### Declaration #### +#### Declaration ``` int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) ``` -### SbUserGetSignedIn ### +### SbUserGetSignedIn Gets a list of up to `users_size` signed-in users and places the results in `out_users`. The return value identifies the actual number of signed-in users, @@ -116,17 +116,17 @@ the referenced objects will persist for the lifetime of the app. `out_users`: Handles for the retrieved users. `users_size`: The maximum number of signed-in users to retrieve. -#### Declaration #### +#### Declaration ``` int SbUserGetSignedIn(SbUser *out_users, int users_size) ``` -### SbUserIsValid ### +### SbUserIsValid Returns whether the given user handle is valid. -#### Declaration #### +#### Declaration ``` 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 915e254667c6..acea84d4c7d0 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/window.md +++ b/cobalt/site/docs/reference/starboard/modules/14/window.md @@ -1,40 +1,40 @@ ---- -layout: doc -title: "Starboard Module Reference: window.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `window.h` Provides functionality to handle Window creation and management. -## Macros ## +## Macros -### kSbEventOnScreenKeyboardInvalidTicket ### +### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value kSbEventOnScreenKeyboardInvalidTicket. -### kSbWindowInvalid ### +### kSbWindowInvalid Well-defined value for an invalid window handle. -## Typedefs ## +## Typedefs -### SbWindow ### +### SbWindow A handle to a window. -#### Definition #### +#### Definition ``` typedef SbWindowPrivate* SbWindow ``` -## Structs ## +## Structs -### SbWindowOptions ### +### SbWindowOptions Options that can be requested at window creation time. -#### Members #### +#### Members * `SbWindowSize size` @@ -48,25 +48,25 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect ### +### SbWindowRect Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. -#### Members #### +#### Members * `float x` * `float y` * `float width` * `float height` -### SbWindowSize ### +### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window. -#### Members #### +#### Members * `int width` @@ -93,9 +93,9 @@ that would be created to back that window. A value of 0.0f means the ratio could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f). -## Functions ## +## Functions -### SbWindowBlurOnScreenKeyboard ### +### SbWindowBlurOnScreenKeyboard Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred. kSbEventTypeOnScreenKeyboardBlurred has data `ticket`. Calling @@ -103,13 +103,13 @@ 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 #### +#### Declaration ``` void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowCreate ### +### SbWindowCreate Creates and returns a new system window with the given `options`, which may be `NULL`. The function returns `kSbWindowInvalid` if it cannot create the @@ -131,25 +131,25 @@ entry point. `options`: Options that specify parameters for the window being created. -#### Declaration #### +#### Declaration ``` SbWindow SbWindowCreate(const SbWindowOptions *options) ``` -### SbWindowDestroy ### +### SbWindowDestroy Destroys `window`, reclaiming associated resources. `window`: The `SbWindow` to destroy. -#### Declaration #### +#### Declaration ``` bool SbWindowDestroy(SbWindow window) ``` -### SbWindowFocusOnScreenKeyboard ### +### SbWindowFocusOnScreenKeyboard Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused. kSbEventTypeOnScreenKeyboardFocused has data `ticket`. Calling @@ -157,38 +157,38 @@ 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 #### +#### Declaration ``` void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowGetDiagonalSizeInInches ### +### SbWindowGetDiagonalSizeInInches Gets the size of the diagonal between two opposing screen corners. A return value of 0 means that starboard does not know what the screen diagonal is. -#### Declaration #### +#### Declaration ``` float SbWindowGetDiagonalSizeInInches(SbWindow window) ``` -### SbWindowGetOnScreenKeyboardBoundingRect ### +### 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 #### +#### Declaration ``` bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect) ``` -### SbWindowGetPlatformHandle ### +### SbWindowGetPlatformHandle Gets the platform-specific handle for `window`, which can be passed as an EGLNativeWindowType to initialize EGL/GLES. This return value is entirely @@ -196,13 +196,13 @@ platform-specific, so there are no constraints about expected ranges. `window`: The SbWindow to retrieve the platform handle for. -#### Declaration #### +#### Declaration ``` void* SbWindowGetPlatformHandle(SbWindow window) ``` -### SbWindowGetSize ### +### SbWindowGetSize Retrieves the dimensions of `window` and sets `size` accordingly. This function returns `true` if it completes successfully. If the function returns `false`, @@ -210,81 +210,81 @@ then `size` will not have been modified. `window`: The SbWindow to retrieve the size of. `size`: The retrieved size. -#### Declaration #### +#### Declaration ``` bool SbWindowGetSize(SbWindow window, SbWindowSize *size) ``` -### SbWindowHideOnScreenKeyboard ### +### 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 #### +#### Declaration ``` void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowIsOnScreenKeyboardShown ### +### SbWindowIsOnScreenKeyboardShown Determine if the on screen keyboard is shown. -#### Declaration #### +#### Declaration ``` bool SbWindowIsOnScreenKeyboardShown(SbWindow window) ``` -### SbWindowIsValid ### +### SbWindowIsValid Returns whether the given window handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbWindowIsValid(SbWindow window) ``` -### SbWindowOnScreenKeyboardIsSupported ### +### SbWindowOnScreenKeyboardIsSupported Return whether the current platform supports an on screen keyboard -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardIsSupported() ``` -### SbWindowOnScreenKeyboardSuggestionsSupported ### +### SbWindowOnScreenKeyboardSuggestionsSupported Determine if the on screen keyboard has suggestions implemented. If this returns false, then calling SbWindowUpdateOnScreenKeyboardSuggestions() will be undefined. -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardSuggestionsSupported(SbWindow window) ``` -### SbWindowSetDefaultOptions ### +### SbWindowSetDefaultOptions Sets the default options for system windows. `options`: The option values to use as default values. This object must not be `NULL`. -#### Declaration #### +#### Declaration ``` void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` -### SbWindowSetOnScreenKeyboardKeepFocus ### +### 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 @@ -293,13 +293,13 @@ OnScreenKeyboard via input; focus may only be moved via events sent by the app. OnScreenKeyboard via input. `keepFocus` is initialized to false in the OnScreenKeyboard constructor. -#### Declaration #### +#### Declaration ``` void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus) ``` -### SbWindowShowOnScreenKeyboard ### +### SbWindowShowOnScreenKeyboard Show the on screen keyboard and populate the input with text `input_text`. Fire kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary. @@ -309,13 +309,13 @@ 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 #### +#### Declaration ``` void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket) ``` -### SbWindowUpdateOnScreenKeyboardSuggestions ### +### SbWindowUpdateOnScreenKeyboardSuggestions Update the on screen keyboard custom suggestions. Fire kSbEventTypeOnScreenKeyboardSuggestionsUpdated. @@ -323,7 +323,7 @@ kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data `ticket`. The suggestions should remain up-to-date when the keyboard is shown after being hidden. -#### Declaration #### +#### Declaration ``` 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 1a5adcbb873e..5c66ba442803 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/15/accessibility.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: accessibility.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `accessibility.h` Provides access to the system options and settings related to accessibility. -## Enums ## +## Enums -### SbAccessibilityCaptionCharacterEdgeStyle ### +### SbAccessibilityCaptionCharacterEdgeStyle Enum for possible closed captioning character edge styles. -#### Values #### +#### Values * `kSbAccessibilityCaptionCharacterEdgeStyleNone` * `kSbAccessibilityCaptionCharacterEdgeStyleRaised` @@ -19,11 +19,11 @@ Enum for possible closed captioning character edge styles. * `kSbAccessibilityCaptionCharacterEdgeStyleUniform` * `kSbAccessibilityCaptionCharacterEdgeStyleDropShadow` -### SbAccessibilityCaptionColor ### +### SbAccessibilityCaptionColor Enum for possible closed captioning colors. -#### Values #### +#### Values * `kSbAccessibilityCaptionColorBlue` * `kSbAccessibilityCaptionColorBlack` @@ -34,11 +34,11 @@ Enum for possible closed captioning colors. * `kSbAccessibilityCaptionColorWhite` * `kSbAccessibilityCaptionColorYellow` -### SbAccessibilityCaptionFontFamily ### +### SbAccessibilityCaptionFontFamily Enum for possible closed captioning font families -#### Values #### +#### Values * `kSbAccessibilityCaptionFontFamilyCasual` * `kSbAccessibilityCaptionFontFamilyCursive` @@ -48,11 +48,11 @@ Enum for possible closed captioning font families * `kSbAccessibilityCaptionFontFamilyProportionalSerif` * `kSbAccessibilityCaptionFontFamilySmallCapitals` -### SbAccessibilityCaptionFontSizePercentage ### +### SbAccessibilityCaptionFontSizePercentage Enum for possible closed captioning font size percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionFontSizePercentage25` * `kSbAccessibilityCaptionFontSizePercentage50` @@ -67,11 +67,11 @@ Enum for possible closed captioning font size percentages. * `kSbAccessibilityCaptionFontSizePercentage275` * `kSbAccessibilityCaptionFontSizePercentage300` -### SbAccessibilityCaptionOpacityPercentage ### +### SbAccessibilityCaptionOpacityPercentage Enum for possible closed captioning opacity percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionOpacityPercentage0` * `kSbAccessibilityCaptionOpacityPercentage25` @@ -79,11 +79,11 @@ Enum for possible closed captioning opacity percentages. * `kSbAccessibilityCaptionOpacityPercentage75` * `kSbAccessibilityCaptionOpacityPercentage100` -### SbAccessibilityCaptionState ### +### SbAccessibilityCaptionState Enum for possible states of closed captioning properties. -#### Values #### +#### Values * `kSbAccessibilityCaptionStateUnsupported` @@ -115,14 +115,14 @@ Enum for possible states of closed captioning properties. SbAccessibilityCaptionSettings.supportsOverride contains false, then no fields of SbAccessibilityCaptionSettings will ever contain this value. -## Structs ## +## Structs -### SbAccessibilityCaptionSettings ### +### SbAccessibilityCaptionSettings A group of settings related to system-level closed captioning settings, for platforms that expose closed captioning settings. -#### Members #### +#### Members * `SbAccessibilityCaptionColor background_color` * `SbAccessibilityCaptionState background_color_state` @@ -166,9 +166,9 @@ platforms that expose closed captioning settings. false, the values of `SbAccessibilityCaptionState` should be interpreted differently. -### SbAccessibilityDisplaySettings ### +### SbAccessibilityDisplaySettings -#### Members #### +#### Members * `bool has_high_contrast_text_setting` @@ -177,12 +177,12 @@ platforms that expose closed captioning settings. Whether the high contrast text setting is enabled or not. -### SbAccessibilityTextToSpeechSettings ### +### SbAccessibilityTextToSpeechSettings A group of settings related to text-to-speech functionality, for platforms that expose system settings for text-to-speech. -#### Members #### +#### Members * `bool has_text_to_speech_setting` @@ -192,9 +192,9 @@ expose system settings for text-to-speech. Whether the text-to-speech setting is enabled or not. This setting is only valid if `has_text_to_speech_setting` is set to true. -## Functions ## +## Functions -### SbAccessibilityGetCaptionSettings ### +### SbAccessibilityGetCaptionSettings Get the platform's settings for system-level closed captions. This function returns false if `caption_settings` is NULL or if it is not zero-initialized. @@ -202,13 +202,13 @@ returns false if `caption_settings` is NULL or if it is not zero-initialized. `caption_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetCaptionSettings(SbAccessibilityCaptionSettings *caption_settings) ``` -### SbAccessibilityGetDisplaySettings ### +### SbAccessibilityGetDisplaySettings Get the platform settings related to high contrast text. This function returns false if `out_settings` is NULL or if it is not zero-initialized. @@ -216,13 +216,13 @@ false if `out_settings` is NULL or if it is not zero-initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityDisplaySettings* struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetDisplaySettings(SbAccessibilityDisplaySettings *out_settings) ``` -### SbAccessibilityGetTextToSpeechSettings ### +### SbAccessibilityGetTextToSpeechSettings Get the platform settings related to the text-to-speech accessibility feature. This function returns false if `out_settings` is NULL or if it is not zero- @@ -231,13 +231,13 @@ initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetTextToSpeechSettings(SbAccessibilityTextToSpeechSettings *out_settings) ``` -### SbAccessibilitySetCaptionsEnabled ### +### SbAccessibilitySetCaptionsEnabled Modifies whether closed captions are enabled at a system level. This function returns false if this feature is not supported by the platform, or if changing @@ -246,7 +246,7 @@ the setting is unsuccessful. This function will modify the setting system-wide. `enabled`: A boolean indicating whether captions should be turned on (true) or off (false). -#### Declaration #### +#### Declaration ``` 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 9741f3cd7302..0ed31cb649ec 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/15/atomic.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: atomic.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `atomic.h` Defines a set of atomic integer operations that can be used as lightweight synchronization or as building blocks for heavier synchronization primitives. @@ -9,32 +9,32 @@ Their use is very subtle and requires detailed understanding of the behavior of supported architectures, so their direct use is not recommended except when rigorously deemed absolutely necessary for performance reasons. -## Typedefs ## +## Typedefs -### SbAtomic64 ### +### SbAtomic64 64-bit atomic operations (only available on 64-bit processors). -#### Definition #### +#### Definition ``` typedef int64_t SbAtomic64 ``` -### SbAtomicPtr ### +### SbAtomicPtr Pointer-sized atomic operations. Forwards to either 32-bit or 64-bit functions as appropriate. -#### Definition #### +#### Definition ``` typedef SbAtomic32 SbAtomicPtr ``` -## Functions ## +## Functions -### SbAtomicAcquire_CompareAndSwap ### +### SbAtomicAcquire_CompareAndSwap These following lower-level operations are typically useful only to people implementing higher-level synchronization operations like spinlocks, mutexes, @@ -45,23 +45,23 @@ operations ensure that no previous memory access can be reordered after the operation. "Barrier" operations have both "Acquire" and "Release" semantics. A SbAtomicMemoryBarrier() has "Barrier" semantics, but does no memory access. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicAcquire_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicBarrier_Increment ### +### SbAtomicBarrier_Increment Same as SbAtomicNoBarrier_Increment, but with a memory barrier. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicNoBarrier_CompareAndSwap ### +### SbAtomicNoBarrier_CompareAndSwap Atomically execute: result = *ptr; if (*ptr == old_value) *ptr = new_value; return result; @@ -71,39 +71,39 @@ return the old value of "*ptr" This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Exchange ### +### SbAtomicNoBarrier_Exchange Atomically store new_value into *ptr, returning the previous value held in *ptr. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Exchange(volatile SbAtomic32 *ptr, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Increment ### +### SbAtomicNoBarrier_Increment Atomically increment *ptr by "increment". Returns the new value of *ptr with the increment applied. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicRelease_CompareAndSwap8 ### +### SbAtomicRelease_CompareAndSwap8 Overloaded functions for Atomic8. -#### Declaration #### +#### Declaration ``` 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 b0e652f50e92..9277c70837b0 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/15/audio_sink.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: audio_sink.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `audio_sink.h` Provides an interface to output raw audio data. -## Macros ## +## Macros -### kSbAudioSinkInvalid ### +### kSbAudioSinkInvalid Well-defined value for an invalid audio sink. -## Typedefs ## +## Typedefs -### SbAudioSink ### +### SbAudioSink An opaque handle to an implementation-private structure representing an audio sink. -#### Definition #### +#### Definition ``` typedef struct SbAudioSinkPrivate* SbAudioSink ``` -### SbAudioSinkConsumeFramesFunc ### +### SbAudioSinkConsumeFramesFunc Callback used to report frames consumed. The consumed frames will be removed from the source frame buffer to free space for new audio frames. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkConsumeFramesFunc) (int frames_consumed, void *context) ``` -### SbAudioSinkFrameBuffers ### +### SbAudioSinkFrameBuffers An array of frame buffers. For interleaved audio streams, there will be only one element in the array. For planar audio streams, the number of elements in the array equal to the number of channels. -#### Definition #### +#### Definition ``` typedef void** SbAudioSinkFrameBuffers ``` -### SbAudioSinkUpdateSourceStatusFunc ### +### SbAudioSinkUpdateSourceStatusFunc Callback being called periodically to retrieve the status of the audio source. The first two output parameters indicating the filling level of the audio frame @@ -64,15 +64,15 @@ usually this is caused by a seek. All parameters except `context` cannot be NULL. Note that this function only reports the status of the source, it doesn't remove audio data from the source frame buffer. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkUpdateSourceStatusFunc) (int *frames_in_buffer, int *offset_in_frames, bool *is_playing, bool *is_eos_reached, void *context) ``` -## Functions ## +## Functions -### SbAudioSinkCreate ### +### SbAudioSinkCreate Creates an audio sink for the specified `channels` and `sampling_frequency_hz`, acquires all resources needed to operate the audio sink, and returns an opaque @@ -113,13 +113,13 @@ to sample data. value that is passed back to all callbacks and is generally used to point at a class or struct that contains state associated with the audio sink. -#### Declaration #### +#### Declaration ``` SbAudioSink SbAudioSinkCreate(int channels, int sampling_frequency_hz, SbMediaAudioSampleType audio_sample_type, SbMediaAudioFrameStorageType audio_frame_storage_type, SbAudioSinkFrameBuffers frame_buffers, int frames_per_channel, SbAudioSinkUpdateSourceStatusFunc update_source_status_func, SbAudioSinkConsumeFramesFunc consume_frames_func, void *context) ``` -### SbAudioSinkDestroy ### +### SbAudioSinkDestroy Destroys `audio_sink`, freeing all associated resources. Before returning, the function waits until all callbacks that are in progress have finished. After the @@ -132,24 +132,24 @@ any of the callbacks passed into SbAudioSinkCreate. `audio_sink`: The audio sink to destroy. -#### Declaration #### +#### Declaration ``` void SbAudioSinkDestroy(SbAudioSink audio_sink) ``` -### SbAudioSinkGetMaxChannels ### +### SbAudioSinkGetMaxChannels Returns the maximum number of channels supported on the platform. For example, the number would be `2` if the platform only supports stereo. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMaxChannels() ``` -### SbAudioSinkGetMinBufferSizeInFrames ### +### SbAudioSinkGetMinBufferSizeInFrames Returns the minimum frames required by audio sink to play without underflows. Returns -1, if `channels`, `sample_type` or `sampling_frequency_hz` is not @@ -162,52 +162,52 @@ stereo audio. `audio_sample_type`: The type of each sample of the audio data – audio data being streamed. For example, 22,000 Hz means 22,000 sample elements represents one second of audio data. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMinBufferSizeInFrames(int channels, SbMediaAudioSampleType sample_type, int sampling_frequency_hz) ``` -### SbAudioSinkGetNearestSupportedSampleFrequency ### +### SbAudioSinkGetNearestSupportedSampleFrequency Returns the supported sample rate closest to `sampling_frequency_hz`. On platforms that don't support all sample rates, it is the caller's responsibility to resample the audio frames into the supported sample rate returned by this function. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetNearestSupportedSampleFrequency(int sampling_frequency_hz) ``` -### SbAudioSinkIsAudioFrameStorageTypeSupported ### +### SbAudioSinkIsAudioFrameStorageTypeSupported Indicates whether `audio_frame_storage_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioFrameStorageTypeSupported(SbMediaAudioFrameStorageType audio_frame_storage_type) ``` -### SbAudioSinkIsAudioSampleTypeSupported ### +### SbAudioSinkIsAudioSampleTypeSupported Indicates whether `audio_sample_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioSampleTypeSupported(SbMediaAudioSampleType audio_sample_type) ``` -### SbAudioSinkIsValid ### +### SbAudioSinkIsValid Indicates whether the given audio sink handle is valid. `audio_sink`: The audio sink handle to check. -#### Declaration #### +#### Declaration ``` 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 c83927d5132d..72dc9327ed1e 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/15/byte_swap.md @@ -1,74 +1,74 @@ ---- -layout: doc -title: "Starboard Module Reference: byte_swap.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `byte_swap.h` Specifies functions for swapping byte order. These functions are used to deal with endianness when performing I/O. -## Functions ## +## Functions -### SbByteSwapS16 ### +### SbByteSwapS16 Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int16_t SbByteSwapS16(int16_t value) ``` -### SbByteSwapS32 ### +### SbByteSwapS32 Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int32_t SbByteSwapS32(int32_t value) ``` -### SbByteSwapS64 ### +### SbByteSwapS64 Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int64_t SbByteSwapS64(int64_t value) ``` -### SbByteSwapU16 ### +### SbByteSwapU16 Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint16_t SbByteSwapU16(uint16_t value) ``` -### SbByteSwapU32 ### +### SbByteSwapU32 Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint32_t SbByteSwapU32(uint32_t value) ``` -### SbByteSwapU64 ### +### SbByteSwapU64 Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` 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 e58e10652156..2d8f30b5fdce 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/15/condition_variable.md @@ -1,23 +1,23 @@ ---- -layout: doc -title: "Starboard Module Reference: condition_variable.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `condition_variable.h` Defines an interface for condition variables. -## Macros ## +## Macros -### SB_CONDITION_VARIABLE_MAX_SIZE ### +### SB_CONDITION_VARIABLE_MAX_SIZE Max size of the SbConditionVariable type. -## Enums ## +## Enums -### SbConditionVariableResult ### +### SbConditionVariableResult Enumeration of possible results from waiting on a condvar. -#### Values #### +#### Values * `kSbConditionVariableSignaled` @@ -30,22 +30,22 @@ Enumeration of possible results from waiting on a condvar. The wait failed, either because a parameter wasn't valid, or the condition variable has already been destroyed, or something similar. -## Typedefs ## +## Typedefs -### SbConditionVariable ### +### SbConditionVariable An opaque handle to a condition variable type with reserved memory buffer of size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbConditionVariable SbConditionVariable ``` -## Functions ## +## Functions -### SbConditionVariableBroadcast ### +### SbConditionVariableBroadcast Broadcasts to all current waiters of `condition` to stop waiting. This function wakes all of the threads waiting on `condition` while SbConditionVariableSignal @@ -53,26 +53,26 @@ wakes a single thread. `condition`: The condition that should no longer be waited for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableBroadcast(SbConditionVariable *condition) ``` -### SbConditionVariableCreate ### +### SbConditionVariableCreate Creates a new condition variable to work with `opt_mutex`, which may be null, placing the newly created condition variable in `out_condition`. The return value indicates whether the condition variable could be created. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) ``` -### SbConditionVariableDestroy ### +### SbConditionVariableDestroy Destroys the specified SbConditionVariable . The return value indicates whether the destruction was successful. The behavior is undefined if other threads are @@ -81,23 +81,23 @@ currently waiting on this condition variable. `condition`: The SbConditionVariable to be destroyed. This invalidates the condition variable. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableDestroy(SbConditionVariable *condition) ``` -### SbConditionVariableIsSignaled ### +### SbConditionVariableIsSignaled Returns whether the given result is a success. -#### Declaration #### +#### Declaration ``` static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) ``` -### SbConditionVariableSignal ### +### SbConditionVariableSignal Signals the next waiter of `condition` to stop waiting. This function wakes a single thread waiting on `condition` while SbConditionVariableBroadcast wakes @@ -105,24 +105,24 @@ all threads waiting on it. `condition`: The condition that the waiter should stop waiting for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableSignal(SbConditionVariable *condition) ``` -### SbConditionVariableWait ### +### SbConditionVariableWait Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, and returning the result. Behavior is undefined if `mutex` is not held. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) ``` -### SbConditionVariableWaitTimed ### +### SbConditionVariableWaitTimed Waits for `condition`, releasing the held lock `mutex`, blocking up to `timeout_duration`, and returning the acquisition result. Behavior is undefined @@ -133,7 +133,7 @@ if `mutex` is not held. function returns as quickly as possible with a kSbConditionVariableTimedOut result. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime 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 630f1cf32228..d0ba3c7196f8 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/15/configuration.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration.h` Provides a description of the current platform in lurid detail so that common code never needs to actually know what the current operating system and @@ -13,117 +13,117 @@ Configuration feature instead. This implies the continued existence of very narrowly-defined configuration features, but it retains porting control in Starboard. -## Macros ## +## Macros -### SB_ALIGNAS(byte_alignment) ### +### SB_ALIGNAS(byte_alignment) Specifies the alignment for a class, struct, union, enum, class/struct field, or stack variable. -### SB_ALIGNOF(type) ### +### SB_ALIGNOF(type) Returns the alignment required for any instance of the type indicated by `type`. -### SB_ARRAY_SIZE(array) ### +### SB_ARRAY_SIZE(array) A constant expression that evaluates to the size_t size of a statically-sized array. -### SB_ARRAY_SIZE_INT(array) ### +### SB_ARRAY_SIZE_INT(array) A constant expression that evaluates to the int size of a statically-sized array. -### SB_CAN(SB_FEATURE) ### +### SB_CAN(SB_FEATURE) Determines a compile-time capability of the system. -### SB_COMPILE_ASSERT(expr, msg) ### +### SB_COMPILE_ASSERT(expr, msg) Will cause a compiler error with `msg` if `expr` is false. `msg` must be a valid identifier, and must be a unique type in the scope of the declaration. -### SB_DEPRECATED(FUNC) ### +### SB_DEPRECATED(FUNC) SB_DEPRECATED(int Foo(int bar)); Annotates the function as deprecated, which will trigger a compiler warning when referenced. -### SB_DEPRECATED_EXTERNAL(FUNC) ### +### SB_DEPRECATED_EXTERNAL(FUNC) SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION ### +### 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 ### +### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for logging. -### SB_HAS(SB_FEATURE) ### +### SB_HAS(SB_FEATURE) Determines at compile-time whether this platform has a standard feature or header available. -### SB_HAS_64_BIT_ATOMICS ### +### SB_HAS_64_BIT_ATOMICS Whether the current platform has 64-bit atomic operations. -### SB_HAS_GLES2 ### +### SB_HAS_GLES2 Specifies whether this platform has a performant OpenGL ES 2 implementation, which allows client applications to use GL rendering paths. Derived from the gyp variable `gl_type` gl_type which indicates what kind of GL implementation is available. -### SB_HAS_QUIRK(SB_FEATURE) ### +### SB_HAS_QUIRK(SB_FEATURE) Determines at compile-time whether this platform has a quirk. -### SB_INT64_C(x) ### +### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. -### SB_IS(SB_FEATURE) ### +### SB_IS(SB_FEATURE) Determines at compile-time an inherent aspect of this platform. -### SB_LIKELY(x) ### +### SB_LIKELY(x) Macro for hinting that an expression is likely to be true. -### SB_MAXIMUM_API_VERSION ### +### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, inclusive. -### SB_MINIMUM_API_VERSION ### +### SB_MINIMUM_API_VERSION The minimum API version allowed by this version of the Starboard headers, inclusive. -### SB_NORETURN ### +### SB_NORETURN Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE ### +### SB_OVERRIDE Declares a function as overriding a virtual function on compilers that support it. -### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA ### +### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. Setting this up properly means avoiding slow color swizzles when passing pixel data from one library to another. Note that these definitions are in byte-order and so are endianness-independent. -### SB_PRINTF_FORMAT(format_param, dots_param) ### +### SB_PRINTF_FORMAT(format_param, dots_param) Tells the compiler a function is using a printf-style format string. `format_param` is the one-based index of the format string parameter; @@ -132,7 +132,7 @@ functions (which take a va_list), pass 0 for dots_param. (This is undocumented but matches what the system C headers do.) (Partially taken from base/compiler_specific.h) -### SB_RESTRICT ### +### SB_RESTRICT 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 @@ -140,29 +140,29 @@ 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. -### SB_SIZE_OF(DATATYPE) ### +### SB_SIZE_OF(DATATYPE) Determines at compile-time the size of a data type, or 0 if the data type that was specified was invalid. -### SB_STRINGIFY(x) ### +### SB_STRINGIFY(x) Standard CPP trick to stringify an evaluated macro definition. -### SB_UINT64_C(x) ### +### SB_UINT64_C(x) Declare numeric literals of unsigned 64-bit type. -### SB_UNLIKELY(x) ### +### SB_UNLIKELY(x) Macro for hinting that an expression is likely to be false. -### SB_UNREFERENCED_PARAMETER(x) ### +### SB_UNREFERENCED_PARAMETER(x) Trivially references a parameter that is otherwise unreferenced, preventing a compiler warning on some platforms. -### SB_WARN_UNUSED_RESULT ### +### SB_WARN_UNUSED_RESULT Causes the annotated (at the end) function to generate a warning if the result is not accessed. diff --git a/cobalt/site/docs/reference/starboard/modules/15/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/15/configuration_constants.md index 99d92f822809..18af4bc2945c 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/15/configuration_constants.md @@ -1,113 +1,113 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration_constants.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration_constants.h` Declares all configuration variables we will need to use at runtime. These variables describe the current platform in detail to allow cobalt to make runtime decisions based on per platform configurations. -## Variables ## +## Variables -### kSbDefaultMmapThreshold ### +### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if available), rather than allocated within the core heap. -### kSbFileAltSepChar ### +### kSbFileAltSepChar The current platform's alternate file path component separator character. This is like SB_FILE_SEP_CHAR, except if your platform supports an alternate character, then you can place that here. For example, on windows machines, the primary separator character is probably '\', but the alternate is '/'. -### kSbFileAltSepString ### +### kSbFileAltSepString The string form of SB_FILE_ALT_SEP_CHAR. -### kSbFileMaxName ### +### kSbFileMaxName The current platform's maximum length of the name of a single directory entry, not including the absolute path. -### kSbFileMaxOpen ### +### kSbFileMaxOpen The current platform's maximum number of files that can be opened at the same time by one process. -### kSbFileMaxPath ### +### kSbFileMaxPath The current platform's maximum length of an absolute path. -### kSbFileSepChar ### +### kSbFileSepChar The current platform's file path component separator character. This is the character that appears after a directory in a file path. For example, the absolute canonical path of the file "/path/to/a/file.txt" uses '/' as a path component separator character. -### kSbFileSepString ### +### kSbFileSepString The string form of SB_FILE_SEP_CHAR. -### kSbHasMediaWebmVp9Support ### +### kSbHasMediaWebmVp9Support Specifies whether this platform has webm/vp9 support. This should be set to non- zero on platforms with webm/vp9 support. -### kSbHasThreadPrioritySupport ### +### kSbHasThreadPrioritySupport Whether the current platform supports thread priorities. -### kSbMallocAlignment ### +### kSbMallocAlignment Determines the alignment that allocations should have on this platform. -### kSbMaxSystemPathCacheDirectorySize ### +### kSbMaxSystemPathCacheDirectorySize The maximum size the cache directory is allowed to use in bytes. -### kSbMaxThreadLocalKeys ### +### kSbMaxThreadLocalKeys The maximum number of thread local storage keys supported by this platform. This comes from _POSIX_THREAD_KEYS_MAX. The value of PTHREAD_KEYS_MAX is higher, but unit tests show that the implementation doesn't support nearly as many keys. -### kSbMaxThreadNameLength ### +### kSbMaxThreadNameLength The maximum length of the name for a thread, including the NULL-terminator. -### kSbMaxThreads ### +### kSbMaxThreads Defines the maximum number of simultaneous threads for this platform. Some platforms require sharing thread handles with other kinds of system handles, like mutexes, so we want to keep this manageable. -### kSbMediaMaxAudioBitrateInBitsPerSecond ### +### kSbMediaMaxAudioBitrateInBitsPerSecond The maximum audio bitrate the platform can decode. The following value equals to 5M bytes per seconds which is more than enough for compressed audio. -### kSbMediaMaxVideoBitrateInBitsPerSecond ### +### kSbMediaMaxVideoBitrateInBitsPerSecond The maximum video bitrate the platform can decode. The following value equals to 8M bytes per seconds which is more than enough for compressed video. -### kSbMediaVideoFrameAlignment ### +### kSbMediaVideoFrameAlignment Specifies how video frame buffers must be aligned on this platform. -### kSbMemoryLogPath ### +### kSbMemoryLogPath Defines the path where memory debugging logs should be written to. -### kSbMemoryPageSize ### +### kSbMemoryPageSize The memory page size, which controls the size of chunks on memory that allocators deal with, and the alignment of those chunks. This doesn't have to be the hardware-defined physical page size, but it should be a multiple of it. -### kSbNetworkReceiveBufferSize ### +### kSbNetworkReceiveBufferSize Specifies the network receive buffer size in bytes, set via SbSocketSetReceiveBufferSize(). @@ -122,7 +122,7 @@ affect throughput in the presence of latency. If your platform does not have a good TCP auto-tuning mechanism, a setting of (128 * 1024) here is recommended. -### kSbPathSepChar ### +### kSbPathSepChar The current platform's search path component separator character. When specifying an ordered list of absolute paths of directories to search for a @@ -130,16 +130,16 @@ given reason, this is the character that appears between entries. For example, the search path of "/etc/search/first:/etc/search/second" uses ':' as a search path component separator character. -### kSbPathSepString ### +### kSbPathSepString The string form of SB_PATH_SEP_CHAR. -### kSbPreferredRgbaByteOrder ### +### kSbPreferredRgbaByteOrder Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. -### kSbUserMaxSignedIn ### +### kSbUserMaxSignedIn The maximum number of users that can be signed in at the same time. 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 7a4bcc05ddd0..e2aa35f2bb1a 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/15/cpu_features.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: cpu_features.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml -## Structs ## +# Starboard Module Reference: `cpu_features.h` -### SbCPUFeatures ### +## Structs -#### Members #### +### SbCPUFeatures + +#### Members * `SbCPUFeaturesArchitecture architecture` @@ -54,9 +54,9 @@ title: "Starboard Module Reference: cpu_features.h" defined as a macro. * `SbCPUFeaturesX86 x86` -### SbCPUFeaturesARM ### +### SbCPUFeaturesARM -#### Members #### +#### Members * `int16_t implementer` @@ -98,7 +98,7 @@ title: "Starboard Module Reference: cpu_features.h" SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags ###### + ###### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -114,17 +114,17 @@ title: "Starboard Module Reference: cpu_features.h" 64-bit PMULL and PMULL2 instructions. -### SbCPUFeaturesMIPS ### +### SbCPUFeaturesMIPS -#### Members #### +#### Members * `bool has_msa` MIPS SIMD Architecture (MSA). -### SbCPUFeaturesX86 ### +### SbCPUFeaturesX86 -#### Members #### +#### Members * `const char * vendor` @@ -244,9 +244,9 @@ title: "Starboard Module Reference: cpu_features.h" SAHF in long mode. -## Functions ## +## Functions -### SbCPUFeaturesGet ### +### SbCPUFeaturesGet Retrieve the underlying CPU features and place it in `features`, which must not be NULL. @@ -254,7 +254,7 @@ be NULL. If this function returns false, it means the CPU architecture is unknown and all fields in `features` are invalid. -#### Declaration #### +#### Declaration ``` 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 a237ad98c81b..1e98db5db54d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/15/decode_target.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: decode_target.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `decode_target.h` A target for decoding image and video data into. This corresponds roughly to an EGLImage, but that extension may not be fully supported on all GL platforms. @@ -12,7 +12,7 @@ data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. -## SbDecodeTargetFormat ## +## SbDecodeTargetFormat SbDecodeTargets support several different formats that can be used to decode into and render from. Some formats may be easier to decode into, and others may @@ -21,7 +21,7 @@ the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. -## SbDecodeTargetGraphicsContextProvider ## +## SbDecodeTargetGraphicsContextProvider Some components may need to acquire SbDecodeTargets compatible with a certain rendering context, which may need to be created on a particular thread. The @@ -36,7 +36,7 @@ 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 ## +## 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. @@ -79,15 +79,15 @@ GLuint texture = info.planes[kSbDecodeTargetPlaneRGBA].texture; ``` -## Macros ## +## Macros -### kSbDecodeTargetInvalid ### +### kSbDecodeTargetInvalid Well-defined value for an invalid decode target handle. -## Enums ## +## Enums -### SbDecodeTargetFormat ### +### SbDecodeTargetFormat The list of all possible decoder target formats. An SbDecodeTarget consists of one or more planes of data, each plane corresponding with a surface. For some @@ -96,7 +96,7 @@ formats, different planes will be different sizes for the same dimensions. NOTE: For enumeration entries with an alpha component, the alpha will always be premultiplied unless otherwise explicitly specified. -#### Values #### +#### Values * `kSbDecodeTargetFormat1PlaneRGBA` @@ -137,11 +137,11 @@ premultiplied unless otherwise explicitly specified. An invalid decode target format. -### SbDecodeTargetPlane ### +### SbDecodeTargetPlane All the planes supported by SbDecodeTarget. -#### Values #### +#### Values * `kSbDecodeTargetPlaneRGBA` @@ -162,45 +162,45 @@ All the planes supported by SbDecodeTarget. The V plane for 3-plane YUV formats. -## Typedefs ## +## Typedefs -### SbDecodeTarget ### +### SbDecodeTarget A handle to a target for image data decoding. -#### Definition #### +#### Definition ``` typedef SbDecodeTargetPrivate* SbDecodeTarget ``` -### SbDecodeTargetGlesContextRunner ### +### SbDecodeTargetGlesContextRunner Signature for a function provided by the application to the Starboard implementation that will let the Starboard implementation run arbitrary code on the application's renderer thread with the application's EGLContext held current. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunner) (struct SbDecodeTargetGraphicsContextProvider *graphics_context_provider, SbDecodeTargetGlesContextRunnerTarget target_function, void *target_function_context) ``` -### SbDecodeTargetGlesContextRunnerTarget ### +### SbDecodeTargetGlesContextRunnerTarget Signature for a Starboard implementation function that is to be run by a SbDecodeTargetGlesContextRunner callback. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunnerTarget) (void *gles_context_runner_target_context) ``` -## Structs ## +## Structs -### SbDecodeTargetGraphicsContextProvider ### +### SbDecodeTargetGraphicsContextProvider In general, the SbDecodeTargetGraphicsContextProvider structure provides information about the graphics context that will be used to render @@ -210,7 +210,7 @@ References to SbDecodeTargetGraphicsContextProvider objects should be provided to all Starboard functions that might create SbDecodeTargets (e.g. SbImageDecode()). -#### Members #### +#### Members * `void * egl_display` @@ -233,12 +233,12 @@ SbImageDecode()). Context data that is to be passed in to `gles_context_runner` when it is invoked. -### SbDecodeTargetInfo ### +### SbDecodeTargetInfo Contains all information about a decode target, including all of its planes. This can be queried via calls to SbDecodeTargetGetInfo(). -#### Members #### +#### Members * `SbDecodeTargetFormat format` @@ -267,11 +267,11 @@ This can be queried via calls to SbDecodeTargetGetInfo(). kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode target. -### SbDecodeTargetInfoContentRegion ### +### SbDecodeTargetInfoContentRegion Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. -#### Members #### +#### Members * `float left` @@ -283,11 +283,11 @@ Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. * `float right` * `float bottom` -### SbDecodeTargetInfoPlane ### +### SbDecodeTargetInfoPlane Defines an image plane within a SbDecodeTargetInfo object. -#### Members #### +#### Members * `uint32_t texture` @@ -317,53 +317,53 @@ Defines an image plane within a SbDecodeTargetInfo object. these parameters are number of pixels. The range for left/right is [0, width], and for top/bottom it is [0, height]. -## Functions ## +## Functions -### PrivateDecodeTargetReleaser ### +### PrivateDecodeTargetReleaser This function is just an implementation detail of SbDecodeTargetReleaseInGlesContext() and should not be called directly. -#### Declaration #### +#### Declaration ``` static void PrivateDecodeTargetReleaser(void *context) ``` -### SbDecodeTargetGetInfo ### +### SbDecodeTargetGetInfo Writes all information about `decode_target` into `out_info`. The `decode_target` must not be kSbDecodeTargetInvalid. The `out_info` pointer must not be NULL. Returns false if the provided `out_info` structure is not zero initialized. -#### Declaration #### +#### Declaration ``` bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target, SbDecodeTargetInfo *out_info) ``` -### SbDecodeTargetIsFormatValid ### +### SbDecodeTargetIsFormatValid Returns whether a given format is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsFormatValid(SbDecodeTargetFormat format) ``` -### SbDecodeTargetIsValid ### +### SbDecodeTargetIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsValid(SbDecodeTarget handle) ``` -### SbDecodeTargetRelease ### +### SbDecodeTargetRelease Returns ownership of `decode_target` to the Starboard implementation. This function will likely result in the destruction of the SbDecodeTarget and all its @@ -371,31 +371,31 @@ 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 -#### Declaration #### +#### Declaration ``` void SbDecodeTargetRelease(SbDecodeTarget decode_target) ``` -### SbDecodeTargetReleaseInGlesContext ### +### SbDecodeTargetReleaseInGlesContext Helper function that is possibly useful to Starboard implementations that will release a decode target on the thread with the GLES context current. -#### Declaration #### +#### Declaration ``` static void SbDecodeTargetReleaseInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTarget decode_target) ``` -### SbDecodeTargetRunInGlesContext ### +### SbDecodeTargetRunInGlesContext Inline convenience function to run an arbitrary SbDecodeTargetGlesContextRunnerTarget function through a SbDecodeTargetGraphicsContextProvider . This is intended to be called by Starboard implementations, if it is necessary. -#### Declaration #### +#### Declaration ``` 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 dcdf48a0e479..6f845f6567a9 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/15/directory.md @@ -1,56 +1,56 @@ ---- -layout: doc -title: "Starboard Module Reference: directory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `directory.h` Provides directory listing functions. -## Macros ## +## Macros -### kSbDirectoryInvalid ### +### kSbDirectoryInvalid Well-defined value for an invalid directory stream handle. -## Typedefs ## +## Typedefs -### SbDirectory ### +### SbDirectory A handle to an open directory stream. -#### Definition #### +#### Definition ``` typedef struct SbDirectoryPrivate* SbDirectory ``` -## Functions ## +## Functions -### SbDirectoryCanOpen ### +### SbDirectoryCanOpen Indicates whether SbDirectoryOpen is allowed for the given `path`. `path`: The path to be checked. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCanOpen(const char *path) ``` -### SbDirectoryClose ### +### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the directory was closed successfully. `directory`: The directory stream handle to close. -#### Declaration #### +#### Declaration ``` bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate ### +### SbDirectoryCreate Creates the directory `path`, assuming the parent directory already exists. This function returns `true` if the directory now exists (even if it existed before) @@ -58,13 +58,13 @@ and returns `false` if the directory does not exist. `path`: The path to be created. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCreate(const char *path) ``` -### SbDirectoryGetNext ### +### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and moves the stream forward by one entry. @@ -83,23 +83,23 @@ entry. The space allocated for this string should be equal to `out_entry_size`. `out_entry_size`: The size of the space allocated for `out_entry`. This should be at least equal to kSbFileMaxName. -#### Declaration #### +#### Declaration ``` bool SbDirectoryGetNext(SbDirectory directory, char *out_entry, size_t out_entry_size) ``` -### SbDirectoryIsValid ### +### SbDirectoryIsValid Returns whether the given directory stream handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDirectoryIsValid(SbDirectory directory) ``` -### SbDirectoryOpen ### +### SbDirectoryOpen Opens the given existing directory for listing. This function returns kSbDirectoryInvalidHandle if it is not successful. @@ -110,7 +110,7 @@ SbFileError code on failure. `out_error`: An output parameter that, in case of an error, is set to the reason that the directory could not be opened. -#### Declaration #### +#### Declaration ``` 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 fbb92f9ec841..f42e43bf3db7 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/15/drm.md @@ -1,37 +1,37 @@ ---- -layout: doc -title: "Starboard Module Reference: drm.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `drm.h` Provides definitions that allow for DRM support, which are common between Player and Decoder interfaces. -## Macros ## +## Macros -### kSbDrmSystemInvalid ### +### kSbDrmSystemInvalid An invalid SbDrmSystem. -### kSbDrmTicketInvalid ### +### kSbDrmTicketInvalid A ticket for callback invocations initiated by the DRM system. -## Enums ## +## Enums -### SbDrmEncryptionScheme ### +### SbDrmEncryptionScheme Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. -#### Values #### +#### Values * `kSbDrmEncryptionSchemeAesCtr` * `kSbDrmEncryptionSchemeAesCbc` -### SbDrmKeyStatus ### +### SbDrmKeyStatus Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) -#### Values #### +#### Values * `kSbDrmKeyStatusUsable` * `kSbDrmKeyStatusExpired` @@ -41,24 +41,24 @@ Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-de * `kSbDrmKeyStatusPending` * `kSbDrmKeyStatusError` -### SbDrmSessionRequestType ### +### SbDrmSessionRequestType The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype) -#### Values #### +#### Values * `kSbDrmSessionRequestTypeLicenseRequest` * `kSbDrmSessionRequestTypeLicenseRenewal` * `kSbDrmSessionRequestTypeLicenseRelease` * `kSbDrmSessionRequestTypeIndividualizationRequest` -### SbDrmStatus ### +### SbDrmStatus The status of session related operations. Used by `SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and `SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names) -#### Values #### +#### Values * `kSbDrmStatusSuccess` * `kSbDrmStatusTypeError` @@ -70,42 +70,42 @@ The status of session related operations. Used by The following error can be used when the error status cannot be mapped to one of the above errors. -## Typedefs ## +## Typedefs -### SbDrmServerCertificateUpdatedFunc ### +### SbDrmServerCertificateUpdatedFunc A callback to notify the caller of SbDrmUpdateServerCertificate() whether the update has been successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message) ``` -### SbDrmSessionClosedFunc ### +### SbDrmSessionClosedFunc A callback for signalling that a session has been closed by the SbDrmSystem -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size) ``` -### SbDrmSessionKeyStatusesChangedFunc ### +### SbDrmSessionKeyStatusesChangedFunc A callback for notifications that the status of one or more keys in a session has been changed. All keys of the session and their new status will be passed along. Any keys not in the list is considered as deleted. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses) ``` -### SbDrmSessionUpdateRequestFunc ### +### SbDrmSessionUpdateRequestFunc A callback that will receive generated session update request when requested from a SbDrmSystem. `drm_system` will be the DRM system that @@ -128,13 +128,13 @@ there was an error generating the request. This allows Cobalt to find and reject the correct Promise corresponding to the associated SbDrmGenerateSessionUpdateRequest(). -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url) ``` -### SbDrmSessionUpdatedFunc ### +### SbDrmSessionUpdatedFunc A callback for notifications that a session has been added, and subsequent encrypted samples are actively ready to be decoded. `drm_system` will be the DRM @@ -150,37 +150,37 @@ context passed into that call to SbDrmCreateSystem(). `status` is `kSbDrmStatusSuccess` or if no error message can be provided. `succeeded` is whether the session was successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size) ``` -### SbDrmSystem ### +### SbDrmSystem A handle to a DRM system which can be used with either an SbDecoder or an SbPlayer. -#### Definition #### +#### Definition ``` typedef struct SbDrmSystemPrivate* SbDrmSystem ``` -## Structs ## +## Structs -### SbDrmEncryptionPattern ### +### SbDrmEncryptionPattern Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. -#### Members #### +#### Members * `uint32_t crypt_byte_block` * `uint32_t skip_byte_block` -### SbDrmKeyId ### +### SbDrmKeyId -#### Members #### +#### Members * `uint8_t identifier` @@ -188,11 +188,11 @@ Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. PlayReady, this is the license GUID in packed little-endian binary form. * `int identifier_size` -### SbDrmSampleInfo ### +### SbDrmSampleInfo All the optional information needed per sample for encrypted samples. -#### Members #### +#### Members * `SbDrmEncryptionScheme encryption_scheme` @@ -217,13 +217,13 @@ All the optional information needed per sample for encrypted samples. The clear/encrypted mapping of each subsample in this sample. This must be an array of `subsample_count` mappings. -### SbDrmSubSampleMapping ### +### SbDrmSubSampleMapping A mapping of clear and encrypted bytes for a single subsample. All subsamples within a sample must be encrypted with the same encryption parameters. The clear bytes always appear first in the sample. -#### Members #### +#### Members * `int32_t clear_byte_count` @@ -232,21 +232,21 @@ bytes always appear first in the sample. How many bytes of the corresponding subsample are encrypted. -## Functions ## +## Functions -### SbDrmCloseSession ### +### SbDrmCloseSession Clear any internal states/resources related to the specified `session_id`. `drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` -### SbDrmDestroySystem ### +### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and invalidates all outstanding session update requests. A DRM system cannot be @@ -258,13 +258,13 @@ SbDrmCreateSystem(), a deadlock will occur. `drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` void SbDrmDestroySystem(SbDrmSystem drm_system) ``` -### SbDrmGenerateSessionUpdateRequest ### +### SbDrmGenerateSessionUpdateRequest Asynchronously generates a session update request payload for `initialization_data`, of `initialization_data_size`, in case sensitive `type`, @@ -296,13 +296,13 @@ be NULL. `initialization_data`: The data for which the session update request payload is created. Must not be NULL. `initialization_data_size`: The size of the session update request payload. -#### Declaration #### +#### Declaration ``` void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size) ``` -### SbDrmGetMetrics ### +### SbDrmGetMetrics Get the metrics of the underlying drm system. @@ -326,13 +326,13 @@ system, or when the drm system implementation fails to retrieve the metrics. `drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL. -#### Declaration #### +#### Declaration ``` const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size) ``` -### SbDrmIsServerCertificateUpdatable ### +### SbDrmIsServerCertificateUpdatable Returns true if server certificate of `drm_system` can be updated via SbDrmUpdateServerCertificate(). The return value should remain the same during @@ -341,33 +341,33 @@ the life time of `drm_system`. `drm_system`: The DRM system to check if its server certificate is updatable. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system) ``` -### SbDrmSystemIsValid ### +### SbDrmSystemIsValid Indicates whether `drm_system` is a valid SbDrmSystem. -#### Declaration #### +#### Declaration ``` static bool SbDrmSystemIsValid(SbDrmSystem drm) ``` -### SbDrmTicketIsValid ### +### SbDrmTicketIsValid Indicates whether `ticket` is a valid ticket. -#### Declaration #### +#### Declaration ``` static bool SbDrmTicketIsValid(int ticket) ``` -### SbDrmUpdateServerCertificate ### +### SbDrmUpdateServerCertificate Update the server certificate of `drm_system`. The function can be called multiple times. It is possible that a call to it happens before the callback of @@ -384,13 +384,13 @@ requests with the same ticket may result in undefined behavior. The value certificate data. Must not be NULL. `certificate_size`: Size of the server certificate data. -#### Declaration #### +#### Declaration ``` void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size) ``` -### SbDrmUpdateSession ### +### SbDrmUpdateSession Update session with `key`, in `drm_system`'s key system, from the license server response. Calls `session_updated_callback` with `context` and whether the update @@ -410,7 +410,7 @@ with that DRM key system will be able to decrypt encrypted samples. thread before this function returns or from another thread. The `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` 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 c8c2120b0acf..4afff1aa236e 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/15/egl.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: egl.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `egl.h` The EGL API provides an interface with accompanying type declarations and defines that together provide a single consistent method of EGL usage across @@ -11,67 +11,67 @@ 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 functions from EGL 1.5 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_EGL_ALPHA_FORMAT ### +### SB_EGL_ALPHA_FORMAT EGL_VERSION_1_2 -### SB_EGL_ALPHA_SIZE ### +### SB_EGL_ALPHA_SIZE EGL_VERSION_1_0 -### SB_EGL_BACK_BUFFER ### +### SB_EGL_BACK_BUFFER EGL_VERSION_1_1 -### SB_EGL_CONFORMANT ### +### SB_EGL_CONFORMANT EGL_VERSION_1_3 -### SB_EGL_CONTEXT_MAJOR_VERSION ### +### SB_EGL_CONTEXT_MAJOR_VERSION EGL_VERSION_1_5 -### SB_EGL_DEFAULT_DISPLAY ### +### SB_EGL_DEFAULT_DISPLAY EGL_VERSION_1_4 -## Typedefs ## +## Typedefs -### SbEglCastsToProperFunctionPointerType ### +### SbEglCastsToProperFunctionPointerType The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/egl.h](https://www.khronos.org/registry/EGL/api/EGL/egl.h) . -#### Definition #### +#### Definition ``` typedef void(* SbEglCastsToProperFunctionPointerType) (void) ``` -### SbEglInt32 ### +### SbEglInt32 The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h](https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h) . -#### Definition #### +#### Definition ``` typedef int32_t SbEglInt32 ``` -## Structs ## +## Structs -### SbEglInterface ### +### SbEglInterface -#### Members #### +#### Members * `SbEglBoolean(*eglChooseConfig)(SbEglDisplay dpy, const SbEglInt32 *attrib_list, SbEglConfig *configs, SbEglInt32 config_size, SbEglInt32 diff --git a/cobalt/site/docs/reference/starboard/modules/15/event.md b/cobalt/site/docs/reference/starboard/modules/15/event.md index 58cb1f4d1390..d8bab06a5538 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/event.md +++ b/cobalt/site/docs/reference/starboard/modules/15/event.md @@ -1,11 +1,11 @@ ---- -layout: doc -title: "Starboard Module Reference: event.h" ---- +Project: /youtube/cobalt/_project.yaml +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 ``` * ---------- @@ -78,15 +78,15 @@ for a more graceful shutdown. Note that the application is always expected to transition through `BLURRED`, `CONCEALED` to `FROZEN` before receiving `Stop` or being killed. -## Enums ## +## Enums -### SbEventType ### +### SbEventType An enumeration of all possible event types dispatched directly by the system. Each event is accompanied by a void* data argument, and each event must define the type of the value pointed to by that data argument, if any. -#### Values #### +#### Values * `kSbEventTypePreload` @@ -273,55 +273,55 @@ the type of the value pointed to by that data argument, if any. change in the timezone setting). This should trigger the application to re- query the relevant APIs to update the date and time. -## Typedefs ## +## Typedefs -### SbEventCallback ### +### SbEventCallback A function that can be called back from the main Starboard event pump. -#### Definition #### +#### Definition ``` typedef void(* SbEventCallback) (void *context) ``` -### SbEventDataDestructor ### +### SbEventDataDestructor A function that will cleanly destroy an event data instance of a specific type. -#### Definition #### +#### Definition ``` typedef void(* SbEventDataDestructor) (void *data) ``` -### SbEventId ### +### SbEventId An ID that can be used to refer to a scheduled event. -#### Definition #### +#### Definition ``` typedef uint32_t SbEventId ``` -## Structs ## +## Structs -### SbEvent ### +### SbEvent Structure representing a Starboard event and its data. -#### Members #### +#### Members * `SbEventType type` * `SbTimeMonotonic timestamp` * `void * data` -### SbEventStartData ### +### SbEventStartData Event data for kSbEventTypeStart events. -#### Members #### +#### Members * `char ** argument_values` @@ -333,31 +333,31 @@ Event data for kSbEventTypeStart events. The startup link, if any. -### SbEventWindowSizeChangedData ### +### SbEventWindowSizeChangedData Event data for kSbEventTypeWindowSizeChanged events. -#### Members #### +#### Members * `SbWindow window` * `SbWindowSize size` -## Functions ## +## Functions -### SbEventCancel ### +### SbEventCancel Cancels the specified `event_id`. Note that this function is a no-op if the event already fired. This function can be safely called from any thread, but the only way to guarantee that the event does not run anyway is to call it from the main Starboard event loop thread. -#### Declaration #### +#### Declaration ``` void SbEventCancel(SbEventId event_id) ``` -### SbEventHandle ### +### SbEventHandle The entry point that Starboard applications MUST implement. Any memory pointed at by `event` or the `data` field inside `event` is owned by the system, and @@ -370,23 +370,23 @@ specification about what other work might happen on this thread, so the application should generally do as little work as possible on this thread, and just dispatch it over to another thread. -#### Declaration #### +#### Declaration ``` SB_EXPORT_PLATFORM void SbEventHandle(const SbEvent *event) ``` -### SbEventIsIdValid ### +### SbEventIsIdValid Returns whether the given event handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbEventIsIdValid(SbEventId handle) ``` -### SbEventSchedule ### +### SbEventSchedule Schedules an event `callback` into the main Starboard event loop. This function may be called from any thread, but `callback` is always called from the main @@ -397,18 +397,18 @@ context that is passed to the `callback` function. `delay`: The minimum number of microseconds to wait before calling the `callback` function. Set `delay` to `0` to call the callback as soon as possible. -#### Declaration #### +#### Declaration ``` SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) ``` -### SbRunStarboardMain ### +### SbRunStarboardMain Serves as the entry point in the Starboard library for running the Starboard event loop with the application event handler. -#### Declaration #### +#### Declaration ``` int SbRunStarboardMain(int argc, char **argv, SbEventHandleCallback callback) diff --git a/cobalt/site/docs/reference/starboard/modules/15/export.md b/cobalt/site/docs/reference/starboard/modules/15/export.md index ff797770e824..a398d4ad0c85 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/export.md +++ b/cobalt/site/docs/reference/starboard/modules/15/export.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: export.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `export.h` Provides macros for properly exporting or importing symbols from shared libraries. -## Macros ## +## Macros -### SB_EXPORT ### +### SB_EXPORT Specification for a symbol that should be exported when building the DLL and imported when building code that uses the DLL. -### SB_EXPORT_PRIVATE ### +### SB_EXPORT_PRIVATE Specification for a symbol that should be exported or imported for testing purposes only. -### SB_IMPORT ### +### SB_IMPORT Specification for a symbol that is expected to be defined externally to this module. diff --git a/cobalt/site/docs/reference/starboard/modules/15/file.md b/cobalt/site/docs/reference/starboard/modules/15/file.md index 56eb415e677f..103af475ace1 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/file.md +++ b/cobalt/site/docs/reference/starboard/modules/15/file.md @@ -1,25 +1,25 @@ ---- -layout: doc -title: "Starboard Module Reference: file.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `file.h` Defines file system input/output functions. -## Macros ## +## Macros -### kSbFileInvalid ### +### kSbFileInvalid Well-defined value for an invalid file handle. -## Enums ## +## Enums -### SbFileError ### +### SbFileError kSbFileErrorAccessDenied is returned when a call fails because of a filesystem restriction. kSbFileErrorSecurity is returned when a security policy doesn't allow the operation to be executed. -#### Values #### +#### Values * `kSbFileOk` * `kSbFileErrorFailed` @@ -40,7 +40,7 @@ allow the operation to be executed. * `kSbFileErrorIO` * `kSbFileErrorMax` -### SbFileFlags ### +### SbFileFlags Flags that define how a file is used in the application. These flags should be or'd together when passed to SbFileOpen to open or create a file. @@ -66,7 +66,7 @@ In addition, one or more of the following flags must be specified: The `kSbFileAsync` flag is optional. -#### Values #### +#### Values * `kSbFileOpenOnly` * `kSbFileCreateOnly` @@ -85,35 +85,35 @@ The `kSbFileAsync` flag is optional. * `kSbFileWrite` * `kSbFileAsync` -### SbFileWhence ### +### SbFileWhence This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. -#### Values #### +#### Values * `kSbFileFromBegin` * `kSbFileFromCurrent` * `kSbFileFromEnd` -## Typedefs ## +## Typedefs -### SbFile ### +### SbFile A handle to an open file. -#### Definition #### +#### Definition ``` typedef SbFilePrivate* SbFile ``` -## Structs ## +## Structs -### SbFileInfo ### +### SbFileInfo Used to hold information about a file. -#### Members #### +#### Members * `int64_t size` @@ -134,9 +134,9 @@ Used to hold information about a file. The creation time of a file. -## Functions ## +## Functions -### SbFileAtomicReplace ### +### SbFileAtomicReplace Replaces the content of the file at `path` with `data`. Returns whether the contents of the file were replaced. The replacement of the content is an atomic @@ -146,39 +146,39 @@ operation. The file will either have all of the data, or none. to replace the file contents with. `data_size`: The amount of `data`, in bytes, to be written to the file. -#### Declaration #### +#### Declaration ``` bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size) ``` -### SbFileCanOpen ### +### SbFileCanOpen Indicates whether SbFileOpen() with the given `flags` is allowed for `path`. `path`: The absolute path to be checked. `flags`: The flags that are being evaluated for the given `path`. -#### Declaration #### +#### Declaration ``` bool SbFileCanOpen(const char *path, int flags) ``` -### SbFileClose ### +### SbFileClose Closes `file`. The return value indicates whether the file was closed successfully. `file`: The absolute path of the file to be closed. -#### Declaration #### +#### Declaration ``` bool SbFileClose(SbFile file) ``` -### SbFileDelete ### +### SbFileDelete Deletes the regular file, symlink, or empty directory at `path`. This function is used primarily to clean up after unit tests. On some platforms, this function @@ -186,38 +186,38 @@ fails if the file in question is being held open. `path`: The absolute path of the file, symlink, or directory to be deleted. -#### Declaration #### +#### Declaration ``` bool SbFileDelete(const char *path) ``` -### SbFileExists ### +### SbFileExists Indicates whether a file or directory exists at `path`. `path`: The absolute path of the file or directory being checked. -#### Declaration #### +#### Declaration ``` bool SbFileExists(const char *path) ``` -### SbFileFlush ### +### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed. `file`: The SbFile to which the write buffer is flushed. -#### Declaration #### +#### Declaration ``` bool SbFileFlush(SbFile file) ``` -### SbFileGetInfo ### +### SbFileGetInfo Retrieves information about `file`. The return value indicates whether the file information was retrieved successfully. @@ -226,13 +226,13 @@ information was retrieved successfully. into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetInfo(SbFile file, SbFileInfo *out_info) ``` -### SbFileGetPathInfo ### +### SbFileGetPathInfo Retrieves information about the file at `path`. The return value indicates whether the file information was retrieved successfully. @@ -241,36 +241,36 @@ whether the file information was retrieved successfully. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info) ``` -### SbFileIsValid ### +### SbFileIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbFileIsValid(SbFile file) ``` -### SbFileModeStringToFlags ### +### SbFileModeStringToFlags Converts an ISO `fopen()` mode string into flags that can be equivalently passed into SbFileOpen(). `mode`: The mode string to be converted into flags. -#### Declaration #### +#### Declaration ``` int SbFileModeStringToFlags(const char *mode) ``` -### SbFileOpen ### +### SbFileOpen Opens the file at `path`, which must be absolute, creating it if specified by `flags`. The read/write position is at the beginning of the file. @@ -287,13 +287,13 @@ which can happen if the `kSbFileCreateAlways` flag is set. Otherwise, Starboard sets this value to `false`. `out_error`: If `path` cannot be created, this is set to `kSbFileInvalid`. Otherwise, it is `NULL`. -#### Declaration #### +#### Declaration ``` SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error) ``` -### SbFileRead ### +### SbFileRead Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -306,13 +306,13 @@ However, this function can be run in a loop to make it a best-effort read. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` int SbFileRead(SbFile file, char *data, int size) ``` -### SbFileReadAll ### +### SbFileReadAll Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -326,13 +326,13 @@ be read unless there is an error. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` static int SbFileReadAll(SbFile file, char *data, int size) ``` -### SbFileSeek ### +### SbFileSeek Changes the current read/write position in `file`. The return value identifies the resultant current read/write position in the file (relative to the start) or @@ -344,13 +344,13 @@ The starting read/write position. The position is modified relative to this value. `offset`: The amount that the read/write position is changed, relative to `whence`. -#### Declaration #### +#### Declaration ``` int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset) ``` -### SbFileTruncate ### +### SbFileTruncate Truncates the given `file` to the given `length`. The return value indicates whether the file was truncated successfully. @@ -360,13 +360,13 @@ after it is truncated. If `length` is greater than the current size of the file, then the file is extended with zeros. If `length` is negative, then the function is a no-op and returns `false`. -#### Declaration #### +#### Declaration ``` bool SbFileTruncate(SbFile file, int64_t length) ``` -### SbFileWrite ### +### SbFileWrite Writes the given buffer into `file` at the file's current position, overwriting any data that was previously there. @@ -380,13 +380,13 @@ in a loop to ensure that all data is written. `file`: The SbFile to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` int SbFileWrite(SbFile file, const char *data, int size) ``` -### SbFileWriteAll ### +### SbFileWriteAll Writes the given buffer into `file`, starting at the beginning of the file, and overwriting any data that was previously there. Unlike SbFileWrite, this @@ -397,7 +397,7 @@ The return value identifies the number of bytes written, or `-1` on error. `file`: The file to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` 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 163d8d76aa41..77bc07e71c82 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/15/gles.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: gles.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `gles.h` The GLES API provides an interface with accompanying type declarations and defines that together provide a single consistent method of GLES usage across @@ -11,37 +11,37 @@ 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 the functions from GLES 3.0 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_GL_DEPTH_BUFFER_BIT ### +### SB_GL_DEPTH_BUFFER_BIT Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) -### SB_GL_READ_BUFFER ### +### SB_GL_READ_BUFFER Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h](https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h) . -## Typedefs ## +## Typedefs -### SbGlBoolean ### +### SbGlBoolean The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) . -#### Definition #### +#### Definition ``` typedef uint8_t SbGlBoolean ``` -### SbGlIntPtr ### +### SbGlIntPtr Some compilers will transform the intptr_t to an int transparently behind the scenes, which is not equivalent to a long int, or long long int, as far as the @@ -49,17 +49,17 @@ compiler is concerned. We check the Starboard configuration and set the types to those exact types used by OpenGL ES 2.0 ( [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h) ). -#### Definition #### +#### Definition ``` typedef long int SbGlIntPtr ``` -## Structs ## +## Structs -### SbGlesInterface ### +### SbGlesInterface -#### Members #### +#### Members * `void(*glActiveTexture)(SbGlEnum texture)` diff --git a/cobalt/site/docs/reference/starboard/modules/15/image.md b/cobalt/site/docs/reference/starboard/modules/15/image.md index 1427d3995d54..945938a09903 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/image.md +++ b/cobalt/site/docs/reference/starboard/modules/15/image.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: image.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `image.h` API for hardware accelerated image decoding. This module allows for the client to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It @@ -11,7 +11,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(); @@ -28,9 +28,9 @@ SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); ``` -## Functions ## +## Functions -### SbImageDecode ### +### SbImageDecode Attempt to decode encoded `mime_type` image data `data` of size `data_size` into an SbDecodeTarget of SbDecodeFormatType `format`, possibly using @@ -56,13 +56,13 @@ scenarios regarding the provider may happen: kSbDecodeTargetInvalid will be returned, with any intermediate allocations being cleaned up in the implementation. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) ``` -### SbImageIsDecodeSupported ### +### SbImageIsDecodeSupported Whether the current platform supports hardware accelerated decoding an image of mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must @@ -70,7 +70,7 @@ not be NULL. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. -#### Declaration #### +#### Declaration ``` 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 ec86793b7761..a858c73e3e89 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/input.md +++ b/cobalt/site/docs/reference/starboard/modules/15/input.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: input.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `input.h` Defines input events and associated data types. -## Enums ## +## Enums -### SbInputDeviceType ### +### SbInputDeviceType Identifies possible input subsystem types. The types of events that each device type produces correspond to `SbInputEventType` values. -#### Values #### +#### Values * `kSbInputDeviceTypeGesture` @@ -57,11 +57,11 @@ type produces correspond to `SbInputEventType` values. Produces `Input` events. -### SbInputEventType ### +### SbInputEventType The action that an input event represents. -#### Values #### +#### Values * `kSbInputEventTypeMove` @@ -86,13 +86,13 @@ The action that an input event represents. [https://w3c.github.io/uievents/#event-type-input](https://w3c.github.io/uievents/#event-type-input) -## Structs ## +## Structs -### SbInputData ### +### SbInputData Event data for `kSbEventTypeInput` events. -#### Members #### +#### Members * `SbWindow window` @@ -160,11 +160,11 @@ Event data for `kSbEventTypeInput` events. Set to true if the input event is part of a composition event. -### SbInputVector ### +### SbInputVector A 2-dimensional vector used to represent points and motion vectors. -#### Members #### +#### Members * `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 2835b20d70d9..ed87e531f4fc 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/key.md +++ b/cobalt/site/docs/reference/starboard/modules/15/key.md @@ -1,19 +1,19 @@ ---- -layout: doc -title: "Starboard Module Reference: key.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `key.h` Defines the canonical set of Starboard key codes. -## Enums ## +## Enums -### SbKey ### +### SbKey A standard set of key codes, ordered by value, that represent each possible input key across all kinds of devices. Starboard uses the semi-standard Windows virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx) -#### Values #### +#### Values * `kSbKeyUnknown` * `kSbKeyCancel` @@ -275,11 +275,11 @@ virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windo * `kSbKeyGamepadRightStickLeft` * `kSbKeyGamepadRightStickRight` -### SbKeyModifiers ### +### SbKeyModifiers Bit-mask of key modifiers. -#### Values #### +#### Values * `kSbKeyModifiersNone` * `kSbKeyModifiersAlt` diff --git a/cobalt/site/docs/reference/starboard/modules/15/log.md b/cobalt/site/docs/reference/starboard/modules/15/log.md index 42de5138c303..6cf3a491a2a7 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/log.md +++ b/cobalt/site/docs/reference/starboard/modules/15/log.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: log.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `log.h` Defines core debug logging functions. -## Enums ## +## Enums -### SbLogPriority ### +### SbLogPriority The priority at which a message should be logged. The platform may be configured to filter logs by priority, or render them differently. -#### Values #### +#### Values * `kSbLogPriorityUnknown` * `kSbLogPriorityInfo` @@ -20,9 +20,9 @@ to filter logs by priority, or render them differently. * `kSbLogPriorityError` * `kSbLogPriorityFatal` -## Functions ## +## Functions -### SbLog ### +### SbLog Writes `message` to the platform's debug output log. This method is thread-safe, and responsible for ensuring that the output from multiple threads is not mixed. @@ -35,55 +35,55 @@ NULL. No formatting is required to be done on the value, including newline termination. That said, platforms can adjust the message to be more suitable for their output method by wrapping the text, stripping unprintable characters, etc. -#### Declaration #### +#### Declaration ``` void SbLog(SbLogPriority priority, const char *message) ``` -### SbLogFlush ### +### SbLogFlush Flushes the log buffer on some platforms. This method is safe to call from multiple threads. -#### Declaration #### +#### Declaration ``` void SbLogFlush() ``` -### SbLogFormat ### +### SbLogFormat A log output method that additionally performs a string format on the data being logged. -#### Declaration #### +#### Declaration ``` void SbLogFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogFormatF ### +### SbLogFormatF Inline wrapper of SbLogFormat that converts from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` void static void static void SbLogFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` -### SbLogIsTty ### +### SbLogIsTty Indicates whether the log output goes to a TTY or is being redirected. -#### Declaration #### +#### Declaration ``` bool SbLogIsTty() ``` -### SbLogRaw ### +### SbLogRaw A bare-bones log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). It should not do any @@ -91,13 +91,13 @@ additional formatting. `message`: The message to be logged. Must not be NULL. -#### Declaration #### +#### Declaration ``` void SbLogRaw(const char *message) ``` -### SbLogRawDumpStack ### +### SbLogRawDumpStack Dumps the stack of the current thread to the log in an async-signal-safe manner, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` @@ -108,28 +108,28 @@ dumping the current thread to the log. This parameter lets you remove noise from helper functions that might end up on top of every stack dump so that the stack dump is just the relevant function stack where the problem occurred. -#### Declaration #### +#### Declaration ``` void SbLogRawDumpStack(int frames_to_skip) ``` -### SbLogRawFormat ### +### SbLogRawFormat A formatted log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). -#### Declaration #### +#### Declaration ``` void SbLogRawFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogRawFormatF ### +### SbLogRawFormatF Inline wrapper of SbLogFormat to convert from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` 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 132166c69955..e1c2ae5318e9 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/media.md +++ b/cobalt/site/docs/reference/starboard/modules/15/media.md @@ -1,28 +1,28 @@ ---- -layout: doc -title: "Starboard Module Reference: media.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `media.h` Provides media definitions that are common between the Decoder and Player interfaces. -## Macros ## +## Macros -### kSbMediaBitsPerPixelInvalid ### +### kSbMediaBitsPerPixelInvalid Value used when a video's bits per pixel is not known. -### kSbMediaVideoResolutionDimensionInvalid ### +### kSbMediaVideoResolutionDimensionInvalid Value used when a video's resolution is not known. -## Enums ## +## Enums -### SbMediaAudioCodec ### +### SbMediaAudioCodec Types of audio elementary streams that can be supported. -#### Values #### +#### Values * `kSbMediaAudioCodecNone` * `kSbMediaAudioCodecAac` @@ -35,11 +35,11 @@ Types of audio elementary streams that can be supported. * `kSbMediaAudioCodecPcm` * `kSbMediaAudioCodecIamf` -### SbMediaAudioCodingType ### +### SbMediaAudioCodingType Possible audio coding types. -#### Values #### +#### Values * `kSbMediaAudioCodingTypeNone` * `kSbMediaAudioCodingTypeAac` @@ -53,11 +53,11 @@ Possible audio coding types. * `kSbMediaAudioCodingTypeMpeg3` * `kSbMediaAudioCodingTypePcm` -### SbMediaAudioConnector ### +### SbMediaAudioConnector Possible audio connector types. -#### Values #### +#### Values * `kSbMediaAudioConnectorUnknown` * `kSbMediaAudioConnectorAnalog` @@ -76,11 +76,11 @@ Possible audio connector types. * `kSbMediaAudioConnectorSpdif` * `kSbMediaAudioConnectorUsb` -### SbMediaAudioFrameStorageType ### +### SbMediaAudioFrameStorageType Possible audio frame storage types. -#### Values #### +#### Values * `kSbMediaAudioFrameStorageTypeInterleaved` @@ -96,22 +96,22 @@ Possible audio frame storage types. with timestamps 0, 1, 2, etc., the samples are stored in two buffers "L0 L1 L2 ..." and "R0 R1 R2 ...". -### SbMediaAudioSampleType ### +### SbMediaAudioSampleType Possible audio sample types. -#### Values #### +#### Values * `kSbMediaAudioSampleTypeInt16Deprecated` * `kSbMediaAudioSampleTypeFloat32` -### SbMediaRangeId ### +### SbMediaRangeId This corresponds to the WebM Range enum which is part of WebM color data (see [http://www.webmproject.org/docs/container/#Range](http://www.webmproject.org/docs/container/#Range) ). H.264 only uses a bool, which corresponds to the LIMITED/FULL values. Chrome- specific values start at 1000. -#### Values #### +#### Values * `kSbMediaRangeIdUnspecified` @@ -127,13 +127,13 @@ specific values start at 1000. Range is defined by TransferId/MatrixId. * `kSbMediaRangeIdLast` -### SbMediaSupportType ### +### SbMediaSupportType Indicates how confident the device is that it can play media resources of the given type. The values are a direct map of the canPlayType() method specified at the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype](https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype) -#### Values #### +#### Values * `kSbMediaSupportTypeNotSupported` @@ -145,11 +145,11 @@ the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom The media type seems to be playable. -### SbMediaType ### +### SbMediaType Types of media component streams. -#### Values #### +#### Values * `kSbMediaTypeAudio` @@ -158,11 +158,11 @@ Types of media component streams. Value used for video streams. -### SbMediaVideoCodec ### +### SbMediaVideoCodec Types of video elementary streams that could be supported. -#### Values #### +#### Values * `kSbMediaVideoCodecNone` * `kSbMediaVideoCodecH264` @@ -174,14 +174,14 @@ Types of video elementary streams that could be supported. * `kSbMediaVideoCodecVp8` * `kSbMediaVideoCodecVp9` -## Structs ## +## Structs -### SbMediaAudioConfiguration ### +### SbMediaAudioConfiguration A structure describing the audio configuration parameters of a single audio output. -#### Members #### +#### Members * `SbMediaAudioConnector connector` @@ -200,11 +200,11 @@ output. `0` if this device cannot provide this information, in which case the caller can probably assume stereo output. -### SbMediaAudioSampleInfo ### +### SbMediaAudioSampleInfo The set of information required by the decoder or player for each audio sample. -#### Members #### +#### Members * `SbMediaAudioStreamInfo stream_info` @@ -212,11 +212,11 @@ The set of information required by the decoder or player for each audio sample. * `SbTime discarded_duration_from_front` * `SbTime discarded_duration_from_back` -### SbMediaAudioStreamInfo ### +### SbMediaAudioStreamInfo The set of information required by the decoder or player for each audio stream. -#### Members #### +#### Members * `SbMediaAudioCodec codec` @@ -242,14 +242,14 @@ The set of information required by the decoder or player for each audio stream. The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1: [http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF](http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF) -### SbMediaColorMetadata ### +### SbMediaColorMetadata HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR formats, together with the ColorSpace. HDR reproduces a greater dynamic range of luminosity than is possible with standard digital imaging. See the Consumer Electronics Association press release: [https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) -#### Members #### +#### Members * `unsigned int bits_per_channel` @@ -330,7 +330,7 @@ Electronics Association press release: [https://www.cta.tech/News/Press-Releases a row-major ordered 3 x 4 submatrix of the 4 x 4 transform matrix. The 4th row is completed as (0, 0, 0, 1). -### SbMediaMasteringMetadata ### +### SbMediaMasteringMetadata SMPTE 2086 mastering data [http://ieeexplore.ieee.org/document/7291707/](http://ieeexplore.ieee.org/document/7291707/) This standard specifies the metadata items to specify the color volume (the @@ -339,7 +339,7 @@ in mastering video content. The metadata is specified as a set of values independent of any specific digital representation. Also see the WebM container guidelines: [https://www.webmproject.org/docs/container/](https://www.webmproject.org/docs/container/) -#### Members #### +#### Members * `float primary_r_chromaticity_x` @@ -374,11 +374,11 @@ guidelines: [https://www.webmproject.org/docs/container/](https://www.webmprojec Minimum luminance. Shall be represented in candelas per square meter (cd/m^2). In range [0, 9999.99]. -### SbMediaVideoSampleInfo ### +### SbMediaVideoSampleInfo The set of information required by the decoder or player for each video sample. -#### Members #### +#### Members * `SbMediaVideoStreamInfo stream_info` @@ -388,11 +388,11 @@ The set of information required by the decoder or player for each video sample. Indicates whether the associated sample is a key frame (I-frame). Avc video key frames must always start with SPS and PPS NAL units. -### SbMediaVideoStreamInfo ### +### SbMediaVideoStreamInfo The set of information required by the decoder or player for each video stream. -#### Members #### +#### Members * `SbMediaVideoCodec codec` @@ -434,9 +434,9 @@ The set of information required by the decoder or player for each video stream. . This will only be specified on frames where the HDR metadata and color / color space might have changed (e.g. keyframes). -## Functions ## +## Functions -### SbMediaCanPlayMimeAndKeySystem ### +### SbMediaCanPlayMimeAndKeySystem Returns information about whether the playback of the specific media described by `mime` and encrypted using `key_system` can be played. @@ -480,13 +480,13 @@ return `kSbMediaSupportTypeProbably` kSbMediaSupportTypeProbably when implementation supports key system with attributes on one key system, it has to support key system with attributes on all key systems supported. -#### Declaration #### +#### Declaration ``` SbMediaSupportType SbMediaCanPlayMimeAndKeySystem(const char *mime, const char *key_system) ``` -### SbMediaGetAudioBufferBudget ### +### SbMediaGetAudioBufferBudget Specifies the maximum amount of memory used by audio buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -494,13 +494,13 @@ being used by audio buffers but will also make the app less likely to re- download audio data. Note that the app may experience significant difficulty if this value is too low. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioBufferBudget() ``` -### SbMediaGetAudioConfiguration ### +### SbMediaGetAudioConfiguration Retrieves the current physical audio configuration of audio output `output_index` on this device and places it in `out_configuration`, which must @@ -512,37 +512,37 @@ if `output_index` does not exist on this device. `out_configuration`: The variable that holds the audio configuration information. -#### Declaration #### +#### Declaration ``` bool SbMediaGetAudioConfiguration(int output_index, SbMediaAudioConfiguration *out_configuration) ``` -### SbMediaGetAudioOutputCount ### +### SbMediaGetAudioOutputCount Returns the number of audio outputs currently available on this device. Even if the number of outputs or their audio configurations can't be determined, it is expected that the platform will at least return a single output that supports at least stereo. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioOutputCount() ``` -### SbMediaGetBufferAlignment ### +### 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 #### +#### Declaration ``` int SbMediaGetBufferAlignment() ``` -### SbMediaGetBufferAllocationUnit ### +### SbMediaGetBufferAllocationUnit When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can @@ -550,13 +550,13 @@ 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferAllocationUnit() ``` -### SbMediaGetBufferGarbageCollectionDurationThreshold ### +### SbMediaGetBufferGarbageCollectionDurationThreshold Specifies the duration threshold of media source garbage collection. When the accumulated duration in a source buffer exceeds this value, the media source @@ -567,25 +567,25 @@ 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 #### +#### Declaration ``` SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() ``` -### SbMediaGetBufferPadding ### +### 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferPadding() ``` -### SbMediaGetBufferStorageType ### +### SbMediaGetBufferStorageType Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored @@ -595,26 +595,26 @@ by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when its value is "file" the media stack will still allocate memory to cache the the buffers in use. -#### Declaration #### +#### Declaration ``` SbMediaBufferStorageType SbMediaGetBufferStorageType() ``` -### SbMediaGetInitialBufferCapacity ### +### SbMediaGetInitialBufferCapacity The amount of memory that will be used to store media buffers allocated during system startup. To allocate a large chunk at startup helps with reducing fragmentation and can avoid failures to allocate incrementally. This can return 0. -#### Declaration #### +#### Declaration ``` int SbMediaGetInitialBufferCapacity() ``` -### SbMediaGetMaxBufferCapacity ### +### SbMediaGetMaxBufferCapacity The maximum amount of memory that will be used to store media buffers. This must be larger than sum of the video budget and audio budget. This is a soft limit @@ -629,13 +629,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetProgressiveBufferBudget ### +### SbMediaGetProgressiveBufferBudget The memory used when playing mp4 videos that is not in DASH format. The resolution of such videos shouldn't go beyond 1080p. Its value should be less @@ -647,13 +647,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetVideoBufferBudget ### +### SbMediaGetVideoBufferBudget Specifies the maximum amount of memory used by video buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -666,13 +666,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaIsBufferPoolAllocateOnDemand ### +### SbMediaIsBufferPoolAllocateOnDemand When either SbMediaGetInitialBufferCapacity or SbMediaGetBufferAllocationUnit isn't zero, media buffers will be allocated using a memory pool. Set the @@ -683,18 +683,18 @@ SbMediaGetInitialBufferCapacity bytes for media buffer on startup and will not release any media buffer memory back to the system even if there is no media buffers allocated. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferPoolAllocateOnDemand() ``` -### SbMediaIsBufferUsingMemoryPool ### +### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer pools should be allocated on demand, as opposed to using SbMemory* functions. -#### Declaration #### +#### 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 2fbf7dc94346..6dfa84442426 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/15/memory.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: memory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. -## Porters ## +## 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 @@ -26,14 +26,14 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. * The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). -## Enums ## +## Enums -### SbMemoryMapFlags ### +### SbMemoryMapFlags The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used. -#### Values #### +#### Values * `kSbMemoryMapProtectReserved` @@ -44,9 +44,9 @@ the mapped memory can be used. * `kSbMemoryMapProtectExec` * `kSbMemoryMapProtectReadWrite` -## Functions ## +## Functions -### SbMemoryAllocate ### +### SbMemoryAllocate Allocates and returns a chunk of memory of at least `size` bytes. This function should be called from the client codebase. It is intended to be a drop-in @@ -58,13 +58,13 @@ Note that this function returns `NULL` if it is unable to allocate the memory. return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocate(size_t size) ``` -### SbMemoryAllocateAligned ### +### SbMemoryAllocateAligned Allocates and returns a chunk of memory of at least `size` bytes, aligned to `alignment`. This function should be called from the client codebase. It is @@ -78,87 +78,87 @@ must be a power of two. `size`: The size of the memory to be allocated. If `size` is `0`, the function may return `NULL` or it may return a unique aligned pointer value that can be passed to SbMemoryDeallocateAligned. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAligned(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedChecked ### +### SbMemoryAllocateAlignedChecked Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedUnchecked ### +### SbMemoryAllocateAlignedUnchecked This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateChecked ### +### SbMemoryAllocateChecked Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateChecked(size_t size) ``` -### SbMemoryAllocateNoReport ### +### SbMemoryAllocateNoReport Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateNoReport(size_t size) ``` -### SbMemoryAllocateUnchecked ### +### SbMemoryAllocateUnchecked This is the implementation of SbMemoryAllocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateUnchecked(size_t size) ``` -### SbMemoryCalloc ### +### SbMemoryCalloc A wrapper that implements a drop-in replacement for `calloc`, which is used in some packages. -#### Declaration #### +#### Declaration ``` static void* SbMemoryCalloc(size_t count, size_t size) ``` -### SbMemoryDeallocate ### +### SbMemoryDeallocate Frees a previously allocated chunk of memory. If `memory` is NULL, then the operation is a no-op. This function should be called from the client codebase. @@ -166,74 +166,74 @@ It is meant to be a drop-in replacement for `free`. `memory`: The chunk of memory to be freed. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocate(void *memory) ``` -### SbMemoryDeallocateAligned ### +### SbMemoryDeallocateAligned `memory`: The chunk of memory to be freed. If `memory` is NULL, then the function is a no-op. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateAligned(void *memory) ``` -### SbMemoryDeallocateNoReport ### +### SbMemoryDeallocateNoReport Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport(). -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateNoReport(void *memory) ``` -### SbMemoryFlush ### +### SbMemoryFlush Flushes any data in the given virtual address range that is cached locally in the current processor core to physical memory, ensuring that data and instruction caches are cleared. This is required to be called on executable memory that has been written to and might be executed in the future. -#### Declaration #### +#### Declaration ``` void SbMemoryFlush(void *virtual_address, int64_t size_bytes) ``` -### SbMemoryFree ### +### SbMemoryFree This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocate(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFree(void *memory) ``` -### SbMemoryFreeAligned ### +### SbMemoryFreeAligned This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFreeAligned(void *memory) ``` -### SbMemoryMap ### +### SbMemoryMap Allocates `size_bytes` worth of physical memory pages and maps them into an available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on @@ -248,24 +248,24 @@ used, the address space will not be accessible and, if possible, the platform should not count it against any memory budget. `name`: A value that appears in the debugger on some platforms. The value can be up to 32 bytes. -#### Declaration #### +#### Declaration ``` void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) ``` -### SbMemoryProtect ### +### SbMemoryProtect Change the protection of `size_bytes` of memory regions, starting from `virtual_address`, to `flags`, returning `true` on success. -#### Declaration #### +#### Declaration ``` bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) ``` -### SbMemoryReallocate ### +### SbMemoryReallocate Attempts to resize `memory` to be at least `size` bytes, without touching the contents of memory. @@ -285,39 +285,39 @@ it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which `memory` will be resized. If `size` is `0`, the function may return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocate(void *memory, size_t size) ``` -### SbMemoryReallocateChecked ### +### SbMemoryReallocateChecked Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateChecked(void *memory, size_t size) ``` -### SbMemoryReallocateUnchecked ### +### SbMemoryReallocateUnchecked This is the implementation of SbMemoryReallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateUnchecked(void *memory, size_t size) ``` -### SbMemoryUnmap ### +### SbMemoryUnmap Unmap `size_bytes` of physical pages starting from `virtual_address`, returning `true` on success. After this function completes, [virtual_address, @@ -327,7 +327,7 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns `(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns `(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. -#### Declaration #### +#### Declaration ``` bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) diff --git a/cobalt/site/docs/reference/starboard/modules/15/microphone.md b/cobalt/site/docs/reference/starboard/modules/15/microphone.md index d760e1e7533f..bcf9e4355e65 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/15/microphone.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: microphone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `microphone.h` Defines functions for microphone creation, control, audio data fetching, and destruction. This module supports multiple calls to `SbMicrophoneOpen` and @@ -31,23 +31,23 @@ How to use this API: 1. Destroy the microphone with `SbMicrophoneDestroy`. -## Macros ## +## Macros -### kSbMicrophoneIdInvalid ### +### kSbMicrophoneIdInvalid Well-defined value for an invalid microphone ID handle. -### kSbMicrophoneInvalid ### +### kSbMicrophoneInvalid Well-defined value for an invalid microphone handle. -## Enums ## +## Enums -### SbMicrophoneType ### +### SbMicrophoneType All possible microphone types. -#### Values #### +#### Values * `kSbMicrophoneCamera` @@ -66,37 +66,37 @@ All possible microphone types. Unknown microphone type. The microphone could be different than the other enum descriptions or could fall under one of those descriptions. -## Typedefs ## +## Typedefs -### SbMicrophone ### +### SbMicrophone An opaque handle to an implementation-private structure that represents a microphone. -#### Definition #### +#### Definition ``` typedef struct SbMicrophonePrivate* SbMicrophone ``` -### SbMicrophoneId ### +### SbMicrophoneId An opaque handle to an implementation-private structure that represents a microphone ID. -#### Definition #### +#### Definition ``` typedef struct SbMicrophoneIdPrivate* SbMicrophoneId ``` -## Structs ## +## Structs -### SbMicrophoneInfo ### +### SbMicrophoneInfo Microphone information. -#### Members #### +#### Members * `SbMicrophoneId id` @@ -116,9 +116,9 @@ Microphone information. of the microphone type. For example, "Headset Microphone". The string must be null terminated. -## Functions ## +## Functions -### SbMicrophoneClose ### +### SbMicrophoneClose Closes the microphone port, stops recording audio on `microphone`, and clears the unread buffer if it is not empty. If the microphone has already been @@ -127,13 +127,13 @@ is closed. `microphone`: The microphone to close. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneClose(SbMicrophone microphone) ``` -### SbMicrophoneCreate ### +### SbMicrophoneCreate Creates a microphone with the specified ID, audio sample rate, and cached audio buffer size. Starboard only requires support for creating one microphone at a @@ -153,25 +153,25 @@ from the audio buffer if it has been read, and new audio data can be read from this buffer in smaller chunks than this size. This parameter must be set to a value greater than zero and the ideal size is `2^n`. -#### Declaration #### +#### Declaration ``` SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size_bytes) ``` -### SbMicrophoneDestroy ### +### SbMicrophoneDestroy Destroys a microphone. If the microphone is in started state, it is first stopped and then destroyed. Any data that has been recorded and not read is thrown away. -#### Declaration #### +#### Declaration ``` void SbMicrophoneDestroy(SbMicrophone microphone) ``` -### SbMicrophoneGetAvailable ### +### SbMicrophoneGetAvailable Retrieves all currently available microphone information and stores it in `out_info_array`. The return value is the number of the available microphones. @@ -184,43 +184,43 @@ indicates that an internal error occurred. placed into this output parameter. `info_array_size`: The size of `out_info_array`. -#### Declaration #### +#### Declaration ``` int SbMicrophoneGetAvailable(SbMicrophoneInfo *out_info_array, int info_array_size) ``` -### SbMicrophoneIdIsValid ### +### SbMicrophoneIdIsValid Indicates whether the given microphone ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIdIsValid(SbMicrophoneId id) ``` -### SbMicrophoneIsSampleRateSupported ### +### SbMicrophoneIsSampleRateSupported Indicates whether the microphone supports the sample rate. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz) ``` -### SbMicrophoneIsValid ### +### SbMicrophoneIsValid Indicates whether the given microphone is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIsValid(SbMicrophone microphone) ``` -### SbMicrophoneOpen ### +### SbMicrophoneOpen Opens the microphone port and starts recording audio on `microphone`. @@ -230,13 +230,13 @@ clears the unread buffer. The return value indicates whether the microphone is open. `microphone`: The microphone that will be opened and will start recording audio. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneOpen(SbMicrophone microphone) ``` -### SbMicrophoneRead ### +### SbMicrophoneRead Retrieves the recorded audio data from the microphone and writes that data to `out_audio_data`. @@ -255,7 +255,7 @@ audio data is thrown out. No audio data is read from a stopped microphone. smaller than `min_read_size` of `SbMicrophoneInfo`, the extra audio data that has already been read from the device is discarded. -#### Declaration #### +#### Declaration ``` 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 05dd810c1f94..82ff8500ab8d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/15/mutex.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: mutex.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `mutex.h` Defines a mutually exclusive lock that can be used to coordinate with other threads. -## Macros ## +## Macros -### SB_MUTEX_MAX_SIZE ### +### SB_MUTEX_MAX_SIZE Max size of the SbMutex type. -## Enums ## +## Enums -### SbMutexResult ### +### SbMutexResult Enumeration of possible results from acquiring a mutex. -#### Values #### +#### Values * `kSbMutexAcquired` @@ -30,22 +30,22 @@ Enumeration of possible results from acquiring a mutex. The mutex has already been destroyed. -## Typedefs ## +## Typedefs -### SbMutex ### +### SbMutex An opaque handle to a mutex type with reserved memory buffer of size SB_MUTEX_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbMutex SbMutex ``` -## Functions ## +## Functions -### SbMutexAcquire ### +### SbMutexAcquire Acquires `mutex`, blocking indefinitely. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition @@ -53,13 +53,13 @@ blocks forever. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquire(SbMutex *mutex) ``` -### SbMutexAcquireTry ### +### SbMutexAcquireTry Acquires `mutex`, without blocking. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition has undefined @@ -67,52 +67,52 @@ behavior. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquireTry(SbMutex *mutex) ``` -### SbMutexCreate ### +### SbMutexCreate Creates a new mutex. The return value indicates whether the function was able to create a new mutex. `out_mutex`: The handle to the newly created mutex. -#### Declaration #### +#### Declaration ``` bool SbMutexCreate(SbMutex *out_mutex) ``` -### SbMutexDestroy ### +### SbMutexDestroy Destroys a mutex. The return value indicates whether the destruction was successful. Destroying a locked mutex results in undefined behavior. `mutex`: The mutex to be invalidated. -#### Declaration #### +#### Declaration ``` bool SbMutexDestroy(SbMutex *mutex) ``` -### SbMutexIsSuccess ### +### SbMutexIsSuccess Indicates whether the given result is a success. A value of `true` indicates that the mutex was acquired. `result`: The result being checked. -#### Declaration #### +#### Declaration ``` static bool SbMutexIsSuccess(SbMutexResult result) ``` -### SbMutexRelease ### +### SbMutexRelease Releases `mutex` held by the current thread. The return value indicates whether the release was successful. Releases should always be successful if `mutex` is @@ -120,7 +120,7 @@ held by the current thread. `mutex`: The mutex to be released. -#### Declaration #### +#### Declaration ``` 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 2ad1959cd50e..d77302467f8b 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/once.md +++ b/cobalt/site/docs/reference/starboard/modules/15/once.md @@ -1,43 +1,43 @@ ---- -layout: doc -title: "Starboard Module Reference: once.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `once.h` Onces represent initializations that should only ever happen once per process, in a thread-safe way. -## Macros ## +## Macros -### SB_ONCE_MAX_SIZE ### +### SB_ONCE_MAX_SIZE Max size of the SbOnceControl type. -## Typedefs ## +## Typedefs -### SbOnceControl ### +### SbOnceControl An opaque handle to a once control type with reserved memory buffer of size SB_ONCE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbOnceControl SbOnceControl ``` -### SbOnceInitRoutine ### +### SbOnceInitRoutine Function pointer type for methods that can be called via the SbOnce() system. -#### Definition #### +#### Definition ``` typedef void(* SbOnceInitRoutine) (void) ``` -## Functions ## +## Functions -### SbOnce ### +### SbOnce Thread-safely runs `init_routine` only once. @@ -50,7 +50,7 @@ Thread-safely runs `init_routine` only once. * If `once_control` or `init_routine` is invalid, the function returns `false`. -#### Declaration #### +#### Declaration ``` 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 8039f6b69b41..e7e740e910eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/player.md +++ b/cobalt/site/docs/reference/starboard/modules/15/player.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: player.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `player.h` Defines an interface for controlling playback of media elementary streams. -## Macros ## +## Macros -### SB_PLAYER_INITIAL_TICKET ### +### SB_PLAYER_INITIAL_TICKET The value of the initial ticket held by the player before the first seek. The player will use this ticket value to make the first call to SbPlayerStatusFunc with kSbPlayerStateInitialized. -### SB_PLAYER_NO_DURATION ### +### SB_PLAYER_NO_DURATION The value to pass into SbPlayerCreate's `duration_pts` argument for cases where the duration is unknown, such as for live streams. -### kSbPlayerInvalid ### +### kSbPlayerInvalid Well-defined value for an invalid player. -### kSbPlayerWriteDurationLocal ### +### kSbPlayerWriteDurationLocal The audio write duration when all the audio connectors are local. -### kSbPlayerWriteDurationRemote ### +### kSbPlayerWriteDurationRemote The audio write duration when at least one of the audio connectors are remote. -## Enums ## +## Enums -### SbPlayerDecoderState ### +### SbPlayerDecoderState An indicator of whether the decoder can accept more samples. -#### Values #### +#### Values * `kSbPlayerDecoderStateNeedsData` The decoder is asking for one more sample. -### SbPlayerSampleSideDataType ### +### SbPlayerSampleSideDataType Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side data may come from multiple sources. -#### Values #### +#### Values * `kMatroskaBlockAdditional` @@ -56,11 +56,11 @@ data may come from multiple sources. . The first 8 bytes of the data contains the value of BlockAddID in big endian format, followed by the content of BlockAdditional. -### SbPlayerState ### +### SbPlayerState An indicator of the general playback state. -#### Values #### +#### Values * `kSbPlayerStateInitialized` @@ -84,31 +84,31 @@ An indicator of the general playback state. The player has been destroyed, and will send no more callbacks. -## Typedefs ## +## Typedefs -### SbPlayer ### +### SbPlayer An opaque handle to an implementation-private structure representing a player. -#### Definition #### +#### Definition ``` typedef struct SbPlayerPrivate* SbPlayer ``` -### SbPlayerDeallocateSampleFunc ### +### SbPlayerDeallocateSampleFunc Callback to free the given sample buffer data. When more than one buffer are sent in SbPlayerWriteSample(), the implementation only has to call this callback with `sample_buffer` points to the the first buffer. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) ``` -### SbPlayerDecoderStatusFunc ### +### SbPlayerDecoderStatusFunc Callback for decoder status updates, called in response to a call to SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called @@ -122,45 +122,45 @@ player will make at most one call to SbPlayerWriteSample() or SbPlayerWriteEndOfStream(). The player implementation should update the decoder status again after such call to notify its user to continue writing more frames. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) ``` -### SbPlayerErrorFunc ### +### SbPlayerErrorFunc Callback for player errors, that may set a `message`. `error`: indicates the error code. `message`: provides specific informative diagnostic message about the error condition encountered. It is ok for the message to be an empty string or NULL if no information is available. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) ``` -### SbPlayerStatusFunc ### +### SbPlayerStatusFunc Callback for player status updates. These callbacks will happen on a different thread than the calling thread, and it is not valid to call SbPlayer functions from within this callback. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) ``` -## Structs ## +## Structs -### SbPlayerCreationParam ### +### SbPlayerCreationParam The playback related parameters to pass into SbPlayerCreate() and SbPlayerGetPreferredOutputMode(). -#### Members #### +#### Members * `SbDrmSystem drm_system` @@ -186,11 +186,11 @@ SbPlayerGetPreferredOutputMode(). should be made available for the application to pull via calls to SbPlayerGetCurrentFrame(). -### SbPlayerInfo ### +### SbPlayerInfo Information about the current media playback state. -#### Members #### +#### Members * `SbTime current_media_timestamp` @@ -237,11 +237,11 @@ Information about the current media playback state. faster than normal speed. When it is less than one, the video is played in a slower than normal speed. Negative speeds are not supported. -### SbPlayerSampleInfo ### +### SbPlayerSampleInfo Information about the samples to be written into SbPlayerWriteSamples(). -#### Members #### +#### Members * `SbMediaType type` * `const void * buffer` @@ -274,12 +274,12 @@ Information about the samples to be written into SbPlayerWriteSamples(). The DRM system related info for the media sample. This value is required for encrypted samples. Otherwise, it must be `NULL`. -### SbPlayerSampleSideData ### +### SbPlayerSampleSideData Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data coming from multiple sources. -#### Members #### +#### Members * `SbPlayerSampleSideDataType type` * `const uint8_t * data` @@ -290,9 +290,9 @@ coming from multiple sources. The size of the data pointed by `data`, in bytes. -## Functions ## +## Functions -### SbPlayerDestroy ### +### SbPlayerDestroy Destroys `player`, freeing all associated resources. @@ -307,13 +307,13 @@ Destroys `player`, freeing all associated resources. SbPlayerDestroy has been called on that player. `player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` void SbPlayerDestroy(SbPlayer player) ``` -### SbPlayerGetAudioConfiguration ### +### SbPlayerGetAudioConfiguration Returns the audio configurations used by `player`. @@ -371,13 +371,13 @@ be greater than or equal to 0. `out_audio_configuration`: The information about the audio output, refer to `SbMediaAudioConfiguration` for more details. Must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbPlayerGetAudioConfiguration(SbPlayer player, int index, SbMediaAudioConfiguration *out_audio_configuration) ``` -### SbPlayerGetCurrentFrame ### +### SbPlayerGetCurrentFrame Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, it will return a SbDecodeTarget representing the current frame to be rasterized. @@ -389,13 +389,13 @@ kSbDecodeTargetInvalid is returned. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` -### SbPlayerGetMaximumNumberOfSamplesPerWrite ### +### 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 @@ -409,13 +409,13 @@ to retain from those structures. of sample for which the number is retrieved. See the `SbMediaType` enum in media.h. -#### Declaration #### +#### Declaration ``` int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) ``` -### SbPlayerGetPreferredOutputMode ### +### SbPlayerGetPreferredOutputMode Returns the preferred output mode of the implementation when a video described by `creation_param` is played. It is assumed that it is okay to call @@ -433,23 +433,23 @@ whether the video described by `creation_param` can be played on the platform, and the implementation should try its best effort to return a valid output mode. `creation_param` must not be NULL. -#### Declaration #### +#### Declaration ``` SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) ``` -### SbPlayerIsValid ### +### SbPlayerIsValid Returns whether the given player handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbPlayerIsValid(SbPlayer player) ``` -### SbPlayerSetBounds ### +### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do not take effect until the next graphics frame buffer swap. The default bounds @@ -470,13 +470,13 @@ smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. `y`: The y-coordinate of the upper-left corner of the player. `width`: The width of the player, in pixels. `height`: The height of the player, in pixels. -#### Declaration #### +#### Declaration ``` void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) ``` -### SbPlayerSetPlaybackRate ### +### SbPlayerSetPlaybackRate Set the playback rate of the `player`. `rate` is default to 1.0 which indicates the playback is at its original speed. A `rate` greater than one will make the @@ -491,13 +491,13 @@ to support. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) ``` -### SbPlayerSetVolume ### +### SbPlayerSetVolume Sets the player's volume. @@ -506,13 +506,13 @@ Sets the player's volume. `0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be muted, and a value of `1.0` means that it should be played at full volume. -#### Declaration #### +#### Declaration ``` void SbPlayerSetVolume(SbPlayer player, double volume) ``` -### SbPlayerWriteEndOfStream ### +### SbPlayerWriteEndOfStream Writes a marker to `player`'s input stream of `stream_type` indicating that there are no more samples for that media type for the remainder of this media @@ -522,13 +522,13 @@ contents, after a call to SbPlayerSeek. `player`: The player to which the marker is written. `stream_type`: The type of stream for which the marker is written. -#### Declaration #### +#### Declaration ``` void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ``` -### SbPlayerWriteSamples ### +### SbPlayerWriteSamples `sample_type`: The type of sample being written. See the `SbMediaType` enum in media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with @@ -540,7 +540,7 @@ be copied if its content will be used after SbPlayerWriteSamples() returns. `sample_infos`. It has to be at least one, and less than the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). -#### Declaration #### +#### Declaration ``` void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) diff --git a/cobalt/site/docs/reference/starboard/modules/15/socket.md b/cobalt/site/docs/reference/starboard/modules/15/socket.md index 9e0f81b98334..744c04e3847d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/15/socket.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket.h` Defines Starboard socket I/O functions. Starboard supports IPv4 and IPv6, TCP and UDP, server and client sockets. Some platforms may not support IPv6, some @@ -18,19 +18,19 @@ the connection, thus requiring use of either an SbSocketWaiter or spin-polling. TODO: For platforms that do not support sockets at all, they must support at least a high-level HTTP client API (to be defined later). -## Macros ## +## Macros -### kSbSocketInvalid ### +### kSbSocketInvalid Well-defined value for an invalid socket handle. -## Enums ## +## Enums -### SbSocketAddressType ### +### SbSocketAddressType All possible address types. -#### Values #### +#### Values * `kSbSocketAddressTypeIpv4` @@ -39,13 +39,13 @@ All possible address types. An IPv6 address, which uses 16 entries of the address buffer. -### SbSocketError ### +### SbSocketError Enumeration of all Starboard socket operation results. Despite the enum name, note that the value actually describes the outcome of an operation, which is not always an error. -#### Values #### +#### Values * `kSbSocketOk` @@ -63,11 +63,11 @@ always an error. The operation failed for some other reason not specified above. -### SbSocketProtocol ### +### SbSocketProtocol All possible IP socket types. -#### Values #### +#### Values * `kSbSocketProtocolTcp` @@ -77,11 +77,11 @@ All possible IP socket types. The UDP/IP protocol, an unreliable, connectionless, discrete packet (datagram) protocol. -### SbSocketResolveFilter ### +### SbSocketResolveFilter Bits that can be set when calling SbSocketResolve to filter the results. -#### Values #### +#### Values * `kSbSocketResolveFilterNone` @@ -93,25 +93,25 @@ Bits that can be set when calling SbSocketResolve to filter the results. Include Ipv6 addresses. -## Typedefs ## +## Typedefs -### SbSocket ### +### SbSocket A handle to a socket. -#### Definition #### +#### Definition ``` typedef SbSocketPrivate* SbSocket ``` -## Structs ## +## Structs -### SbSocketAddress ### +### SbSocketAddress A representation of any possible supported address type. -#### Members #### +#### Members * `uint8_t address` @@ -126,11 +126,11 @@ A representation of any possible supported address type. The port component of this socket address. If not specified, it will be zero, which is officially undefined. -### SbSocketResolution ### +### SbSocketResolution The result of a host name resolution. -#### Members #### +#### Members * `SbSocketAddress* addresses` @@ -139,9 +139,9 @@ The result of a host name resolution. The length of the `addresses` array. -## Functions ## +## Functions -### SbSocketAccept ### +### SbSocketAccept Accepts a pending connection on `socket` and returns a new SbSocket representing that connection. This function sets the error on `socket` and returns @@ -149,13 +149,13 @@ that connection. This function sets the error on `socket` and returns `socket`: The SbSocket that is accepting a pending connection. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketAccept(SbSocket socket) ``` -### SbSocketBind ### +### SbSocketBind Binds `socket` to a specific local interface and port specified by `local_address`. This function sets and returns the socket error if it is unable @@ -170,24 +170,24 @@ local address to which the socket is to be bound. This value must not be `NULL`. * Setting the IP address to `0.0.0.0` means that the socket should be bound to all interfaces. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address) ``` -### SbSocketClearLastError ### +### SbSocketClearLastError Clears the last error set on `socket`. The return value indicates whether the socket error was cleared. -#### Declaration #### +#### Declaration ``` bool SbSocketClearLastError(SbSocket socket) ``` -### SbSocketConnect ### +### SbSocketConnect Opens a connection of `socket`'s type to the host and port specified by `address`. This function sets and returns the socket error if it is unable to @@ -197,13 +197,13 @@ successfully.) `socket`: The type of connection that should be opened. `address`: The host and port to which the socket should connect. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketCreate ### +### SbSocketCreate Creates a new non-blocking socket for protocol `protocol` using address family `address_type`. @@ -216,13 +216,13 @@ Creates a new non-blocking socket for protocol `protocol` using address family `address_type`: The type of IP address to use for the socket. `protocol`: The protocol to use for the socket. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol) ``` -### SbSocketDestroy ### +### SbSocketDestroy Destroys the `socket` by flushing it, closing any connection that may be active on it, and reclaiming any resources associated with it, including any @@ -234,25 +234,25 @@ more. `socket`: The SbSocket to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketDestroy(SbSocket socket) ``` -### SbSocketFreeResolution ### +### SbSocketFreeResolution Frees a resolution allocated by SbSocketResolve. `resolution`: The resolution to be freed. -#### Declaration #### +#### Declaration ``` void SbSocketFreeResolution(SbSocketResolution *resolution) ``` -### SbSocketGetInterfaceAddress ### +### SbSocketGetInterfaceAddress Gets the source address and the netmask that would be used to connect to the destination. The netmask parameter is optional, and only populated if a non-NULL @@ -288,26 +288,26 @@ this output variable. `out_netmask`: This parameter is optional. If a non-NULL value is passed in, this function places the netmask associated with the source address in this output variable. -#### Declaration #### +#### Declaration ``` bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask) ``` -### SbSocketGetLastError ### +### SbSocketGetLastError Returns the last error set on `socket`. If `socket` is not valid, this function returns `kSbSocketErrorFailed`. `socket`: The SbSocket that the last error is returned for. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketGetLastError(SbSocket socket) ``` -### SbSocketGetLocalAddress ### +### SbSocketGetLocalAddress Gets the address that this socket is bound to locally, if the socket is connected. The return value indicates whether the address was retrieved @@ -316,59 +316,59 @@ successfully. `socket`: The SbSocket for which the local address is retrieved. `out_address`: The SbSocket's local address. -#### Declaration #### +#### Declaration ``` bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address) ``` -### SbSocketIsConnected ### +### SbSocketIsConnected Indicates whether `socket` is connected to anything. Invalid sockets are not connected. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnected(SbSocket socket) ``` -### SbSocketIsConnectedAndIdle ### +### SbSocketIsConnectedAndIdle Returns whether `socket` is connected to anything, and, if so, whether it is receiving any data. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnectedAndIdle(SbSocket socket) ``` -### SbSocketIsIpv6Supported ### +### SbSocketIsIpv6Supported Returns whether IPV6 is supported on the current platform. -#### Declaration #### +#### Declaration ``` bool SbSocketIsIpv6Supported() ``` -### SbSocketIsValid ### +### SbSocketIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketIsValid(SbSocket socket) ``` -### SbSocketJoinMulticastGroup ### +### SbSocketJoinMulticastGroup Joins `socket` to an IP multicast group identified by `address`. The equivalent of IP_ADD_MEMBERSHIP. The return value indicates whether the socket was joined @@ -377,13 +377,13 @@ to the group successfully. `socket`: The SbSocket to be joined to the IP multicast group. `address`: The location of the IP multicast group. -#### Declaration #### +#### Declaration ``` bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketListen ### +### SbSocketListen Causes `socket` to listen on the local address that `socket` was previously bound to by SbSocketBind. This function sets and returns the socket error if it @@ -392,13 +392,13 @@ connection successfully.) `socket`: The SbSocket on which the function operates. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketListen(SbSocket socket) ``` -### SbSocketReceiveFrom ### +### SbSocketReceiveFrom Reads up to `data_size` bytes from `socket` into `out_data` and places the source address of the packet in `out_source` if out_source is not NULL. Returns @@ -420,13 +420,13 @@ the address is unnecessary, but allowed. the socket. Must not be NULL. `data_size`: The number of bytes to read. `out_source`: The source address of the packet. -#### Declaration #### +#### Declaration ``` int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source) ``` -### SbSocketResolve ### +### SbSocketResolve Synchronously resolves `hostname` into the returned SbSocketResolution , which must be freed with SbSocketFreeResolution. The function returns `NULL` if it is @@ -438,13 +438,13 @@ not specify an IP address family filter, all address families are included. However, if one IP address family filter is specified, only that address family is included. The function ignores unrecognized filter bits. -#### Declaration #### +#### Declaration ``` SbSocketResolution* SbSocketResolve(const char *hostname, int filters) ``` -### SbSocketSendTo ### +### SbSocketSendTo Writes up to `data_size` bytes of `data` to `destination` via `socket`. Returns the number of bytes written, or a negative number if there is an error, in which @@ -466,13 +466,13 @@ to multiple sources from a single UDP server socket. TCP has two endpoints connected persistently, so setting `destination` when sending to a TCP socket will cause an error. -#### Declaration #### +#### Declaration ``` int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination) ``` -### SbSocketSetBroadcast ### +### SbSocketSetBroadcast Sets the `SO_BROADCAST`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -483,13 +483,13 @@ the broadcast address. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetBroadcast(SbSocket socket, bool value) ``` -### SbSocketSetReceiveBufferSize ### +### SbSocketSetReceiveBufferSize Sets the `SO_RCVBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -497,13 +497,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetReuseAddress ### +### SbSocketSetReuseAddress Sets the `SO_REUSEADDR`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -514,13 +514,13 @@ to it. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReuseAddress(SbSocket socket, bool value) ``` -### SbSocketSetSendBufferSize ### +### SbSocketSetSendBufferSize Sets the `SO_SNDBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -528,13 +528,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetTcpKeepAlive ### +### SbSocketSetTcpKeepAlive Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -545,13 +545,13 @@ 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`. -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) ``` -### SbSocketSetTcpNoDelay ### +### SbSocketSetTcpNoDelay Sets the `TCP_NODELAY`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -564,13 +564,13 @@ behavior. `socket`: The SbSocket for which the option is set. `value`: Indicates whether the Nagle algorithm should be disabled (`value`=`true`). -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpNoDelay(SbSocket socket, bool value) ``` -### SbSocketSetTcpWindowScaling ### +### SbSocketSetTcpWindowScaling Sets the `SO_WINSCALE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -578,7 +578,7 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: The value for the option. -#### Declaration #### +#### Declaration ``` 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 855dcf8b9c72..f1c6bd8b9f2f 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/15/socket_waiter.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket_waiter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket_waiter.h` Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to: @@ -26,19 +26,19 @@ thread, it needs to call SbSocketWaiterWakeUp() on the SbSocketWaiter after queuing the work item, or the SbSocketWaiter is not otherwise guaranteed to wake up. -## Macros ## +## Macros -### kSbSocketWaiterInvalid ### +### kSbSocketWaiterInvalid Well-defined value for an invalid socket watcher handle. -## Enums ## +## Enums -### SbSocketWaiterInterest ### +### SbSocketWaiterInterest All the interests that a socket may register for on a waiter. -#### Values #### +#### Values * `kSbSocketWaiterInterestNone` @@ -50,11 +50,11 @@ All the interests that a socket may register for on a waiter. An interest in or readiness to write to a socket without blocking. -### SbSocketWaiterResult ### +### SbSocketWaiterResult Possible reasons why a call to SbSocketWaiterWaitTimed returned. -#### Values #### +#### Values * `kSbSocketWaiterResultInvalid` @@ -66,31 +66,31 @@ Possible reasons why a call to SbSocketWaiterWaitTimed returned. The wait stopped because a call to SbSocketWaiterWakeUp was consumed. -## Typedefs ## +## Typedefs -### SbSocketWaiter ### +### SbSocketWaiter A handle to a socket waiter. -#### Definition #### +#### Definition ``` typedef SbSocketWaiterPrivate* SbSocketWaiter ``` -### SbSocketWaiterCallback ### +### SbSocketWaiterCallback Function pointer for socket waiter callbacks. -#### Definition #### +#### Definition ``` typedef void(* SbSocketWaiterCallback) (SbSocketWaiter waiter, SbSocket socket, void *context, int ready_interests) ``` -## Functions ## +## Functions -### SbSocketWaiterAdd ### +### SbSocketWaiterAdd Adds a new socket to be waited on by the `waiter` with a bitfield of `interests`. This function should only be called on the thread that waits on @@ -120,25 +120,25 @@ socket: `callback`, even if not all registered `interests` became ready, which allows for adding it again in the `callback`. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterAdd(SbSocketWaiter waiter, SbSocket socket, void *context, SbSocketWaiterCallback callback, int interests, bool persistent) ``` -### SbSocketWaiterCreate ### +### SbSocketWaiterCreate The results of two threads waiting on the same waiter is undefined and will not work. Except for the SbSocketWaiterWakeUp() function, SbSocketWaiters are not thread-safe and don't expect to be modified concurrently. -#### Declaration #### +#### Declaration ``` SbSocketWaiter SbSocketWaiterCreate() ``` -### SbSocketWaiterDestroy ### +### SbSocketWaiterDestroy Destroys `waiter` and removes all sockets still registered by way of SbSocketWaiterAdd. This function may be called on any thread as long as there is @@ -146,23 +146,23 @@ no risk of concurrent access to the waiter. `waiter`: The SbSocketWaiter to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterDestroy(SbSocketWaiter waiter) ``` -### SbSocketWaiterIsValid ### +### SbSocketWaiterIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketWaiterIsValid(SbSocketWaiter watcher) ``` -### SbSocketWaiterRemove ### +### SbSocketWaiterRemove Removes a socket, previously added with SbSocketWaiterAdd(), from a waiter. This function should only be called on the thread that waits on this waiter. @@ -174,26 +174,26 @@ returns `true`. `waiter`: The waiter from which the socket is removed. `socket`: The socket to remove from the waiter. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket) ``` -### SbSocketWaiterWait ### +### SbSocketWaiterWait Waits on all registered sockets, calling the registered callbacks if and when the corresponding sockets become ready for an interested operation. This version exits only after SbSocketWaiterWakeUp() is called. This function should only be called on the thread that waits on this waiter. -#### Declaration #### +#### Declaration ``` void SbSocketWaiterWait(SbSocketWaiter waiter) ``` -### SbSocketWaiterWaitTimed ### +### SbSocketWaiterWaitTimed Behaves similarly to SbSocketWaiterWait(), but this function also causes `waiter` to exit on its own after at least `duration` has passed if @@ -207,13 +207,13 @@ 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 #### +#### Declaration ``` SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) ``` -### SbSocketWaiterWakeUp ### +### SbSocketWaiterWakeUp Wakes up `waiter` once. This is the only thread-safe waiter function. It can can be called from a SbSocketWaiterCallback to wake up its own waiter, and it can @@ -230,7 +230,7 @@ next 7 times they are called. `waiter`: The socket waiter to be woken up. -#### Declaration #### +#### Declaration ``` 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 16223184e784..0bd6e65b6379 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/15/speech_synthesis.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: speech_synthesis.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `speech_synthesis.h` A basic text-to-speech API intended to be used for audio accessibility. @@ -11,29 +11,29 @@ non-visual navigation of the application. Note that these functions do not have to be thread-safe. They must only be called from a single application thread. -## Functions ## +## Functions -### SbSpeechSynthesisCancel ### +### SbSpeechSynthesisCancel Cancels all speaking and queued speech synthesis audio. Must return immediately. -#### Declaration #### +#### Declaration ``` void SbSpeechSynthesisCancel() ``` -### SbSpeechSynthesisIsSupported ### +### SbSpeechSynthesisIsSupported Returns whether the platform supports speech synthesis -#### Declaration #### +#### Declaration ``` bool SbSpeechSynthesisIsSupported() ``` -### SbSpeechSynthesisSpeak ### +### SbSpeechSynthesisSpeak Enqueues `text`, a UTF-8 string, to be spoken. Returns immediately. @@ -44,7 +44,7 @@ If audio from previous SbSpeechSynthesisSpeak() invocations is still processing, the current speaking should continue and this new text should be queued to play when the previous utterances are complete. -#### Declaration #### +#### Declaration ``` 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 db7e9509bd2b..5c2b9624723d 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/15/storage.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: storage.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `storage.h` Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and retrieval API that is intended for robust long-term, per-user storage. Some @@ -15,27 +15,27 @@ record for a user will result in undefined behavior. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbStorageInvalidRecord ### +### kSbStorageInvalidRecord Well-defined value for an invalid storage record handle. -## Typedefs ## +## Typedefs -### SbStorageRecord ### +### SbStorageRecord A handle to an open storage record. -#### Definition #### +#### Definition ``` typedef SbStorageRecordPrivate* SbStorageRecord ``` -## Functions ## +## Functions -### SbStorageCloseRecord ### +### SbStorageCloseRecord Closes `record`, synchronously ensuring that all written data is flushed. This function performs blocking I/O on the calling thread. @@ -47,13 +47,13 @@ deleted (or, even better, untouched). `record`: The storage record to close. `record` is invalid after this point, and subsequent calls referring to `record` will fail. -#### Declaration #### +#### Declaration ``` bool SbStorageCloseRecord(SbStorageRecord record) ``` -### SbStorageDeleteRecord ### +### SbStorageDeleteRecord Deletes the `SbStorageRecord` for `user` named `name`. The return value indicates whether the record existed and was successfully deleted. If the record @@ -68,36 +68,36 @@ function performs blocking I/O on the calling thread. `user`: The user for whom the record will be deleted. `name`: The filesystem- safe name of the record to open. -#### Declaration #### +#### Declaration ``` bool SbStorageDeleteRecord(SbUser user, const char *name) ``` -### SbStorageGetRecordSize ### +### SbStorageGetRecordSize Returns the size of `record`, or `-1` if there is an error. This function performs blocking I/O on the calling thread. `record`: The record to retrieve the size of. -#### Declaration #### +#### Declaration ``` int64_t SbStorageGetRecordSize(SbStorageRecord record) ``` -### SbStorageIsValidRecord ### +### SbStorageIsValidRecord Returns whether the given storage record handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbStorageIsValidRecord(SbStorageRecord record) ``` -### SbStorageOpenRecord ### +### SbStorageOpenRecord Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on the calling thread until the open is completed. If `user` is not a valid @@ -111,13 +111,13 @@ would have been saved with the previous version of SbStorageOpenRecord. `user`: The user for which the storage record will be opened. `name`: The filesystem-safe name of the record to open. -#### Declaration #### +#### Declaration ``` SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) ``` -### SbStorageReadRecord ### +### SbStorageReadRecord Reads up to `data_size` bytes from `record`, starting at the beginning of the record. The function returns the actual number of bytes read, which must be <= @@ -128,13 +128,13 @@ the calling thread until the entire record is read or an error is encountered. `record`: The record to be read. `out_data`: The data read from the record. `data_size`: The amount of data, in bytes, to read. -#### Declaration #### +#### Declaration ``` int64_t SbStorageReadRecord(SbStorageRecord record, char *out_data, int64_t data_size) ``` -### SbStorageWriteRecord ### +### SbStorageWriteRecord Replaces the data in `record` with `data_size` bytes from `data`. This function always deletes any previous data in that record. The return value indicates @@ -151,7 +151,7 @@ after a short time, even if there is an unexpected process termination before `record`: The record to be written to. `data`: The data to write to the record. `data_size`: The amount of `data`, in bytes, to write to the record. -#### Declaration #### +#### Declaration ``` 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 685f5e8f5e5b..3fed809df461 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/string.md +++ b/cobalt/site/docs/reference/starboard/modules/15/string.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: string.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `string.h` Defines functions for interacting with c-style strings. -## Functions ## +## Functions -### SbStringCompareNoCase ### +### SbStringCompareNoCase Compares two strings, ignoring differences in case. The return value is: @@ -21,13 +21,13 @@ This function is meant to be a drop-in replacement for `strcasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCase(const char *string1, const char *string2) ``` -### SbStringCompareNoCaseN ### +### SbStringCompareNoCaseN Compares the first `count` characters of two strings, ignoring differences in case. The return value is: @@ -43,13 +43,13 @@ This function is meant to be a drop-in replacement for `strncasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. `count`: The number of characters to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) ``` -### SbStringDuplicate ### +### SbStringDuplicate Copies `source` into a buffer that is allocated by this function and that can be freed with SbMemoryDeallocate. This function is meant to be a drop-in @@ -57,13 +57,13 @@ replacement for `strdup`. `source`: The string to be copied. -#### Declaration #### +#### Declaration ``` char* SbStringDuplicate(const char *source) ``` -### SbStringFormat ### +### SbStringFormat Produces a string formatted with `format` and `arguments`, placing as much of the result that will fit into `out_buffer`. The return value specifies the @@ -76,13 +76,13 @@ This function is meant to be a drop-in replacement for `vsnprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatF ### +### SbStringFormatF An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This function is meant to be a drop-in replacement for `snprintf`. @@ -91,13 +91,13 @@ function is meant to be a drop-in replacement for `snprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatUnsafeF ### +### SbStringFormatUnsafeF An inline wrapper of SbStringFormat that is meant to be a drop-in replacement for the unsafe but commonly used `sprintf`. @@ -106,13 +106,13 @@ for the unsafe but commonly used `sprintf`. string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 ``` -### SbStringFormatWide ### +### SbStringFormatWide This function is identical to SbStringFormat, but is for wide characters. It is meant to be a drop-in replacement for `vswprintf`. @@ -121,13 +121,13 @@ meant to be a drop-in replacement for `vswprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF ### +### SbStringFormatWideF An inline wrapper of SbStringFormatWide that converts from ellipsis to `va_args`. @@ -136,13 +136,13 @@ An inline wrapper of SbStringFormatWide that converts from ellipsis to The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) ``` -### SbStringScan ### +### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The return value specifies the number of successfully matched items, which may be @@ -154,20 +154,20 @@ This function is meant to be a drop-in replacement for `vsscanf`. for in `buffer`. `arguments`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` int SbStringScan(const char *buffer, const char *pattern, va_list arguments) ``` -### SbStringScanF ### +### SbStringScanF An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` 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 32fd3032ee05..86437a3d0804 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/system.md +++ b/cobalt/site/docs/reference/starboard/modules/15/system.md @@ -1,21 +1,21 @@ ---- -layout: doc -title: "Starboard Module Reference: system.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `system.h` Defines a broad set of APIs that allow the client application to query build and runtime properties of the enclosing system. -## Enums ## +## Enums -### SbSystemCapabilityId ### +### SbSystemCapabilityId Runtime capabilities are boolean properties of a platform that can't be determined at compile-time. They may vary from device to device, but they will not change over the course of a single execution. They often specify particular behavior of other APIs within the bounds of their operating range. -#### Values #### +#### Values * `kSbSystemCapabilityReversedEnterAndBack` @@ -26,11 +26,11 @@ behavior of other APIs within the bounds of their operating range. only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call. -### SbSystemPathId ### +### SbSystemPathId Enumeration of special paths that the platform can define. -#### Values #### +#### Values * `kSbSystemPathContentDirectory` @@ -66,22 +66,22 @@ Enumeration of special paths that the platform can define. for storing the updates. See starboard/doc/evergreen/cobalt_evergreen_overview.md -### SbSystemPlatformErrorResponse ### +### SbSystemPlatformErrorResponse Possible responses for `SbSystemPlatformErrorCallback`. -#### Values #### +#### Values * `kSbSystemPlatformErrorResponsePositive` * `kSbSystemPlatformErrorResponseNegative` * `kSbSystemPlatformErrorResponseCancel` -### SbSystemPlatformErrorType ### +### SbSystemPlatformErrorType Enumeration of possible values for the `type` parameter passed to the `SbSystemRaisePlatformError` function. -#### Values #### +#### Values * `kSbSystemPlatformErrorTypeConnectionError` @@ -90,12 +90,12 @@ Enumeration of possible values for the `type` parameter passed to the `kSbSystemPlatformErrorResponsePositive` then the request should be retried, otherwise the app should be stopped. -### SbSystemPropertyId ### +### SbSystemPropertyId System properties that can be queried for. Many of these are used in User-Agent string generation. -#### Values #### +#### Values * `kSbSystemPropertyCertificationScope` @@ -156,9 +156,9 @@ string generation. Type of the device, e.g. such as "TV", "STB", "OTT" Please see Youtube Technical requirements for a full list of allowed values -## Typedefs ## +## Typedefs -### SbSystemComparator ### +### SbSystemComparator Pointer to a function to compare two items. The return value uses standard `*cmp` semantics: @@ -171,23 +171,23 @@ Pointer to a function to compare two items. The return value uses standard `a`: The first value to compare. `b`: The second value to compare. -#### Definition #### +#### Definition ``` typedef int(* SbSystemComparator) (const void *a, const void *b) ``` -### SbSystemError ### +### SbSystemError A type that can represent a system error code across all Starboard platforms. -#### Definition #### +#### Definition ``` typedef int SbSystemError ``` -### SbSystemPlatformErrorCallback ### +### SbSystemPlatformErrorCallback Type of callback function that may be called in response to an error notification from `SbSystemRaisePlatformError`. `response` is a code to indicate @@ -195,36 +195,36 @@ the user's response, e.g. if the platform raised a dialog to notify the user of the error. `user_data` is the opaque pointer that was passed to the call to `SbSystemRaisePlatformError`. -#### Definition #### +#### Definition ``` typedef void(* SbSystemPlatformErrorCallback) (SbSystemPlatformErrorResponse response, void *user_data) ``` -## Functions ## +## Functions -### SbSystemBreakIntoDebugger ### +### SbSystemBreakIntoDebugger Breaks the current program into the debugger, if a debugger is attached. If a debugger is not attached, this function aborts the program. -#### Declaration #### +#### Declaration ``` SB_NORETURN void SbSystemBreakIntoDebugger() ``` -### SbSystemClearLastError ### +### SbSystemClearLastError Clears the last error set by a Starboard call in the current thread. -#### Declaration #### +#### Declaration ``` void SbSystemClearLastError() ``` -### SbSystemGetErrorString ### +### SbSystemGetErrorString Generates a human-readable string for an error. The return value specifies the total desired length of the string. @@ -233,13 +233,13 @@ total desired length of the string. The generated string. This value may be null, and it is always terminated with a null byte. `string_length`: The maximum length of the error string. -#### Declaration #### +#### Declaration ``` int SbSystemGetErrorString(SbSystemError error, char *out_string, int string_length) ``` -### SbSystemGetExtension ### +### SbSystemGetExtension Returns pointer to a constant global struct implementing the extension named `name`, if it is implemented. Otherwise return NULL. The `name` string must not @@ -261,25 +261,25 @@ application may only get the extension once, meaning updated values would be ignored. As the version of extensions are incremented, fields may be added to the end of the struct, but never removed (only deprecated). -#### Declaration #### +#### Declaration ``` const void* SbSystemGetExtension(const char *name) ``` -### SbSystemGetLastError ### +### SbSystemGetLastError Gets the last platform-specific error code produced by any Starboard call in the current thread for diagnostic purposes. Semantic reactions to Starboard function call results should be modeled explicitly. -#### Declaration #### +#### Declaration ``` SbSystemError SbSystemGetLastError() ``` -### SbSystemGetLocaleId ### +### SbSystemGetLocaleId Gets the system's current POSIX-style Locale ID. The locale represents the location, language, and cultural conventions that the system wants to use, which @@ -296,25 +296,25 @@ RFC 5646 describes BCP 47 language codes: [https://tools.ietf.org/html/bcp47](ht For more information than you probably want about POSIX locales, see: [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html) -#### Declaration #### +#### Declaration ``` const char* SbSystemGetLocaleId() ``` -### SbSystemGetNumberOfProcessors ### +### SbSystemGetNumberOfProcessors Returns the number of processor cores available to this application. If the process is sandboxed to a subset of the physical cores, the function returns that sandboxed limit. -#### Declaration #### +#### Declaration ``` int SbSystemGetNumberOfProcessors() ``` -### SbSystemGetProperty ### +### SbSystemGetProperty Retrieves the platform-defined system property specified by `property_id` and places its value as a zero-terminated string into the user-allocated `out_value` @@ -335,13 +335,13 @@ returns `false` under any of the following conditions and, in any such case, defined system property specified by `property_id`. `value_length`: The length of the system property. -#### Declaration #### +#### Declaration ``` bool SbSystemGetProperty(SbSystemPropertyId property_id, char *out_value, int value_length) ``` -### SbSystemGetRandomData ### +### SbSystemGetRandomData A cryptographically secure random number generator that produces an arbitrary, non-negative number of `buffer_size` random, non-negative bytes. The generated @@ -350,24 +350,24 @@ number is placed in `out_buffer`. This function does not require manual seeding. `out_buffer`: A pointer for the generated random number. This value must not be null. `buffer_size`: The size of the random number, in bytes. -#### Declaration #### +#### Declaration ``` void SbSystemGetRandomData(void *out_buffer, int buffer_size) ``` -### SbSystemGetRandomUInt64 ### +### SbSystemGetRandomUInt64 A cryptographically secure random number generator that gets 64 random bits and returns them as an `uint64_t`. This function does not require manual seeding. -#### Declaration #### +#### Declaration ``` uint64_t SbSystemGetRandomUInt64() ``` -### SbSystemGetStack ### +### SbSystemGetStack Places up to `stack_size` instruction pointer addresses of the current execution stack into `out_stack`. The return value specifies the number of entries added. @@ -384,62 +384,62 @@ what it means to be async-signal-safe on POSIX: [http://pubs.opengroup.org/onlin `stack_size`: The maximum number of instruction pointer addresses to be placed into `out_stack` from the current execution stack. -#### Declaration #### +#### Declaration ``` int SbSystemGetStack(void **out_stack, int stack_size) ``` -### SbSystemGetTotalCPUMemory ### +### SbSystemGetTotalCPUMemory Returns the total CPU memory (in bytes) potentially available to this application. If the process is sandboxed to a maximum allowable limit, the function returns the lesser of the physical and sandbox limits. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalCPUMemory() ``` -### SbSystemGetTotalGPUMemory ### +### SbSystemGetTotalGPUMemory Returns the total GPU memory (in bytes) available for use by this application. This function may only be called the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalGPUMemory() ``` -### SbSystemGetUsedCPUMemory ### +### SbSystemGetUsedCPUMemory Returns the total physical CPU memory (in bytes) used by this application. This value should always be less than (or, in particularly exciting situations, equal to) SbSystemGetTotalCPUMemory(). -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedCPUMemory() ``` -### SbSystemGetUsedGPUMemory ### +### SbSystemGetUsedGPUMemory Returns the current amount of GPU memory (in bytes) that is currently being used by this application. This function may only be called if the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedGPUMemory() ``` -### SbSystemHasCapability ### +### SbSystemHasCapability Returns whether the platform has the runtime capability specified by `capability_id`. Returns false for any unknown capabilities. This implementation @@ -447,48 +447,48 @@ must be thread-safe. `capability_id`: The runtime capability to check. -#### Declaration #### +#### Declaration ``` bool SbSystemHasCapability(SbSystemCapabilityId capability_id) ``` -### SbSystemHideSplashScreen ### +### SbSystemHideSplashScreen Hides the system splash screen on systems that support a splash screen that is displayed while the application is loading. This function may be called from any thread and must be idempotent. -#### Declaration #### +#### Declaration ``` void SbSystemHideSplashScreen() ``` -### SbSystemIsDebuggerAttached ### +### SbSystemIsDebuggerAttached Attempts to determine whether the current program is running inside or attached to a debugger. The function returns `false` if neither of those cases is true. -#### Declaration #### +#### Declaration ``` bool SbSystemIsDebuggerAttached() ``` -### SbSystemNetworkIsDisconnected ### +### SbSystemNetworkIsDisconnected Returns if the device is disconnected from network. "Disconnected" is chosen over connected because disconnection can be determined with more certainty than connection usually. -#### Declaration #### +#### Declaration ``` bool SbSystemNetworkIsDisconnected() ``` -### SbSystemRaisePlatformError ### +### SbSystemRaisePlatformError Cobalt calls this function to notify the platform that an error has occurred in the application that the platform may need to handle. The platform is expected @@ -510,13 +510,13 @@ caller know that the user has reacted to the error. `user_data`: An opaque pointer that the platform should pass as an argument to the callback function, if it is called. -#### Declaration #### +#### Declaration ``` bool SbSystemRaisePlatformError(SbSystemPlatformErrorType type, SbSystemPlatformErrorCallback callback, void *user_data) ``` -### SbSystemRequestBlur ### +### SbSystemRequestBlur Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to "unfocused application" in a @@ -526,13 +526,13 @@ This function eventually causes a `kSbEventTypeBlur` event to be dispatched to the application. Before the `kSbEventTypeBlur` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestBlur() ``` -### SbSystemRequestConceal ### +### SbSystemRequestConceal Requests that the application move into the Concealed state at the next convenient point. This should roughly correspond to "minimization" in a @@ -547,13 +547,13 @@ In the Concealed state, the application will be invisible, but probably still be running background tasks. The expectation is that an external system event will bring the application out of the Concealed state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestConceal() ``` -### SbSystemRequestFocus ### +### SbSystemRequestFocus Requests that the application move into the Started state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -564,13 +564,13 @@ This function eventually causes a `kSbEventTypeFocus` event to be dispatched to the application. Before `kSbEventTypeFocus` is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFocus() ``` -### SbSystemRequestFreeze ### +### SbSystemRequestFreeze Requests that the application move into the Frozen state at the next convenient point. @@ -583,13 +583,13 @@ In the Frozen state, the application will be resident, but probably not running. The expectation is that an external system event will bring the application out of the Frozen state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFreeze() ``` -### SbSystemRequestReveal ### +### SbSystemRequestReveal Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -600,13 +600,13 @@ This function eventually causes a `kSbEventTypeReveal` event to be dispatched to the application. Before the `kSbEventTypeReveal` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestReveal() ``` -### SbSystemRequestStop ### +### SbSystemRequestStop Requests that the application be terminated gracefully at the next convenient point. In the meantime, some work may continue to be done, and unrelated system @@ -617,13 +617,13 @@ it returns `error_level`, if that has any meaning on the current platform. `error_level`: An integer that serves as the return value for the process that is eventually terminated as a result of a call to this function. -#### Declaration #### +#### Declaration ``` void SbSystemRequestStop(int error_level) ``` -### SbSystemSignWithCertificationSecretKey ### +### SbSystemSignWithCertificationSecretKey Computes a HMAC-SHA256 digest of `message` into `digest` using the application's certification secret. The `message` and the `digest` pointers must not be NULL. @@ -633,13 +633,13 @@ greater), since 32-bytes will be written into it. Returns false in the case of an error, or if it is not implemented. In this case the contents of `digest` will be undefined. -#### Declaration #### +#### Declaration ``` bool SbSystemSignWithCertificationSecretKey(const uint8_t *message, size_t message_size_in_bytes, uint8_t *digest, size_t digest_size_in_bytes) ``` -### SbSystemSupportsResume ### +### SbSystemSupportsResume Returns false if the platform doesn't need resume after suspend support. In such case Cobalt will free up the resource it retains for resume after suspend. Note @@ -647,13 +647,13 @@ that if this function returns false, the Starboard implementation cannot send kSbEventTypeResume to the event handler. The return value of this function cannot change over the life time of the application. -#### Declaration #### +#### Declaration ``` bool SbSystemSupportsResume() ``` -### SbSystemSymbolize ### +### SbSystemSymbolize Looks up `address` as an instruction pointer and places up to (`buffer_size - 1`) characters of the symbol associated with it in `out_buffer`, which must not @@ -665,7 +665,7 @@ The return value indicates whether the function found a reasonable match for This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals. -#### Declaration #### +#### Declaration ``` 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 1191e9a56c91..56c7898a12b4 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/15/thread.md @@ -1,35 +1,35 @@ ---- -layout: doc -title: "Starboard Module Reference: thread.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `thread.h` Defines functionality related to thread creation and cleanup. -## Macros ## +## Macros -### kSbThreadContextInvalid ### +### kSbThreadContextInvalid Well-defined value for an invalid thread context. -### kSbThreadInvalidId ### +### kSbThreadInvalidId Well-defined constant value to mean "no thread ID." -### kSbThreadLocalKeyInvalid ### +### kSbThreadLocalKeyInvalid Well-defined constant value to mean "no thread local key." -### kSbThreadNoAffinity ### +### kSbThreadNoAffinity Well-defined constant value to mean "no affinity." -### kSbThreadSamplerInvalid ### +### kSbThreadSamplerInvalid Well-defined value for an invalid thread sampler. -## Enums ## +## Enums -### SbThreadPriority ### +### SbThreadPriority A spectrum of thread priorities. Platforms map them appropriately to their own priority system. Note that scheduling is platform-specific, and what these @@ -39,7 +39,7 @@ In particular, several of these priority values can map to the same priority on a given platform. The only guarantee is that each lower priority should be treated less-than-or-equal-to a higher priority. -#### Values #### +#### Values * `kSbThreadPriorityLowest` @@ -79,116 +79,116 @@ treated less-than-or-equal-to a higher priority. inherit the priority of the spawning thread, or it may mean a specific default priority, or it may mean something else, depending on the platform. -## Typedefs ## +## Typedefs -### SbThread ### +### SbThread An opaque handle to a thread type. -#### Definition #### +#### Definition ``` typedef void* SbThread ``` -### SbThreadAffinity ### +### SbThreadAffinity Type for thread core affinity. This generally will be a single cpu (or core or hyperthread) identifier. Some platforms may not support affinity, and some may have specific rules about how it must be used. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadAffinity ``` -### SbThreadContext ### +### SbThreadContext A handle to the context of a frozen thread. -#### Definition #### +#### Definition ``` typedef SbThreadContextPrivate* SbThreadContext ``` -### SbThreadEntryPoint ### +### SbThreadEntryPoint Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of data passed in from the calling thread. -#### Definition #### +#### Definition ``` typedef void*(* SbThreadEntryPoint) (void *context) ``` -### SbThreadId ### +### SbThreadId An ID type that is unique per thread. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadId ``` -### SbThreadLocalDestructor ### +### SbThreadLocalDestructor Function pointer type for Thread-Local destructors. -#### Definition #### +#### Definition ``` typedef void(* SbThreadLocalDestructor) (void *value) ``` -### SbThreadLocalKey ### +### SbThreadLocalKey A handle to a thread-local key. -#### Definition #### +#### Definition ``` typedef SbThreadLocalKeyPrivate* SbThreadLocalKey ``` -### SbThreadSampler ### +### SbThreadSampler A handle to a thread sampler. -#### Definition #### +#### Definition ``` typedef SbThreadSamplerPrivate* SbThreadSampler ``` -## Functions ## +## Functions -### SbThreadContextGetPointer ### +### SbThreadContextGetPointer Gets the specified pointer-type `property` from the specified `context`. Returns `true` if successful and `out_value` has been modified, otherwise returns `false` and `out_value` is not modified. -#### Declaration #### +#### Declaration ``` bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) ``` -### SbThreadContextIsValid ### +### SbThreadContextIsValid Returns whether the given thread context is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadContextIsValid(SbThreadContext context) ``` -### SbThreadCreate ### +### SbThreadCreate Creates a new thread, which starts immediately. @@ -214,13 +214,13 @@ used in production builds. `entry_point`: A pointer to a function that will be executed on the newly created thread. `context`: This value will be passed to the `entry_point` function. -#### Declaration #### +#### Declaration ``` SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) ``` -### SbThreadCreateLocalKey ### +### SbThreadCreateLocalKey Creates and returns a new, unique key for thread local data. If the function does not succeed, the function returns `kSbThreadLocalKeyInvalid`. @@ -233,13 +233,13 @@ value is not NULL. `destructor`: A pointer to a function. The value may be NULL if no clean up is needed. -#### Declaration #### +#### Declaration ``` SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) ``` -### SbThreadDestroyLocalKey ### +### SbThreadDestroyLocalKey Destroys thread local data for the specified key. The function is a no-op if the key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This @@ -247,13 +247,13 @@ function does NOT call the destructor on any stored values. `key`: The key for which to destroy thread local data. -#### Declaration #### +#### Declaration ``` void SbThreadDestroyLocalKey(SbThreadLocalKey key) ``` -### SbThreadDetach ### +### SbThreadDetach Detaches `thread`, which prevents it from being joined. This is sort of like a non-blocking join. This function is a no-op if the thread is already detached or @@ -261,33 +261,33 @@ if the thread is already being joined by another thread. `thread`: The thread to be detached. -#### Declaration #### +#### Declaration ``` void SbThreadDetach(SbThread thread) ``` -### SbThreadGetCurrent ### +### SbThreadGetCurrent Returns the handle of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThread SbThreadGetCurrent() ``` -### SbThreadGetId ### +### SbThreadGetId Returns the Thread ID of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThreadId SbThreadGetId() ``` -### SbThreadGetLocalValue ### +### SbThreadGetLocalValue Returns the pointer-sized value for `key` in the currently executing thread's local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key @@ -295,97 +295,97 @@ has already been destroyed. `key`: The key for which to return the value. -#### Declaration #### +#### Declaration ``` void* SbThreadGetLocalValue(SbThreadLocalKey key) ``` -### SbThreadGetName ### +### SbThreadGetName Returns the debug name of the currently executing thread. -#### Declaration #### +#### Declaration ``` void SbThreadGetName(char *buffer, int buffer_size) ``` -### SbThreadIsCurrent ### +### SbThreadIsCurrent Returns whether `thread` is the current thread. `thread`: The thread to check. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsCurrent(SbThread thread) ``` -### SbThreadIsEqual ### +### SbThreadIsEqual Indicates whether `thread1` and `thread2` refer to the same thread. `thread1`: The first thread to compare. `thread2`: The second thread to compare. -#### Declaration #### +#### Declaration ``` bool SbThreadIsEqual(SbThread thread1, SbThread thread2) ``` -### SbThreadIsValid ### +### SbThreadIsValid Returns whether the given thread handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValid(SbThread thread) ``` -### SbThreadIsValidAffinity ### +### SbThreadIsValidAffinity Returns whether the given thread affinity is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) ``` -### SbThreadIsValidId ### +### SbThreadIsValidId Returns whether the given thread ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidId(SbThreadId id) ``` -### SbThreadIsValidLocalKey ### +### SbThreadIsValidLocalKey Returns whether the given thread local variable key is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) ``` -### SbThreadIsValidPriority ### +### SbThreadIsValidPriority Returns whether the given thread priority is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidPriority(SbThreadPriority priority) ``` -### SbThreadJoin ### +### SbThreadJoin Joins the thread on which this function is called with joinable `thread`. This function blocks the caller until the designated thread exits, and then cleans up @@ -403,36 +403,36 @@ must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, then the SbThreadJoin function populates it with the return value of the thread's `main` function. -#### Declaration #### +#### Declaration ``` bool SbThreadJoin(SbThread thread, void **out_return) ``` -### SbThreadSamplerCreate ### +### SbThreadSamplerCreate Creates a new thread sampler for the specified `thread`. If successful, this function returns the newly created handle. If unsuccessful, this function returns `kSbThreadSamplerInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadSampler SbThreadSamplerCreate(SbThread thread) ``` -### SbThreadSamplerDestroy ### +### SbThreadSamplerDestroy Destroys the `sampler` and frees whatever resources it was using. -#### Declaration #### +#### Declaration ``` void SbThreadSamplerDestroy(SbThreadSampler sampler) ``` -### SbThreadSamplerFreeze ### +### SbThreadSamplerFreeze Suspends execution of the thread that `sampler` was created for. @@ -440,47 +440,47 @@ If successful, this function returns a `SbThreadContext` for the frozen thread, from which properties may be read while the thread remains frozen. If unsuccessful, this function returns `kSbThreadContextInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) ``` -### SbThreadSamplerIsSupported ### +### SbThreadSamplerIsSupported Whether the current platform supports thread sampling. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. If this returns false, `SbThreadSamplerCreate` will return an invalid sampler. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerIsSupported() ``` -### SbThreadSamplerIsValid ### +### SbThreadSamplerIsValid Returns whether the given thread sampler is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadSamplerIsValid(SbThreadSampler sampler) ``` -### SbThreadSamplerThaw ### +### SbThreadSamplerThaw Resumes execution of the thread that `sampler` was created for. This invalidates the context returned from `SbThreadSamplerFreeze`. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerThaw(SbThreadSampler sampler) ``` -### SbThreadSetLocalValue ### +### SbThreadSetLocalValue Sets the pointer-sized value for `key` in the currently executing thread's local storage. The return value indicates whether `key` is valid and has not already @@ -489,26 +489,26 @@ been destroyed. `key`: The key for which to set the key value. `value`: The new pointer-sized key value. -#### Declaration #### +#### Declaration ``` bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) ``` -### SbThreadSetName ### +### SbThreadSetName Sets the debug name of the currently executing thread by copying the specified name string. `name`: The name to assign to the thread. -#### Declaration #### +#### Declaration ``` void SbThreadSetName(const char *name) ``` -### SbThreadSleep ### +### SbThreadSleep Sleeps the currently executing thread. @@ -516,17 +516,17 @@ Sleeps the currently executing thread. executing thread should sleep. The function is a no-op if this value is negative or `0`. -#### Declaration #### +#### Declaration ``` void SbThreadSleep(SbTime duration) ``` -### SbThreadYield ### +### SbThreadYield Yields the currently executing thread, so another thread has a chance to run. -#### Declaration #### +#### Declaration ``` 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 19a7e4f7c49c..a6228cc0de6c 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/time.md +++ b/cobalt/site/docs/reference/starboard/modules/15/time.md @@ -1,59 +1,59 @@ ---- -layout: doc -title: "Starboard Module Reference: time.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time.h` Provides access to system time and timers. -## Macros ## +## Macros -### kSbTimeDay ### +### kSbTimeDay One day in SbTime units (microseconds). -### kSbTimeHour ### +### kSbTimeHour One hour in SbTime units (microseconds). -### kSbTimeMax ### +### kSbTimeMax The maximum value of an SbTime. -### kSbTimeMillisecond ### +### kSbTimeMillisecond One millisecond in SbTime units (microseconds). -### kSbTimeMinute ### +### kSbTimeMinute One minute in SbTime units (microseconds). -### kSbTimeNanosecondsPerMicrosecond ### +### kSbTimeNanosecondsPerMicrosecond How many nanoseconds in one SbTime unit (microseconds). -### kSbTimeSecond ### +### kSbTimeSecond One second in SbTime units (microseconds). -### kSbTimeToPosixDelta ### +### kSbTimeToPosixDelta A term that can be added to an SbTime to convert it into the number of microseconds since the POSIX epoch. -## Typedefs ## +## Typedefs -### SbTime ### +### SbTime The number of microseconds since the epoch of January 1, 1601 UTC, or the number of microseconds between two times. Always microseconds, ALWAYS UTC. -#### Definition #### +#### Definition ``` typedef int64_t SbTime ``` -### SbTimeMonotonic ### +### SbTimeMonotonic A number of microseconds from some point. The main property of this time is that it increases monotonically. It should also be as high-resolution a timer as we @@ -61,38 +61,38 @@ can get on a platform. So, it is good for measuring the time between two calls without worrying about a system clock adjustment. It's not good for getting the wall clock time. -#### Definition #### +#### Definition ``` typedef int64_t SbTimeMonotonic ``` -## Functions ## +## Functions -### SbTimeFromPosix ### +### SbTimeFromPosix Converts microseconds from the POSIX epoch into an `SbTime`. `time`: A time that measures the number of microseconds since January 1, 1970, 00:00:00, UTC. -#### Declaration #### +#### Declaration ``` static SbTime SbTimeFromPosix(int64_t time) ``` -### SbTimeGetMonotonicNow ### +### SbTimeGetMonotonicNow Gets a monotonically increasing time representing right now. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicNow() ``` -### SbTimeGetMonotonicThreadNow ### +### SbTimeGetMonotonicThreadNow Gets a monotonically increasing time representing how long the current thread has been in the executing state (i.e. not pre-empted nor waiting on an event). @@ -100,44 +100,44 @@ This is not necessarily total time and is intended to allow measuring thread execution time between two timestamps. If this is not available then SbTimeGetMonotonicNow() should be used. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicThreadNow() ``` -### SbTimeGetNow ### +### SbTimeGetNow Gets the current system time as an `SbTime`. -#### Declaration #### +#### Declaration ``` SbTime SbTimeGetNow() ``` -### SbTimeIsTimeThreadNowSupported ### +### SbTimeIsTimeThreadNowSupported Returns whether the current platform supports time thread now -#### Declaration #### +#### Declaration ``` bool SbTimeIsTimeThreadNowSupported() ``` -### SbTimeNarrow ### +### SbTimeNarrow Safely narrows a number from a more precise unit to a less precise one. This function rounds negative values toward negative infinity. -#### Declaration #### +#### Declaration ``` static int64_t SbTimeNarrow(int64_t time, int64_t divisor) ``` -### SbTimeToPosix ### +### SbTimeToPosix Converts `SbTime` into microseconds from the POSIX epoch. @@ -145,7 +145,7 @@ Converts `SbTime` into microseconds from the POSIX epoch. January 1, 1601, UTC, or that measures the number of microseconds between two times. -#### Declaration #### +#### Declaration ``` 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 f9e3fcb1ca1d..74d48172d63e 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/15/time_zone.md @@ -1,38 +1,38 @@ ---- -layout: doc -title: "Starboard Module Reference: time_zone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time_zone.h` Provides access to the system time zone information. -## Typedefs ## +## Typedefs -### SbTimeZone ### +### SbTimeZone 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). -#### Definition #### +#### Definition ``` typedef int SbTimeZone ``` -## Functions ## +## Functions -### SbTimeZoneGetCurrent ### +### SbTimeZoneGetCurrent Gets the system's current SbTimeZone in minutes. -#### Declaration #### +#### Declaration ``` SbTimeZone SbTimeZoneGetCurrent() ``` -### SbTimeZoneGetName ### +### 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 @@ -40,7 +40,7 @@ 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". -#### Declaration #### +#### Declaration ``` const char* SbTimeZoneGetName() diff --git a/cobalt/site/docs/reference/starboard/modules/15/types.md b/cobalt/site/docs/reference/starboard/modules/15/types.md index 90867a69542f..e1f372cc60c4 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/types.md +++ b/cobalt/site/docs/reference/starboard/modules/15/types.md @@ -1,15 +1,15 @@ ---- -layout: doc -title: "Starboard Module Reference: types.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `types.h` Provides a suite of standard types that should be universally available on all platforms, specifically focused on explicitly-sized integer types and booleans. This module also includes some related ubiquitous definitions like limits of the explicitly-sized integer types, and standard pointer and int32 sentinel values. -## Macros ## +## Macros -### kSbInvalidInt ### +### kSbInvalidInt A value that represents an int that is probably invalid. 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 a0ecfb1eafb8..cb4176713005 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/15/ui_navigation.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: ui_navigation.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `ui_navigation.h` API to allow applications to take advantage of the platform's native UI engine. This is mainly to drive the animation of visual elements and to signal which of @@ -19,20 +19,20 @@ SbUiNavItem in case the native UI engine moves individual items in response to user interaction. If the navigation item is a container, then the content offset will also be queried to determine the placement of its content items. -## Macros ## +## Macros -### kSbUiNavItemInvalid ### +### kSbUiNavItemInvalid Well-defined value for an invalid navigation item. -## Enums ## +## Enums -### SbUiNavItemType ### +### SbUiNavItemType Navigation items may be one of the following types. This must be specified upon item creation and may not change during the item's lifespan. -#### Values #### +#### Values * `kSbUiNavItemTypeFocus` @@ -42,29 +42,29 @@ item creation and may not change during the item's lifespan. This is a container of navigation items which can also be containers themselves or focusable items. Containers themselves cannot be focused. -## Typedefs ## +## Typedefs -### SbUiNavItem ### +### SbUiNavItem An opaque handle to an implementation-private structure representing a navigation item. -#### Definition #### +#### Definition ``` typedef struct SbUiNavItemPrivate* SbUiNavItem ``` -## Structs ## +## Structs -### SbUiNavCallbacks ### +### SbUiNavCallbacks This structure specifies all the callbacks which the platform UI engine should invoke for various interaction events on navigation items. These callbacks may be invoked from any thread at any frequency. The `callback_context` is the value that was passed on creation of the relevant SbUiNavItem. -#### Members #### +#### Members * `void(*onblur)(SbUiNavItem item, void *callback_context)` @@ -77,12 +77,12 @@ that was passed on creation of the relevant SbUiNavItem. Invoke when an item's content offset is changed. This is only used with container items. -### SbUiNavInterface ### +### SbUiNavInterface This structure declares the interface to the UI navigation implementation. All function pointers must be specified if the platform supports UI navigation. -#### Members #### +#### Members * `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks *callbacks, void *callback_context)` @@ -237,7 +237,7 @@ function pointers must be specified if the platform supports UI navigation. Call `update_function` with `context` to perform a series of UI navigation changes atomically before returning. -### SbUiNavItemDir ### +### SbUiNavItemDir Navigation items of type kSbUiNavItemTypeContainer have directionality. If directionality is not specified for a container, it should default to left-to- @@ -270,12 +270,12 @@ right and top-to-bottom. Bottom-to-top is similar to right-to-left, but for the Y position. ``` -#### Members #### +#### Members * `bool is_left_to_right` * `bool is_top_to_bottom` -### SbUiNavMatrix2x3 ### +### SbUiNavMatrix2x3 This represents a 2x3 transform matrix in row-major order. @@ -284,38 +284,38 @@ This represents a 2x3 transform matrix in row-major order. /// | c d ty | ``` -#### Members #### +#### Members * `float m` -### SbUiNavMatrix4 ### +### SbUiNavMatrix4 This represents a 4x4 transform matrix in row-major order. -#### Members #### +#### Members * `float m` -## Functions ## +## Functions -### SbUiNavGetInterface ### +### SbUiNavGetInterface Retrieve the platform's UI navigation implementation. If the platform does not provide one, then return false without modifying `out_interface`. Otherwise, initialize all members of `out_interface` and return true. The `out_interface` pointer must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbUiNavGetInterface(SbUiNavInterface *out_interface) ``` -### SbUiNavItemIsValid ### +### SbUiNavItemIsValid Returns whether the given navigation item handle is valid. -#### Declaration #### +#### Declaration ``` 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 406e695c4a2e..309b939d066e 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/user.md +++ b/cobalt/site/docs/reference/starboard/modules/15/user.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: user.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `user.h` Defines a user management API. This module defines functions only for managing signed-in users. Platforms that do not have users must still implement this API, @@ -10,19 +10,19 @@ always reporting a single user that is current and signed in. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbUserInvalid ### +### kSbUserInvalid Well-defined value for an invalid user. -## Enums ## +## Enums -### SbUserPropertyId ### +### SbUserPropertyId A set of string properties that can be queried on a user. -#### Values #### +#### Values * `kSbUserPropertyAvatarUrl` @@ -38,21 +38,21 @@ A set of string properties that can be queried on a user. A unique user ID of a user. -## Typedefs ## +## Typedefs -### SbUser ### +### SbUser A handle to a user. -#### Definition #### +#### Definition ``` typedef SbUserPrivate* SbUser ``` -## Functions ## +## Functions -### SbUserGetCurrent ### +### SbUserGetCurrent Gets the current primary user, if one exists. This is the user that is determined, in a platform-specific way, to be the primary user controlling the @@ -63,13 +63,13 @@ appropriate for the platform. It is expected that there will be a unique SbUser per signed-in user, and that the referenced objects will persist for the lifetime of the app. -#### Declaration #### +#### Declaration ``` SbUser SbUserGetCurrent() ``` -### SbUserGetProperty ### +### SbUserGetProperty Retrieves the value of `property_id` for `user` and places it in `out_value`. The function returns: @@ -83,13 +83,13 @@ The function returns: The property for which the data is requested. `out_value`: The retrieved property value. `value_size`: The size of the retrieved property value. -#### Declaration #### +#### Declaration ``` bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) ``` -### SbUserGetPropertySize ### +### SbUserGetPropertySize Returns the size of the value of `property_id` for `user`, INCLUDING the terminating null character. The function returns `0` if `user` is invalid or if @@ -98,13 +98,13 @@ terminating null character. The function returns `0` if `user` is invalid or if `user`: The user for which property size data is being retrieved. `property_id`: The property for which the data is requested. -#### Declaration #### +#### Declaration ``` int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) ``` -### SbUserGetSignedIn ### +### SbUserGetSignedIn Gets a list of up to `users_size` signed-in users and places the results in `out_users`. The return value identifies the actual number of signed-in users, @@ -116,17 +116,17 @@ the referenced objects will persist for the lifetime of the app. `out_users`: Handles for the retrieved users. `users_size`: The maximum number of signed-in users to retrieve. -#### Declaration #### +#### Declaration ``` int SbUserGetSignedIn(SbUser *out_users, int users_size) ``` -### SbUserIsValid ### +### SbUserIsValid Returns whether the given user handle is valid. -#### Declaration #### +#### Declaration ``` 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 915e254667c6..acea84d4c7d0 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/window.md +++ b/cobalt/site/docs/reference/starboard/modules/15/window.md @@ -1,40 +1,40 @@ ---- -layout: doc -title: "Starboard Module Reference: window.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `window.h` Provides functionality to handle Window creation and management. -## Macros ## +## Macros -### kSbEventOnScreenKeyboardInvalidTicket ### +### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value kSbEventOnScreenKeyboardInvalidTicket. -### kSbWindowInvalid ### +### kSbWindowInvalid Well-defined value for an invalid window handle. -## Typedefs ## +## Typedefs -### SbWindow ### +### SbWindow A handle to a window. -#### Definition #### +#### Definition ``` typedef SbWindowPrivate* SbWindow ``` -## Structs ## +## Structs -### SbWindowOptions ### +### SbWindowOptions Options that can be requested at window creation time. -#### Members #### +#### Members * `SbWindowSize size` @@ -48,25 +48,25 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect ### +### SbWindowRect Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. -#### Members #### +#### Members * `float x` * `float y` * `float width` * `float height` -### SbWindowSize ### +### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window. -#### Members #### +#### Members * `int width` @@ -93,9 +93,9 @@ that would be created to back that window. A value of 0.0f means the ratio could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f). -## Functions ## +## Functions -### SbWindowBlurOnScreenKeyboard ### +### SbWindowBlurOnScreenKeyboard Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred. kSbEventTypeOnScreenKeyboardBlurred has data `ticket`. Calling @@ -103,13 +103,13 @@ 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 #### +#### Declaration ``` void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowCreate ### +### SbWindowCreate Creates and returns a new system window with the given `options`, which may be `NULL`. The function returns `kSbWindowInvalid` if it cannot create the @@ -131,25 +131,25 @@ entry point. `options`: Options that specify parameters for the window being created. -#### Declaration #### +#### Declaration ``` SbWindow SbWindowCreate(const SbWindowOptions *options) ``` -### SbWindowDestroy ### +### SbWindowDestroy Destroys `window`, reclaiming associated resources. `window`: The `SbWindow` to destroy. -#### Declaration #### +#### Declaration ``` bool SbWindowDestroy(SbWindow window) ``` -### SbWindowFocusOnScreenKeyboard ### +### SbWindowFocusOnScreenKeyboard Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused. kSbEventTypeOnScreenKeyboardFocused has data `ticket`. Calling @@ -157,38 +157,38 @@ 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 #### +#### Declaration ``` void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowGetDiagonalSizeInInches ### +### SbWindowGetDiagonalSizeInInches Gets the size of the diagonal between two opposing screen corners. A return value of 0 means that starboard does not know what the screen diagonal is. -#### Declaration #### +#### Declaration ``` float SbWindowGetDiagonalSizeInInches(SbWindow window) ``` -### SbWindowGetOnScreenKeyboardBoundingRect ### +### 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 #### +#### Declaration ``` bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect) ``` -### SbWindowGetPlatformHandle ### +### SbWindowGetPlatformHandle Gets the platform-specific handle for `window`, which can be passed as an EGLNativeWindowType to initialize EGL/GLES. This return value is entirely @@ -196,13 +196,13 @@ platform-specific, so there are no constraints about expected ranges. `window`: The SbWindow to retrieve the platform handle for. -#### Declaration #### +#### Declaration ``` void* SbWindowGetPlatformHandle(SbWindow window) ``` -### SbWindowGetSize ### +### SbWindowGetSize Retrieves the dimensions of `window` and sets `size` accordingly. This function returns `true` if it completes successfully. If the function returns `false`, @@ -210,81 +210,81 @@ then `size` will not have been modified. `window`: The SbWindow to retrieve the size of. `size`: The retrieved size. -#### Declaration #### +#### Declaration ``` bool SbWindowGetSize(SbWindow window, SbWindowSize *size) ``` -### SbWindowHideOnScreenKeyboard ### +### 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 #### +#### Declaration ``` void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowIsOnScreenKeyboardShown ### +### SbWindowIsOnScreenKeyboardShown Determine if the on screen keyboard is shown. -#### Declaration #### +#### Declaration ``` bool SbWindowIsOnScreenKeyboardShown(SbWindow window) ``` -### SbWindowIsValid ### +### SbWindowIsValid Returns whether the given window handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbWindowIsValid(SbWindow window) ``` -### SbWindowOnScreenKeyboardIsSupported ### +### SbWindowOnScreenKeyboardIsSupported Return whether the current platform supports an on screen keyboard -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardIsSupported() ``` -### SbWindowOnScreenKeyboardSuggestionsSupported ### +### SbWindowOnScreenKeyboardSuggestionsSupported Determine if the on screen keyboard has suggestions implemented. If this returns false, then calling SbWindowUpdateOnScreenKeyboardSuggestions() will be undefined. -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardSuggestionsSupported(SbWindow window) ``` -### SbWindowSetDefaultOptions ### +### SbWindowSetDefaultOptions Sets the default options for system windows. `options`: The option values to use as default values. This object must not be `NULL`. -#### Declaration #### +#### Declaration ``` void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` -### SbWindowSetOnScreenKeyboardKeepFocus ### +### 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 @@ -293,13 +293,13 @@ OnScreenKeyboard via input; focus may only be moved via events sent by the app. OnScreenKeyboard via input. `keepFocus` is initialized to false in the OnScreenKeyboard constructor. -#### Declaration #### +#### Declaration ``` void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus) ``` -### SbWindowShowOnScreenKeyboard ### +### SbWindowShowOnScreenKeyboard Show the on screen keyboard and populate the input with text `input_text`. Fire kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary. @@ -309,13 +309,13 @@ 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 #### +#### Declaration ``` void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket) ``` -### SbWindowUpdateOnScreenKeyboardSuggestions ### +### SbWindowUpdateOnScreenKeyboardSuggestions Update the on screen keyboard custom suggestions. Fire kSbEventTypeOnScreenKeyboardSuggestionsUpdated. @@ -323,7 +323,7 @@ kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data `ticket`. The suggestions should remain up-to-date when the keyboard is shown after being hidden. -#### Declaration #### +#### Declaration ``` void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) diff --git a/cobalt/site/docs/reference/starboard/modules/accessibility.md b/cobalt/site/docs/reference/starboard/modules/accessibility.md index a6c8460bcf2b..8f2a652445a9 100644 --- a/cobalt/site/docs/reference/starboard/modules/accessibility.md +++ b/cobalt/site/docs/reference/starboard/modules/accessibility.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: accessibility.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `accessibility.h` Provides access to the system options and settings related to accessibility. -## Enums ## +## Enums -### SbAccessibilityCaptionCharacterEdgeStyle ### +### SbAccessibilityCaptionCharacterEdgeStyle Enum for possible closed captioning character edge styles. -#### Values #### +#### Values * `kSbAccessibilityCaptionCharacterEdgeStyleNone` * `kSbAccessibilityCaptionCharacterEdgeStyleRaised` @@ -19,11 +19,11 @@ Enum for possible closed captioning character edge styles. * `kSbAccessibilityCaptionCharacterEdgeStyleUniform` * `kSbAccessibilityCaptionCharacterEdgeStyleDropShadow` -### SbAccessibilityCaptionColor ### +### SbAccessibilityCaptionColor Enum for possible closed captioning colors. -#### Values #### +#### Values * `kSbAccessibilityCaptionColorBlue` * `kSbAccessibilityCaptionColorBlack` @@ -34,11 +34,11 @@ Enum for possible closed captioning colors. * `kSbAccessibilityCaptionColorWhite` * `kSbAccessibilityCaptionColorYellow` -### SbAccessibilityCaptionFontFamily ### +### SbAccessibilityCaptionFontFamily Enum for possible closed captioning font families -#### Values #### +#### Values * `kSbAccessibilityCaptionFontFamilyCasual` * `kSbAccessibilityCaptionFontFamilyCursive` @@ -48,11 +48,11 @@ Enum for possible closed captioning font families * `kSbAccessibilityCaptionFontFamilyProportionalSerif` * `kSbAccessibilityCaptionFontFamilySmallCapitals` -### SbAccessibilityCaptionFontSizePercentage ### +### SbAccessibilityCaptionFontSizePercentage Enum for possible closed captioning font size percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionFontSizePercentage25` * `kSbAccessibilityCaptionFontSizePercentage50` @@ -67,11 +67,11 @@ Enum for possible closed captioning font size percentages. * `kSbAccessibilityCaptionFontSizePercentage275` * `kSbAccessibilityCaptionFontSizePercentage300` -### SbAccessibilityCaptionOpacityPercentage ### +### SbAccessibilityCaptionOpacityPercentage Enum for possible closed captioning opacity percentages. -#### Values #### +#### Values * `kSbAccessibilityCaptionOpacityPercentage0` * `kSbAccessibilityCaptionOpacityPercentage25` @@ -79,11 +79,11 @@ Enum for possible closed captioning opacity percentages. * `kSbAccessibilityCaptionOpacityPercentage75` * `kSbAccessibilityCaptionOpacityPercentage100` -### SbAccessibilityCaptionState ### +### SbAccessibilityCaptionState Enum for possible states of closed captioning properties. -#### Values #### +#### Values * `kSbAccessibilityCaptionStateUnsupported` @@ -115,14 +115,14 @@ Enum for possible states of closed captioning properties. SbAccessibilityCaptionSettings.supportsOverride contains false, then no fields of SbAccessibilityCaptionSettings will ever contain this value. -## Structs ## +## Structs -### SbAccessibilityCaptionSettings ### +### SbAccessibilityCaptionSettings A group of settings related to system-level closed captioning settings, for platforms that expose closed captioning settings. -#### Members #### +#### Members * `SbAccessibilityCaptionColor background_color` * `SbAccessibilityCaptionState background_color_state` @@ -166,9 +166,9 @@ platforms that expose closed captioning settings. false, the values of `SbAccessibilityCaptionState` should be interpreted differently. -### SbAccessibilityDisplaySettings ### +### SbAccessibilityDisplaySettings -#### Members #### +#### Members * `bool has_high_contrast_text_setting` @@ -177,12 +177,12 @@ platforms that expose closed captioning settings. Whether the high contrast text setting is enabled or not. -### SbAccessibilityTextToSpeechSettings ### +### SbAccessibilityTextToSpeechSettings A group of settings related to text-to-speech functionality, for platforms that expose system settings for text-to-speech. -#### Members #### +#### Members * `bool has_text_to_speech_setting` @@ -192,9 +192,9 @@ expose system settings for text-to-speech. Whether the text-to-speech setting is enabled or not. This setting is only valid if `has_text_to_speech_setting` is set to true. -## Functions ## +## Functions -### SbAccessibilityGetCaptionSettings ### +### SbAccessibilityGetCaptionSettings Get the platform's settings for system-level closed captions. This function returns false if `caption_settings` is NULL or if it is not zero-initialized. @@ -202,13 +202,13 @@ returns false if `caption_settings` is NULL or if it is not zero-initialized. `caption_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetCaptionSettings(SbAccessibilityCaptionSettings *caption_settings) ``` -### SbAccessibilityGetDisplaySettings ### +### SbAccessibilityGetDisplaySettings Get the platform settings related to high contrast text. This function returns false if `out_settings` is NULL or if it is not zero-initialized. @@ -216,13 +216,13 @@ false if `out_settings` is NULL or if it is not zero-initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityDisplaySettings* struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetDisplaySettings(SbAccessibilityDisplaySettings *out_settings) ``` -### SbAccessibilityGetTextToSpeechSettings ### +### SbAccessibilityGetTextToSpeechSettings Get the platform settings related to the text-to-speech accessibility feature. This function returns false if `out_settings` is NULL or if it is not zero- @@ -231,13 +231,13 @@ initialized. `out_settings`: A pointer to a zero-initialized SbAccessibilityTextToSpeechSettings struct. -#### Declaration #### +#### Declaration ``` bool SbAccessibilityGetTextToSpeechSettings(SbAccessibilityTextToSpeechSettings *out_settings) ``` -### SbAccessibilitySetCaptionsEnabled ### +### SbAccessibilitySetCaptionsEnabled Modifies whether closed captions are enabled at a system level. This function returns false if this feature is not supported by the platform, or if changing @@ -246,7 +246,7 @@ the setting is unsuccessful. This function will modify the setting system-wide. `enabled`: A boolean indicating whether captions should be turned on (true) or off (false). -#### Declaration #### +#### Declaration ``` 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 5f799906cdaf..9653e53cecd3 100644 --- a/cobalt/site/docs/reference/starboard/modules/atomic.md +++ b/cobalt/site/docs/reference/starboard/modules/atomic.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: atomic.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `atomic.h` Defines a set of atomic integer operations that can be used as lightweight synchronization or as building blocks for heavier synchronization primitives. @@ -9,32 +9,32 @@ Their use is very subtle and requires detailed understanding of the behavior of supported architectures, so their direct use is not recommended except when rigorously deemed absolutely necessary for performance reasons. -## Typedefs ## +## Typedefs -### SbAtomic64 ### +### SbAtomic64 64-bit atomic operations (only available on 64-bit processors). -#### Definition #### +#### Definition ``` typedef int64_t SbAtomic64 ``` -### SbAtomicPtr ### +### SbAtomicPtr Pointer-sized atomic operations. Forwards to either 32-bit or 64-bit functions as appropriate. -#### Definition #### +#### Definition ``` typedef SbAtomic32 SbAtomicPtr ``` -## Functions ## +## Functions -### SbAtomicAcquire_CompareAndSwap ### +### SbAtomicAcquire_CompareAndSwap These following lower-level operations are typically useful only to people implementing higher-level synchronization operations like spinlocks, mutexes, @@ -45,23 +45,23 @@ operations ensure that no previous memory access can be reordered after the operation. "Barrier" operations have both "Acquire" and "Release" semantics. A SbAtomicMemoryBarrier() has "Barrier" semantics, but does no memory access. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicAcquire_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicBarrier_Increment ### +### SbAtomicBarrier_Increment Same as SbAtomicNoBarrier_Increment, but with a memory barrier. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicNoBarrier_CompareAndSwap ### +### SbAtomicNoBarrier_CompareAndSwap Atomically execute: result = *ptr; if (*ptr == old_value) *ptr = new_value; return result; @@ -71,39 +71,39 @@ return the old value of "*ptr" This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_CompareAndSwap(volatile SbAtomic32 *ptr, SbAtomic32 old_value, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Exchange ### +### SbAtomicNoBarrier_Exchange Atomically store new_value into *ptr, returning the previous value held in *ptr. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Exchange(volatile SbAtomic32 *ptr, SbAtomic32 new_value) ``` -### SbAtomicNoBarrier_Increment ### +### SbAtomicNoBarrier_Increment Atomically increment *ptr by "increment". Returns the new value of *ptr with the increment applied. This routine implies no memory barriers. -#### Declaration #### +#### Declaration ``` static SbAtomic32 SbAtomicNoBarrier_Increment(volatile SbAtomic32 *ptr, SbAtomic32 increment) ``` -### SbAtomicRelease_CompareAndSwap8 ### +### SbAtomicRelease_CompareAndSwap8 Overloaded functions for Atomic8. -#### Declaration #### +#### Declaration ``` 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 b0e652f50e92..9277c70837b0 100644 --- a/cobalt/site/docs/reference/starboard/modules/audio_sink.md +++ b/cobalt/site/docs/reference/starboard/modules/audio_sink.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: audio_sink.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `audio_sink.h` Provides an interface to output raw audio data. -## Macros ## +## Macros -### kSbAudioSinkInvalid ### +### kSbAudioSinkInvalid Well-defined value for an invalid audio sink. -## Typedefs ## +## Typedefs -### SbAudioSink ### +### SbAudioSink An opaque handle to an implementation-private structure representing an audio sink. -#### Definition #### +#### Definition ``` typedef struct SbAudioSinkPrivate* SbAudioSink ``` -### SbAudioSinkConsumeFramesFunc ### +### SbAudioSinkConsumeFramesFunc Callback used to report frames consumed. The consumed frames will be removed from the source frame buffer to free space for new audio frames. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkConsumeFramesFunc) (int frames_consumed, void *context) ``` -### SbAudioSinkFrameBuffers ### +### SbAudioSinkFrameBuffers An array of frame buffers. For interleaved audio streams, there will be only one element in the array. For planar audio streams, the number of elements in the array equal to the number of channels. -#### Definition #### +#### Definition ``` typedef void** SbAudioSinkFrameBuffers ``` -### SbAudioSinkUpdateSourceStatusFunc ### +### SbAudioSinkUpdateSourceStatusFunc Callback being called periodically to retrieve the status of the audio source. The first two output parameters indicating the filling level of the audio frame @@ -64,15 +64,15 @@ usually this is caused by a seek. All parameters except `context` cannot be NULL. Note that this function only reports the status of the source, it doesn't remove audio data from the source frame buffer. -#### Definition #### +#### Definition ``` typedef void(* SbAudioSinkUpdateSourceStatusFunc) (int *frames_in_buffer, int *offset_in_frames, bool *is_playing, bool *is_eos_reached, void *context) ``` -## Functions ## +## Functions -### SbAudioSinkCreate ### +### SbAudioSinkCreate Creates an audio sink for the specified `channels` and `sampling_frequency_hz`, acquires all resources needed to operate the audio sink, and returns an opaque @@ -113,13 +113,13 @@ to sample data. value that is passed back to all callbacks and is generally used to point at a class or struct that contains state associated with the audio sink. -#### Declaration #### +#### Declaration ``` SbAudioSink SbAudioSinkCreate(int channels, int sampling_frequency_hz, SbMediaAudioSampleType audio_sample_type, SbMediaAudioFrameStorageType audio_frame_storage_type, SbAudioSinkFrameBuffers frame_buffers, int frames_per_channel, SbAudioSinkUpdateSourceStatusFunc update_source_status_func, SbAudioSinkConsumeFramesFunc consume_frames_func, void *context) ``` -### SbAudioSinkDestroy ### +### SbAudioSinkDestroy Destroys `audio_sink`, freeing all associated resources. Before returning, the function waits until all callbacks that are in progress have finished. After the @@ -132,24 +132,24 @@ any of the callbacks passed into SbAudioSinkCreate. `audio_sink`: The audio sink to destroy. -#### Declaration #### +#### Declaration ``` void SbAudioSinkDestroy(SbAudioSink audio_sink) ``` -### SbAudioSinkGetMaxChannels ### +### SbAudioSinkGetMaxChannels Returns the maximum number of channels supported on the platform. For example, the number would be `2` if the platform only supports stereo. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMaxChannels() ``` -### SbAudioSinkGetMinBufferSizeInFrames ### +### SbAudioSinkGetMinBufferSizeInFrames Returns the minimum frames required by audio sink to play without underflows. Returns -1, if `channels`, `sample_type` or `sampling_frequency_hz` is not @@ -162,52 +162,52 @@ stereo audio. `audio_sample_type`: The type of each sample of the audio data – audio data being streamed. For example, 22,000 Hz means 22,000 sample elements represents one second of audio data. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetMinBufferSizeInFrames(int channels, SbMediaAudioSampleType sample_type, int sampling_frequency_hz) ``` -### SbAudioSinkGetNearestSupportedSampleFrequency ### +### SbAudioSinkGetNearestSupportedSampleFrequency Returns the supported sample rate closest to `sampling_frequency_hz`. On platforms that don't support all sample rates, it is the caller's responsibility to resample the audio frames into the supported sample rate returned by this function. -#### Declaration #### +#### Declaration ``` int SbAudioSinkGetNearestSupportedSampleFrequency(int sampling_frequency_hz) ``` -### SbAudioSinkIsAudioFrameStorageTypeSupported ### +### SbAudioSinkIsAudioFrameStorageTypeSupported Indicates whether `audio_frame_storage_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioFrameStorageTypeSupported(SbMediaAudioFrameStorageType audio_frame_storage_type) ``` -### SbAudioSinkIsAudioSampleTypeSupported ### +### SbAudioSinkIsAudioSampleTypeSupported Indicates whether `audio_sample_type` is supported on this platform. -#### Declaration #### +#### Declaration ``` bool SbAudioSinkIsAudioSampleTypeSupported(SbMediaAudioSampleType audio_sample_type) ``` -### SbAudioSinkIsValid ### +### SbAudioSinkIsValid Indicates whether the given audio sink handle is valid. `audio_sink`: The audio sink handle to check. -#### Declaration #### +#### Declaration ``` 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 580bc5dbb0e5..4b2cab30de3d 100644 --- a/cobalt/site/docs/reference/starboard/modules/byte_swap.md +++ b/cobalt/site/docs/reference/starboard/modules/byte_swap.md @@ -1,74 +1,74 @@ ---- -layout: doc -title: "Starboard Module Reference: byte_swap.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `byte_swap.h` Specifies functions for swapping byte order. These functions are used to deal with endianness when performing I/O. -## Functions ## +## Functions -### SbByteSwapS16 ### +### SbByteSwapS16 Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int16_t SbByteSwapS16(int16_t value) ``` -### SbByteSwapS32 ### +### SbByteSwapS32 Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int32_t SbByteSwapS32(int32_t value) ``` -### SbByteSwapS64 ### +### SbByteSwapS64 Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` int64_t SbByteSwapS64(int64_t value) ``` -### SbByteSwapU16 ### +### SbByteSwapU16 Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint16_t SbByteSwapU16(uint16_t value) ``` -### SbByteSwapU32 ### +### SbByteSwapU32 Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint32_t SbByteSwapU32(uint32_t value) ``` -### SbByteSwapU64 ### +### SbByteSwapU64 Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The value for which the byte order will be swapped. -#### Declaration #### +#### Declaration ``` uint64_t SbByteSwapU64(uint64_t value) diff --git a/cobalt/site/docs/reference/starboard/modules/condition_variable.md b/cobalt/site/docs/reference/starboard/modules/condition_variable.md index 836c4b813d9c..a665a24f45bf 100644 --- a/cobalt/site/docs/reference/starboard/modules/condition_variable.md +++ b/cobalt/site/docs/reference/starboard/modules/condition_variable.md @@ -1,23 +1,23 @@ ---- -layout: doc -title: "Starboard Module Reference: condition_variable.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `condition_variable.h` Defines an interface for condition variables. -## Macros ## +## Macros -### SB_CONDITION_VARIABLE_MAX_SIZE ### +### SB_CONDITION_VARIABLE_MAX_SIZE Max size of the SbConditionVariable type. -## Enums ## +## Enums -### SbConditionVariableResult ### +### SbConditionVariableResult Enumeration of possible results from waiting on a condvar. -#### Values #### +#### Values * `kSbConditionVariableSignaled` @@ -30,22 +30,22 @@ Enumeration of possible results from waiting on a condvar. The wait failed, either because a parameter wasn't valid, or the condition variable has already been destroyed, or something similar. -## Typedefs ## +## Typedefs -### SbConditionVariable ### +### SbConditionVariable An opaque handle to a condition variable type with reserved memory buffer of size SB_CONDITION_VARIABLE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbConditionVariable SbConditionVariable ``` -## Functions ## +## Functions -### SbConditionVariableBroadcast ### +### SbConditionVariableBroadcast Broadcasts to all current waiters of `condition` to stop waiting. This function wakes all of the threads waiting on `condition` while SbConditionVariableSignal @@ -53,26 +53,26 @@ wakes a single thread. `condition`: The condition that should no longer be waited for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableBroadcast(SbConditionVariable *condition) ``` -### SbConditionVariableCreate ### +### SbConditionVariableCreate Creates a new condition variable to work with `opt_mutex`, which may be null, placing the newly created condition variable in `out_condition`. The return value indicates whether the condition variable could be created. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableCreate(SbConditionVariable *out_condition, SbMutex *opt_mutex) ``` -### SbConditionVariableDestroy ### +### SbConditionVariableDestroy Destroys the specified SbConditionVariable . The return value indicates whether the destruction was successful. The behavior is undefined if other threads are @@ -81,23 +81,23 @@ currently waiting on this condition variable. `condition`: The SbConditionVariable to be destroyed. This invalidates the condition variable. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableDestroy(SbConditionVariable *condition) ``` -### SbConditionVariableIsSignaled ### +### SbConditionVariableIsSignaled Returns whether the given result is a success. -#### Declaration #### +#### Declaration ``` static bool SbConditionVariableIsSignaled(SbConditionVariableResult result) ``` -### SbConditionVariableSignal ### +### SbConditionVariableSignal Signals the next waiter of `condition` to stop waiting. This function wakes a single thread waiting on `condition` while SbConditionVariableBroadcast wakes @@ -105,24 +105,24 @@ all threads waiting on it. `condition`: The condition that the waiter should stop waiting for. -#### Declaration #### +#### Declaration ``` bool SbConditionVariableSignal(SbConditionVariable *condition) ``` -### SbConditionVariableWait ### +### SbConditionVariableWait Waits for `condition`, releasing the held lock `mutex`, blocking indefinitely, and returning the result. Behavior is undefined if `mutex` is not held. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWait(SbConditionVariable *condition, SbMutex *mutex) ``` -### SbConditionVariableWaitTimed ### +### SbConditionVariableWaitTimed Waits for `condition`, releasing the held lock `mutex`, blocking up to `timeout_duration`, and returning the acquisition result. Behavior is undefined @@ -133,7 +133,7 @@ if `mutex` is not held. function returns as quickly as possible with a kSbConditionVariableTimedOut result. -#### Declaration #### +#### Declaration ``` SbConditionVariableResult SbConditionVariableWaitTimed(SbConditionVariable *condition, SbMutex *mutex, SbTime timeout_duration) diff --git a/cobalt/site/docs/reference/starboard/modules/configuration.md b/cobalt/site/docs/reference/starboard/modules/configuration.md index 630f1cf32228..d0ba3c7196f8 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration.h` Provides a description of the current platform in lurid detail so that common code never needs to actually know what the current operating system and @@ -13,117 +13,117 @@ Configuration feature instead. This implies the continued existence of very narrowly-defined configuration features, but it retains porting control in Starboard. -## Macros ## +## Macros -### SB_ALIGNAS(byte_alignment) ### +### SB_ALIGNAS(byte_alignment) Specifies the alignment for a class, struct, union, enum, class/struct field, or stack variable. -### SB_ALIGNOF(type) ### +### SB_ALIGNOF(type) Returns the alignment required for any instance of the type indicated by `type`. -### SB_ARRAY_SIZE(array) ### +### SB_ARRAY_SIZE(array) A constant expression that evaluates to the size_t size of a statically-sized array. -### SB_ARRAY_SIZE_INT(array) ### +### SB_ARRAY_SIZE_INT(array) A constant expression that evaluates to the int size of a statically-sized array. -### SB_CAN(SB_FEATURE) ### +### SB_CAN(SB_FEATURE) Determines a compile-time capability of the system. -### SB_COMPILE_ASSERT(expr, msg) ### +### SB_COMPILE_ASSERT(expr, msg) Will cause a compiler error with `msg` if `expr` is false. `msg` must be a valid identifier, and must be a unique type in the scope of the declaration. -### SB_DEPRECATED(FUNC) ### +### SB_DEPRECATED(FUNC) SB_DEPRECATED(int Foo(int bar)); Annotates the function as deprecated, which will trigger a compiler warning when referenced. -### SB_DEPRECATED_EXTERNAL(FUNC) ### +### SB_DEPRECATED_EXTERNAL(FUNC) SB_DEPRECATED_EXTERNAL(...) annotates the function as deprecated for external clients, but not deprecated for starboard. -### SB_EXPERIMENTAL_API_VERSION ### +### 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 ### +### SB_FUNCTION Whether we use **PRETTY_FUNCTION** PRETTY_FUNCTION or **FUNCTION** FUNCTION for logging. -### SB_HAS(SB_FEATURE) ### +### SB_HAS(SB_FEATURE) Determines at compile-time whether this platform has a standard feature or header available. -### SB_HAS_64_BIT_ATOMICS ### +### SB_HAS_64_BIT_ATOMICS Whether the current platform has 64-bit atomic operations. -### SB_HAS_GLES2 ### +### SB_HAS_GLES2 Specifies whether this platform has a performant OpenGL ES 2 implementation, which allows client applications to use GL rendering paths. Derived from the gyp variable `gl_type` gl_type which indicates what kind of GL implementation is available. -### SB_HAS_QUIRK(SB_FEATURE) ### +### SB_HAS_QUIRK(SB_FEATURE) Determines at compile-time whether this platform has a quirk. -### SB_INT64_C(x) ### +### SB_INT64_C(x) Declare numeric literals of signed 64-bit type. -### SB_IS(SB_FEATURE) ### +### SB_IS(SB_FEATURE) Determines at compile-time an inherent aspect of this platform. -### SB_LIKELY(x) ### +### SB_LIKELY(x) Macro for hinting that an expression is likely to be true. -### SB_MAXIMUM_API_VERSION ### +### SB_MAXIMUM_API_VERSION The maximum API version allowed by this version of the Starboard headers, inclusive. -### SB_MINIMUM_API_VERSION ### +### SB_MINIMUM_API_VERSION The minimum API version allowed by this version of the Starboard headers, inclusive. -### SB_NORETURN ### +### SB_NORETURN Macro to annotate a function as noreturn, which signals to the compiler that the function cannot return. -### SB_OVERRIDE ### +### SB_OVERRIDE Declares a function as overriding a virtual function on compilers that support it. -### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA ### +### SB_PREFERRED_RGBA_BYTE_ORDER_RGBA An enumeration of values for the kSbPreferredByteOrder configuration variable. Setting this up properly means avoiding slow color swizzles when passing pixel data from one library to another. Note that these definitions are in byte-order and so are endianness-independent. -### SB_PRINTF_FORMAT(format_param, dots_param) ### +### SB_PRINTF_FORMAT(format_param, dots_param) Tells the compiler a function is using a printf-style format string. `format_param` is the one-based index of the format string parameter; @@ -132,7 +132,7 @@ functions (which take a va_list), pass 0 for dots_param. (This is undocumented but matches what the system C headers do.) (Partially taken from base/compiler_specific.h) -### SB_RESTRICT ### +### SB_RESTRICT 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 @@ -140,29 +140,29 @@ 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. -### SB_SIZE_OF(DATATYPE) ### +### SB_SIZE_OF(DATATYPE) Determines at compile-time the size of a data type, or 0 if the data type that was specified was invalid. -### SB_STRINGIFY(x) ### +### SB_STRINGIFY(x) Standard CPP trick to stringify an evaluated macro definition. -### SB_UINT64_C(x) ### +### SB_UINT64_C(x) Declare numeric literals of unsigned 64-bit type. -### SB_UNLIKELY(x) ### +### SB_UNLIKELY(x) Macro for hinting that an expression is likely to be false. -### SB_UNREFERENCED_PARAMETER(x) ### +### SB_UNREFERENCED_PARAMETER(x) Trivially references a parameter that is otherwise unreferenced, preventing a compiler warning on some platforms. -### SB_WARN_UNUSED_RESULT ### +### SB_WARN_UNUSED_RESULT Causes the annotated (at the end) function to generate a warning if the result is not accessed. diff --git a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md index 99d92f822809..18af4bc2945c 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md @@ -1,113 +1,113 @@ ---- -layout: doc -title: "Starboard Module Reference: configuration_constants.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `configuration_constants.h` Declares all configuration variables we will need to use at runtime. These variables describe the current platform in detail to allow cobalt to make runtime decisions based on per platform configurations. -## Variables ## +## Variables -### kSbDefaultMmapThreshold ### +### kSbDefaultMmapThreshold Determines the threshold of allocation size that should be done with mmap (if available), rather than allocated within the core heap. -### kSbFileAltSepChar ### +### kSbFileAltSepChar The current platform's alternate file path component separator character. This is like SB_FILE_SEP_CHAR, except if your platform supports an alternate character, then you can place that here. For example, on windows machines, the primary separator character is probably '\', but the alternate is '/'. -### kSbFileAltSepString ### +### kSbFileAltSepString The string form of SB_FILE_ALT_SEP_CHAR. -### kSbFileMaxName ### +### kSbFileMaxName The current platform's maximum length of the name of a single directory entry, not including the absolute path. -### kSbFileMaxOpen ### +### kSbFileMaxOpen The current platform's maximum number of files that can be opened at the same time by one process. -### kSbFileMaxPath ### +### kSbFileMaxPath The current platform's maximum length of an absolute path. -### kSbFileSepChar ### +### kSbFileSepChar The current platform's file path component separator character. This is the character that appears after a directory in a file path. For example, the absolute canonical path of the file "/path/to/a/file.txt" uses '/' as a path component separator character. -### kSbFileSepString ### +### kSbFileSepString The string form of SB_FILE_SEP_CHAR. -### kSbHasMediaWebmVp9Support ### +### kSbHasMediaWebmVp9Support Specifies whether this platform has webm/vp9 support. This should be set to non- zero on platforms with webm/vp9 support. -### kSbHasThreadPrioritySupport ### +### kSbHasThreadPrioritySupport Whether the current platform supports thread priorities. -### kSbMallocAlignment ### +### kSbMallocAlignment Determines the alignment that allocations should have on this platform. -### kSbMaxSystemPathCacheDirectorySize ### +### kSbMaxSystemPathCacheDirectorySize The maximum size the cache directory is allowed to use in bytes. -### kSbMaxThreadLocalKeys ### +### kSbMaxThreadLocalKeys The maximum number of thread local storage keys supported by this platform. This comes from _POSIX_THREAD_KEYS_MAX. The value of PTHREAD_KEYS_MAX is higher, but unit tests show that the implementation doesn't support nearly as many keys. -### kSbMaxThreadNameLength ### +### kSbMaxThreadNameLength The maximum length of the name for a thread, including the NULL-terminator. -### kSbMaxThreads ### +### kSbMaxThreads Defines the maximum number of simultaneous threads for this platform. Some platforms require sharing thread handles with other kinds of system handles, like mutexes, so we want to keep this manageable. -### kSbMediaMaxAudioBitrateInBitsPerSecond ### +### kSbMediaMaxAudioBitrateInBitsPerSecond The maximum audio bitrate the platform can decode. The following value equals to 5M bytes per seconds which is more than enough for compressed audio. -### kSbMediaMaxVideoBitrateInBitsPerSecond ### +### kSbMediaMaxVideoBitrateInBitsPerSecond The maximum video bitrate the platform can decode. The following value equals to 8M bytes per seconds which is more than enough for compressed video. -### kSbMediaVideoFrameAlignment ### +### kSbMediaVideoFrameAlignment Specifies how video frame buffers must be aligned on this platform. -### kSbMemoryLogPath ### +### kSbMemoryLogPath Defines the path where memory debugging logs should be written to. -### kSbMemoryPageSize ### +### kSbMemoryPageSize The memory page size, which controls the size of chunks on memory that allocators deal with, and the alignment of those chunks. This doesn't have to be the hardware-defined physical page size, but it should be a multiple of it. -### kSbNetworkReceiveBufferSize ### +### kSbNetworkReceiveBufferSize Specifies the network receive buffer size in bytes, set via SbSocketSetReceiveBufferSize(). @@ -122,7 +122,7 @@ affect throughput in the presence of latency. If your platform does not have a good TCP auto-tuning mechanism, a setting of (128 * 1024) here is recommended. -### kSbPathSepChar ### +### kSbPathSepChar The current platform's search path component separator character. When specifying an ordered list of absolute paths of directories to search for a @@ -130,16 +130,16 @@ given reason, this is the character that appears between entries. For example, the search path of "/etc/search/first:/etc/search/second" uses ':' as a search path component separator character. -### kSbPathSepString ### +### kSbPathSepString The string form of SB_PATH_SEP_CHAR. -### kSbPreferredRgbaByteOrder ### +### kSbPreferredRgbaByteOrder Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. -### kSbUserMaxSignedIn ### +### kSbUserMaxSignedIn The maximum number of users that can be signed in at the same time. diff --git a/cobalt/site/docs/reference/starboard/modules/cpu_features.md b/cobalt/site/docs/reference/starboard/modules/cpu_features.md index ee12e715e78f..f5287bf7f5e2 100644 --- a/cobalt/site/docs/reference/starboard/modules/cpu_features.md +++ b/cobalt/site/docs/reference/starboard/modules/cpu_features.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: cpu_features.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml -## Structs ## +# Starboard Module Reference: `cpu_features.h` -### SbCPUFeatures ### +## Structs -#### Members #### +### SbCPUFeatures + +#### Members * `SbCPUFeaturesArchitecture architecture` @@ -54,9 +54,9 @@ title: "Starboard Module Reference: cpu_features.h" defined as a macro. * `SbCPUFeaturesX86 x86` -### SbCPUFeaturesARM ### +### SbCPUFeaturesARM -#### Members #### +#### Members * `int16_t implementer` @@ -98,7 +98,7 @@ title: "Starboard Module Reference: cpu_features.h" SDIV and UDIV hardware division in ARM mode. * `bool has_aes` - ###### Arm 64 feature flags ###### + ###### Arm 64 feature flags AES instructions. * `bool has_crc32` @@ -114,17 +114,17 @@ title: "Starboard Module Reference: cpu_features.h" 64-bit PMULL and PMULL2 instructions. -### SbCPUFeaturesMIPS ### +### SbCPUFeaturesMIPS -#### Members #### +#### Members * `bool has_msa` MIPS SIMD Architecture (MSA). -### SbCPUFeaturesX86 ### +### SbCPUFeaturesX86 -#### Members #### +#### Members * `const char * vendor` @@ -244,9 +244,9 @@ title: "Starboard Module Reference: cpu_features.h" SAHF in long mode. -## Functions ## +## Functions -### SbCPUFeaturesGet ### +### SbCPUFeaturesGet Retrieve the underlying CPU features and place it in `features`, which must not be NULL. @@ -254,7 +254,7 @@ be NULL. If this function returns false, it means the CPU architecture is unknown and all fields in `features` are invalid. -#### Declaration #### +#### Declaration ``` 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 a237ad98c81b..1e98db5db54d 100644 --- a/cobalt/site/docs/reference/starboard/modules/decode_target.md +++ b/cobalt/site/docs/reference/starboard/modules/decode_target.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: decode_target.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `decode_target.h` A target for decoding image and video data into. This corresponds roughly to an EGLImage, but that extension may not be fully supported on all GL platforms. @@ -12,7 +12,7 @@ data. This allows the application to allocate fast graphics memory, and have decoding done directly into this memory, avoiding unnecessary memory copies, and also avoiding pushing data between CPU and GPU memory unnecessarily. -## SbDecodeTargetFormat ## +## SbDecodeTargetFormat SbDecodeTargets support several different formats that can be used to decode into and render from. Some formats may be easier to decode into, and others may @@ -21,7 +21,7 @@ the SbDecodeTargetFormat passed into it, or the decode will produce an error. Each decoder provides a way to check if a given SbDecodeTargetFormat is supported by that decoder. -## SbDecodeTargetGraphicsContextProvider ## +## SbDecodeTargetGraphicsContextProvider Some components may need to acquire SbDecodeTargets compatible with a certain rendering context, which may need to be created on a particular thread. The @@ -36,7 +36,7 @@ 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 ## +## 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. @@ -79,15 +79,15 @@ GLuint texture = info.planes[kSbDecodeTargetPlaneRGBA].texture; ``` -## Macros ## +## Macros -### kSbDecodeTargetInvalid ### +### kSbDecodeTargetInvalid Well-defined value for an invalid decode target handle. -## Enums ## +## Enums -### SbDecodeTargetFormat ### +### SbDecodeTargetFormat The list of all possible decoder target formats. An SbDecodeTarget consists of one or more planes of data, each plane corresponding with a surface. For some @@ -96,7 +96,7 @@ formats, different planes will be different sizes for the same dimensions. NOTE: For enumeration entries with an alpha component, the alpha will always be premultiplied unless otherwise explicitly specified. -#### Values #### +#### Values * `kSbDecodeTargetFormat1PlaneRGBA` @@ -137,11 +137,11 @@ premultiplied unless otherwise explicitly specified. An invalid decode target format. -### SbDecodeTargetPlane ### +### SbDecodeTargetPlane All the planes supported by SbDecodeTarget. -#### Values #### +#### Values * `kSbDecodeTargetPlaneRGBA` @@ -162,45 +162,45 @@ All the planes supported by SbDecodeTarget. The V plane for 3-plane YUV formats. -## Typedefs ## +## Typedefs -### SbDecodeTarget ### +### SbDecodeTarget A handle to a target for image data decoding. -#### Definition #### +#### Definition ``` typedef SbDecodeTargetPrivate* SbDecodeTarget ``` -### SbDecodeTargetGlesContextRunner ### +### SbDecodeTargetGlesContextRunner Signature for a function provided by the application to the Starboard implementation that will let the Starboard implementation run arbitrary code on the application's renderer thread with the application's EGLContext held current. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunner) (struct SbDecodeTargetGraphicsContextProvider *graphics_context_provider, SbDecodeTargetGlesContextRunnerTarget target_function, void *target_function_context) ``` -### SbDecodeTargetGlesContextRunnerTarget ### +### SbDecodeTargetGlesContextRunnerTarget Signature for a Starboard implementation function that is to be run by a SbDecodeTargetGlesContextRunner callback. -#### Definition #### +#### Definition ``` typedef void(* SbDecodeTargetGlesContextRunnerTarget) (void *gles_context_runner_target_context) ``` -## Structs ## +## Structs -### SbDecodeTargetGraphicsContextProvider ### +### SbDecodeTargetGraphicsContextProvider In general, the SbDecodeTargetGraphicsContextProvider structure provides information about the graphics context that will be used to render @@ -210,7 +210,7 @@ References to SbDecodeTargetGraphicsContextProvider objects should be provided to all Starboard functions that might create SbDecodeTargets (e.g. SbImageDecode()). -#### Members #### +#### Members * `void * egl_display` @@ -233,12 +233,12 @@ SbImageDecode()). Context data that is to be passed in to `gles_context_runner` when it is invoked. -### SbDecodeTargetInfo ### +### SbDecodeTargetInfo Contains all information about a decode target, including all of its planes. This can be queried via calls to SbDecodeTargetGetInfo(). -#### Members #### +#### Members * `SbDecodeTargetFormat format` @@ -267,11 +267,11 @@ This can be queried via calls to SbDecodeTargetGetInfo(). kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this decode target. -### SbDecodeTargetInfoContentRegion ### +### SbDecodeTargetInfoContentRegion Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. -#### Members #### +#### Members * `float left` @@ -283,11 +283,11 @@ Defines a rectangular content region within a SbDecodeTargetInfoPlane structure. * `float right` * `float bottom` -### SbDecodeTargetInfoPlane ### +### SbDecodeTargetInfoPlane Defines an image plane within a SbDecodeTargetInfo object. -#### Members #### +#### Members * `uint32_t texture` @@ -317,53 +317,53 @@ Defines an image plane within a SbDecodeTargetInfo object. these parameters are number of pixels. The range for left/right is [0, width], and for top/bottom it is [0, height]. -## Functions ## +## Functions -### PrivateDecodeTargetReleaser ### +### PrivateDecodeTargetReleaser This function is just an implementation detail of SbDecodeTargetReleaseInGlesContext() and should not be called directly. -#### Declaration #### +#### Declaration ``` static void PrivateDecodeTargetReleaser(void *context) ``` -### SbDecodeTargetGetInfo ### +### SbDecodeTargetGetInfo Writes all information about `decode_target` into `out_info`. The `decode_target` must not be kSbDecodeTargetInvalid. The `out_info` pointer must not be NULL. Returns false if the provided `out_info` structure is not zero initialized. -#### Declaration #### +#### Declaration ``` bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target, SbDecodeTargetInfo *out_info) ``` -### SbDecodeTargetIsFormatValid ### +### SbDecodeTargetIsFormatValid Returns whether a given format is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsFormatValid(SbDecodeTargetFormat format) ``` -### SbDecodeTargetIsValid ### +### SbDecodeTargetIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDecodeTargetIsValid(SbDecodeTarget handle) ``` -### SbDecodeTargetRelease ### +### SbDecodeTargetRelease Returns ownership of `decode_target` to the Starboard implementation. This function will likely result in the destruction of the SbDecodeTarget and all its @@ -371,31 +371,31 @@ 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 -#### Declaration #### +#### Declaration ``` void SbDecodeTargetRelease(SbDecodeTarget decode_target) ``` -### SbDecodeTargetReleaseInGlesContext ### +### SbDecodeTargetReleaseInGlesContext Helper function that is possibly useful to Starboard implementations that will release a decode target on the thread with the GLES context current. -#### Declaration #### +#### Declaration ``` static void SbDecodeTargetReleaseInGlesContext(SbDecodeTargetGraphicsContextProvider *provider, SbDecodeTarget decode_target) ``` -### SbDecodeTargetRunInGlesContext ### +### SbDecodeTargetRunInGlesContext Inline convenience function to run an arbitrary SbDecodeTargetGlesContextRunnerTarget function through a SbDecodeTargetGraphicsContextProvider . This is intended to be called by Starboard implementations, if it is necessary. -#### Declaration #### +#### Declaration ``` 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 d46c9a194b02..1c0f90482119 100644 --- a/cobalt/site/docs/reference/starboard/modules/directory.md +++ b/cobalt/site/docs/reference/starboard/modules/directory.md @@ -1,56 +1,56 @@ ---- -layout: doc -title: "Starboard Module Reference: directory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `directory.h` Provides directory listing functions. -## Macros ## +## Macros -### kSbDirectoryInvalid ### +### kSbDirectoryInvalid Well-defined value for an invalid directory stream handle. -## Typedefs ## +## Typedefs -### SbDirectory ### +### SbDirectory A handle to an open directory stream. -#### Definition #### +#### Definition ``` typedef struct SbDirectoryPrivate* SbDirectory ``` -## Functions ## +## Functions -### SbDirectoryCanOpen ### +### SbDirectoryCanOpen Indicates whether SbDirectoryOpen is allowed for the given `path`. `path`: The path to be checked. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCanOpen(const char *path) ``` -### SbDirectoryClose ### +### SbDirectoryClose Closes an open directory stream handle. The return value indicates whether the directory was closed successfully. `directory`: The directory stream handle to close. -#### Declaration #### +#### Declaration ``` bool SbDirectoryClose(SbDirectory directory) ``` -### SbDirectoryCreate ### +### SbDirectoryCreate Creates the directory `path`, assuming the parent directory already exists. This function returns `true` if the directory now exists (even if it existed before) @@ -58,13 +58,13 @@ and returns `false` if the directory does not exist. `path`: The path to be created. -#### Declaration #### +#### Declaration ``` bool SbDirectoryCreate(const char *path) ``` -### SbDirectoryGetNext ### +### SbDirectoryGetNext Populates `out_entry` with the next entry in the specified directory stream, and moves the stream forward by one entry. @@ -83,23 +83,23 @@ entry. The space allocated for this string should be equal to `out_entry_size`. `out_entry_size`: The size of the space allocated for `out_entry`. This should be at least equal to kSbFileMaxName. -#### Declaration #### +#### Declaration ``` bool SbDirectoryGetNext(SbDirectory directory, char *out_entry, size_t out_entry_size) ``` -### SbDirectoryIsValid ### +### SbDirectoryIsValid Returns whether the given directory stream handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbDirectoryIsValid(SbDirectory directory) ``` -### SbDirectoryOpen ### +### SbDirectoryOpen Opens the given existing directory for listing. This function returns kSbDirectoryInvalidHandle if it is not successful. @@ -110,7 +110,7 @@ SbFileError code on failure. `out_error`: An output parameter that, in case of an error, is set to the reason that the directory could not be opened. -#### Declaration #### +#### Declaration ``` 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 fbb92f9ec841..f42e43bf3db7 100644 --- a/cobalt/site/docs/reference/starboard/modules/drm.md +++ b/cobalt/site/docs/reference/starboard/modules/drm.md @@ -1,37 +1,37 @@ ---- -layout: doc -title: "Starboard Module Reference: drm.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `drm.h` Provides definitions that allow for DRM support, which are common between Player and Decoder interfaces. -## Macros ## +## Macros -### kSbDrmSystemInvalid ### +### kSbDrmSystemInvalid An invalid SbDrmSystem. -### kSbDrmTicketInvalid ### +### kSbDrmTicketInvalid A ticket for callback invocations initiated by the DRM system. -## Enums ## +## Enums -### SbDrmEncryptionScheme ### +### SbDrmEncryptionScheme Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7. -#### Values #### +#### Values * `kSbDrmEncryptionSchemeAesCtr` * `kSbDrmEncryptionSchemeAesCbc` -### SbDrmKeyStatus ### +### SbDrmKeyStatus Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus) -#### Values #### +#### Values * `kSbDrmKeyStatusUsable` * `kSbDrmKeyStatusExpired` @@ -41,24 +41,24 @@ Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-de * `kSbDrmKeyStatusPending` * `kSbDrmKeyStatusError` -### SbDrmSessionRequestType ### +### SbDrmSessionRequestType The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype) -#### Values #### +#### Values * `kSbDrmSessionRequestTypeLicenseRequest` * `kSbDrmSessionRequestTypeLicenseRenewal` * `kSbDrmSessionRequestTypeLicenseRelease` * `kSbDrmSessionRequestTypeIndividualizationRequest` -### SbDrmStatus ### +### SbDrmStatus The status of session related operations. Used by `SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and `SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names) -#### Values #### +#### Values * `kSbDrmStatusSuccess` * `kSbDrmStatusTypeError` @@ -70,42 +70,42 @@ The status of session related operations. Used by The following error can be used when the error status cannot be mapped to one of the above errors. -## Typedefs ## +## Typedefs -### SbDrmServerCertificateUpdatedFunc ### +### SbDrmServerCertificateUpdatedFunc A callback to notify the caller of SbDrmUpdateServerCertificate() whether the update has been successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message) ``` -### SbDrmSessionClosedFunc ### +### SbDrmSessionClosedFunc A callback for signalling that a session has been closed by the SbDrmSystem -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size) ``` -### SbDrmSessionKeyStatusesChangedFunc ### +### SbDrmSessionKeyStatusesChangedFunc A callback for notifications that the status of one or more keys in a session has been changed. All keys of the session and their new status will be passed along. Any keys not in the list is considered as deleted. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses) ``` -### SbDrmSessionUpdateRequestFunc ### +### SbDrmSessionUpdateRequestFunc A callback that will receive generated session update request when requested from a SbDrmSystem. `drm_system` will be the DRM system that @@ -128,13 +128,13 @@ there was an error generating the request. This allows Cobalt to find and reject the correct Promise corresponding to the associated SbDrmGenerateSessionUpdateRequest(). -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url) ``` -### SbDrmSessionUpdatedFunc ### +### SbDrmSessionUpdatedFunc A callback for notifications that a session has been added, and subsequent encrypted samples are actively ready to be decoded. `drm_system` will be the DRM @@ -150,37 +150,37 @@ context passed into that call to SbDrmCreateSystem(). `status` is `kSbDrmStatusSuccess` or if no error message can be provided. `succeeded` is whether the session was successfully updated or not. -#### Definition #### +#### Definition ``` typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size) ``` -### SbDrmSystem ### +### SbDrmSystem A handle to a DRM system which can be used with either an SbDecoder or an SbPlayer. -#### Definition #### +#### Definition ``` typedef struct SbDrmSystemPrivate* SbDrmSystem ``` -## Structs ## +## Structs -### SbDrmEncryptionPattern ### +### SbDrmEncryptionPattern Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. -#### Members #### +#### Members * `uint32_t crypt_byte_block` * `uint32_t skip_byte_block` -### SbDrmKeyId ### +### SbDrmKeyId -#### Members #### +#### Members * `uint8_t identifier` @@ -188,11 +188,11 @@ Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7. PlayReady, this is the license GUID in packed little-endian binary form. * `int identifier_size` -### SbDrmSampleInfo ### +### SbDrmSampleInfo All the optional information needed per sample for encrypted samples. -#### Members #### +#### Members * `SbDrmEncryptionScheme encryption_scheme` @@ -217,13 +217,13 @@ All the optional information needed per sample for encrypted samples. The clear/encrypted mapping of each subsample in this sample. This must be an array of `subsample_count` mappings. -### SbDrmSubSampleMapping ### +### SbDrmSubSampleMapping A mapping of clear and encrypted bytes for a single subsample. All subsamples within a sample must be encrypted with the same encryption parameters. The clear bytes always appear first in the sample. -#### Members #### +#### Members * `int32_t clear_byte_count` @@ -232,21 +232,21 @@ bytes always appear first in the sample. How many bytes of the corresponding subsample are encrypted. -## Functions ## +## Functions -### SbDrmCloseSession ### +### SbDrmCloseSession Clear any internal states/resources related to the specified `session_id`. `drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size) ``` -### SbDrmDestroySystem ### +### SbDrmDestroySystem Destroys `drm_system`, which implicitly removes all keys installed in it and invalidates all outstanding session update requests. A DRM system cannot be @@ -258,13 +258,13 @@ SbDrmCreateSystem(), a deadlock will occur. `drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` void SbDrmDestroySystem(SbDrmSystem drm_system) ``` -### SbDrmGenerateSessionUpdateRequest ### +### SbDrmGenerateSessionUpdateRequest Asynchronously generates a session update request payload for `initialization_data`, of `initialization_data_size`, in case sensitive `type`, @@ -296,13 +296,13 @@ be NULL. `initialization_data`: The data for which the session update request payload is created. Must not be NULL. `initialization_data_size`: The size of the session update request payload. -#### Declaration #### +#### Declaration ``` void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size) ``` -### SbDrmGetMetrics ### +### SbDrmGetMetrics Get the metrics of the underlying drm system. @@ -326,13 +326,13 @@ system, or when the drm system implementation fails to retrieve the metrics. `drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL. -#### Declaration #### +#### Declaration ``` const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size) ``` -### SbDrmIsServerCertificateUpdatable ### +### SbDrmIsServerCertificateUpdatable Returns true if server certificate of `drm_system` can be updated via SbDrmUpdateServerCertificate(). The return value should remain the same during @@ -341,33 +341,33 @@ the life time of `drm_system`. `drm_system`: The DRM system to check if its server certificate is updatable. Must not be `kSbDrmSystemInvalid`. -#### Declaration #### +#### Declaration ``` bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system) ``` -### SbDrmSystemIsValid ### +### SbDrmSystemIsValid Indicates whether `drm_system` is a valid SbDrmSystem. -#### Declaration #### +#### Declaration ``` static bool SbDrmSystemIsValid(SbDrmSystem drm) ``` -### SbDrmTicketIsValid ### +### SbDrmTicketIsValid Indicates whether `ticket` is a valid ticket. -#### Declaration #### +#### Declaration ``` static bool SbDrmTicketIsValid(int ticket) ``` -### SbDrmUpdateServerCertificate ### +### SbDrmUpdateServerCertificate Update the server certificate of `drm_system`. The function can be called multiple times. It is possible that a call to it happens before the callback of @@ -384,13 +384,13 @@ requests with the same ticket may result in undefined behavior. The value certificate data. Must not be NULL. `certificate_size`: Size of the server certificate data. -#### Declaration #### +#### Declaration ``` void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size) ``` -### SbDrmUpdateSession ### +### SbDrmUpdateSession Update session with `key`, in `drm_system`'s key system, from the license server response. Calls `session_updated_callback` with `context` and whether the update @@ -410,7 +410,7 @@ with that DRM key system will be able to decrypt encrypted samples. thread before this function returns or from another thread. The `session_id` must not be NULL. -#### Declaration #### +#### Declaration ``` 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 b1e120b2e5ea..87deff271ad9 100644 --- a/cobalt/site/docs/reference/starboard/modules/egl.md +++ b/cobalt/site/docs/reference/starboard/modules/egl.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: egl.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `egl.h` The EGL API provides an interface with accompanying type declarations and defines that together provide a single consistent method of EGL usage across @@ -11,67 +11,67 @@ 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 functions from EGL 1.5 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_EGL_ALPHA_FORMAT ### +### SB_EGL_ALPHA_FORMAT EGL_VERSION_1_2 -### SB_EGL_ALPHA_SIZE ### +### SB_EGL_ALPHA_SIZE EGL_VERSION_1_0 -### SB_EGL_BACK_BUFFER ### +### SB_EGL_BACK_BUFFER EGL_VERSION_1_1 -### SB_EGL_CONFORMANT ### +### SB_EGL_CONFORMANT EGL_VERSION_1_3 -### SB_EGL_CONTEXT_MAJOR_VERSION ### +### SB_EGL_CONTEXT_MAJOR_VERSION EGL_VERSION_1_5 -### SB_EGL_DEFAULT_DISPLAY ### +### SB_EGL_DEFAULT_DISPLAY EGL_VERSION_1_4 -## Typedefs ## +## Typedefs -### SbEglCastsToProperFunctionPointerType ### +### SbEglCastsToProperFunctionPointerType The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/egl.h](https://www.khronos.org/registry/EGL/api/EGL/egl.h) . -#### Definition #### +#### Definition ``` typedef void(* SbEglCastsToProperFunctionPointerType) (void) ``` -### SbEglInt32 ### +### SbEglInt32 The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h](https://www.khronos.org/registry/EGL/api/EGL/eglplatform.h) . -#### Definition #### +#### Definition ``` typedef int32_t SbEglInt32 ``` -## Structs ## +## Structs -### SbEglInterface ### +### SbEglInterface -#### Members #### +#### Members * `SbEglBoolean(*eglChooseConfig)(SbEglDisplay dpy, const SbEglInt32 *attrib_list, SbEglConfig *configs, SbEglInt32 config_size, SbEglInt32 diff --git a/cobalt/site/docs/reference/starboard/modules/event.md b/cobalt/site/docs/reference/starboard/modules/event.md index 58cb1f4d1390..d8bab06a5538 100644 --- a/cobalt/site/docs/reference/starboard/modules/event.md +++ b/cobalt/site/docs/reference/starboard/modules/event.md @@ -1,11 +1,11 @@ ---- -layout: doc -title: "Starboard Module Reference: event.h" ---- +Project: /youtube/cobalt/_project.yaml +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 ``` * ---------- @@ -78,15 +78,15 @@ for a more graceful shutdown. Note that the application is always expected to transition through `BLURRED`, `CONCEALED` to `FROZEN` before receiving `Stop` or being killed. -## Enums ## +## Enums -### SbEventType ### +### SbEventType An enumeration of all possible event types dispatched directly by the system. Each event is accompanied by a void* data argument, and each event must define the type of the value pointed to by that data argument, if any. -#### Values #### +#### Values * `kSbEventTypePreload` @@ -273,55 +273,55 @@ the type of the value pointed to by that data argument, if any. change in the timezone setting). This should trigger the application to re- query the relevant APIs to update the date and time. -## Typedefs ## +## Typedefs -### SbEventCallback ### +### SbEventCallback A function that can be called back from the main Starboard event pump. -#### Definition #### +#### Definition ``` typedef void(* SbEventCallback) (void *context) ``` -### SbEventDataDestructor ### +### SbEventDataDestructor A function that will cleanly destroy an event data instance of a specific type. -#### Definition #### +#### Definition ``` typedef void(* SbEventDataDestructor) (void *data) ``` -### SbEventId ### +### SbEventId An ID that can be used to refer to a scheduled event. -#### Definition #### +#### Definition ``` typedef uint32_t SbEventId ``` -## Structs ## +## Structs -### SbEvent ### +### SbEvent Structure representing a Starboard event and its data. -#### Members #### +#### Members * `SbEventType type` * `SbTimeMonotonic timestamp` * `void * data` -### SbEventStartData ### +### SbEventStartData Event data for kSbEventTypeStart events. -#### Members #### +#### Members * `char ** argument_values` @@ -333,31 +333,31 @@ Event data for kSbEventTypeStart events. The startup link, if any. -### SbEventWindowSizeChangedData ### +### SbEventWindowSizeChangedData Event data for kSbEventTypeWindowSizeChanged events. -#### Members #### +#### Members * `SbWindow window` * `SbWindowSize size` -## Functions ## +## Functions -### SbEventCancel ### +### SbEventCancel Cancels the specified `event_id`. Note that this function is a no-op if the event already fired. This function can be safely called from any thread, but the only way to guarantee that the event does not run anyway is to call it from the main Starboard event loop thread. -#### Declaration #### +#### Declaration ``` void SbEventCancel(SbEventId event_id) ``` -### SbEventHandle ### +### SbEventHandle The entry point that Starboard applications MUST implement. Any memory pointed at by `event` or the `data` field inside `event` is owned by the system, and @@ -370,23 +370,23 @@ specification about what other work might happen on this thread, so the application should generally do as little work as possible on this thread, and just dispatch it over to another thread. -#### Declaration #### +#### Declaration ``` SB_EXPORT_PLATFORM void SbEventHandle(const SbEvent *event) ``` -### SbEventIsIdValid ### +### SbEventIsIdValid Returns whether the given event handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbEventIsIdValid(SbEventId handle) ``` -### SbEventSchedule ### +### SbEventSchedule Schedules an event `callback` into the main Starboard event loop. This function may be called from any thread, but `callback` is always called from the main @@ -397,18 +397,18 @@ context that is passed to the `callback` function. `delay`: The minimum number of microseconds to wait before calling the `callback` function. Set `delay` to `0` to call the callback as soon as possible. -#### Declaration #### +#### Declaration ``` SbEventId SbEventSchedule(SbEventCallback callback, void *context, SbTime delay) ``` -### SbRunStarboardMain ### +### SbRunStarboardMain Serves as the entry point in the Starboard library for running the Starboard event loop with the application event handler. -#### Declaration #### +#### Declaration ``` int SbRunStarboardMain(int argc, char **argv, SbEventHandleCallback callback) diff --git a/cobalt/site/docs/reference/starboard/modules/export.md b/cobalt/site/docs/reference/starboard/modules/export.md index ff797770e824..a398d4ad0c85 100644 --- a/cobalt/site/docs/reference/starboard/modules/export.md +++ b/cobalt/site/docs/reference/starboard/modules/export.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: export.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `export.h` Provides macros for properly exporting or importing symbols from shared libraries. -## Macros ## +## Macros -### SB_EXPORT ### +### SB_EXPORT Specification for a symbol that should be exported when building the DLL and imported when building code that uses the DLL. -### SB_EXPORT_PRIVATE ### +### SB_EXPORT_PRIVATE Specification for a symbol that should be exported or imported for testing purposes only. -### SB_IMPORT ### +### SB_IMPORT Specification for a symbol that is expected to be defined externally to this module. diff --git a/cobalt/site/docs/reference/starboard/modules/file.md b/cobalt/site/docs/reference/starboard/modules/file.md index e22edeb51ee7..02c7863d8710 100644 --- a/cobalt/site/docs/reference/starboard/modules/file.md +++ b/cobalt/site/docs/reference/starboard/modules/file.md @@ -1,25 +1,25 @@ ---- -layout: doc -title: "Starboard Module Reference: file.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `file.h` Defines file system input/output functions. -## Macros ## +## Macros -### kSbFileInvalid ### +### kSbFileInvalid Well-defined value for an invalid file handle. -## Enums ## +## Enums -### SbFileError ### +### SbFileError kSbFileErrorAccessDenied is returned when a call fails because of a filesystem restriction. kSbFileErrorSecurity is returned when a security policy doesn't allow the operation to be executed. -#### Values #### +#### Values * `kSbFileOk` * `kSbFileErrorFailed` @@ -40,7 +40,7 @@ allow the operation to be executed. * `kSbFileErrorIO` * `kSbFileErrorMax` -### SbFileFlags ### +### SbFileFlags Flags that define how a file is used in the application. These flags should be or'd together when passed to SbFileOpen to open or create a file. @@ -66,7 +66,7 @@ In addition, one or more of the following flags must be specified: The `kSbFileAsync` flag is optional. -#### Values #### +#### Values * `kSbFileOpenOnly` * `kSbFileCreateOnly` @@ -85,35 +85,35 @@ The `kSbFileAsync` flag is optional. * `kSbFileWrite` * `kSbFileAsync` -### SbFileWhence ### +### SbFileWhence This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. -#### Values #### +#### Values * `kSbFileFromBegin` * `kSbFileFromCurrent` * `kSbFileFromEnd` -## Typedefs ## +## Typedefs -### SbFile ### +### SbFile A handle to an open file. -#### Definition #### +#### Definition ``` typedef SbFilePrivate* SbFile ``` -## Structs ## +## Structs -### SbFileInfo ### +### SbFileInfo Used to hold information about a file. -#### Members #### +#### Members * `int64_t size` @@ -134,9 +134,9 @@ Used to hold information about a file. The creation time of a file. -## Functions ## +## Functions -### SbFileAtomicReplace ### +### SbFileAtomicReplace Replaces the content of the file at `path` with `data`. Returns whether the contents of the file were replaced. The replacement of the content is an atomic @@ -146,39 +146,39 @@ operation. The file will either have all of the data, or none. to replace the file contents with. `data_size`: The amount of `data`, in bytes, to be written to the file. -#### Declaration #### +#### Declaration ``` bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size) ``` -### SbFileCanOpen ### +### SbFileCanOpen Indicates whether SbFileOpen() with the given `flags` is allowed for `path`. `path`: The absolute path to be checked. `flags`: The flags that are being evaluated for the given `path`. -#### Declaration #### +#### Declaration ``` bool SbFileCanOpen(const char *path, int flags) ``` -### SbFileClose ### +### SbFileClose Closes `file`. The return value indicates whether the file was closed successfully. `file`: The absolute path of the file to be closed. -#### Declaration #### +#### Declaration ``` bool SbFileClose(SbFile file) ``` -### SbFileDelete ### +### SbFileDelete Deletes the regular file, symlink, or empty directory at `path`. This function is used primarily to clean up after unit tests. On some platforms, this function @@ -186,38 +186,38 @@ fails if the file in question is being held open. `path`: The absolute path of the file, symlink, or directory to be deleted. -#### Declaration #### +#### Declaration ``` bool SbFileDelete(const char *path) ``` -### SbFileExists ### +### SbFileExists Indicates whether a file or directory exists at `path`. `path`: The absolute path of the file or directory being checked. -#### Declaration #### +#### Declaration ``` bool SbFileExists(const char *path) ``` -### SbFileFlush ### +### SbFileFlush Flushes the write buffer to `file`. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed. `file`: The SbFile to which the write buffer is flushed. -#### Declaration #### +#### Declaration ``` bool SbFileFlush(SbFile file) ``` -### SbFileGetInfo ### +### SbFileGetInfo Retrieves information about `file`. The return value indicates whether the file information was retrieved successfully. @@ -226,13 +226,13 @@ information was retrieved successfully. into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetInfo(SbFile file, SbFileInfo *out_info) ``` -### SbFileGetPathInfo ### +### SbFileGetPathInfo Retrieves information about the file at `path`. The return value indicates whether the file information was retrieved successfully. @@ -241,36 +241,36 @@ whether the file information was retrieved successfully. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. -#### Declaration #### +#### Declaration ``` bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info) ``` -### SbFileIsValid ### +### SbFileIsValid Returns whether the given file handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbFileIsValid(SbFile file) ``` -### SbFileModeStringToFlags ### +### SbFileModeStringToFlags Converts an ISO `fopen()` mode string into flags that can be equivalently passed into SbFileOpen(). `mode`: The mode string to be converted into flags. -#### Declaration #### +#### Declaration ``` int SbFileModeStringToFlags(const char *mode) ``` -### SbFileOpen ### +### SbFileOpen Opens the file at `path`, which must be absolute, creating it if specified by `flags`. The read/write position is at the beginning of the file. @@ -287,13 +287,13 @@ which can happen if the `kSbFileCreateAlways` flag is set. Otherwise, Starboard sets this value to `false`. `out_error`: If `path` cannot be created, this is set to `kSbFileInvalid`. Otherwise, it is `NULL`. -#### Declaration #### +#### Declaration ``` SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error) ``` -### SbFileRead ### +### SbFileRead Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -306,13 +306,13 @@ However, this function can be run in a loop to make it a best-effort read. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` int SbFileRead(SbFile file, char *data, int size) ``` -### SbFileReadAll ### +### SbFileReadAll Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. @@ -326,13 +326,13 @@ be read unless there is an error. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. -#### Declaration #### +#### Declaration ``` static int SbFileReadAll(SbFile file, char *data, int size) ``` -### SbFileSeek ### +### SbFileSeek Changes the current read/write position in `file`. The return value identifies the resultant current read/write position in the file (relative to the start) or @@ -344,13 +344,13 @@ The starting read/write position. The position is modified relative to this value. `offset`: The amount that the read/write position is changed, relative to `whence`. -#### Declaration #### +#### Declaration ``` int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset) ``` -### SbFileTruncate ### +### SbFileTruncate Truncates the given `file` to the given `length`. The return value indicates whether the file was truncated successfully. @@ -360,13 +360,13 @@ after it is truncated. If `length` is greater than the current size of the file, then the file is extended with zeros. If `length` is negative, then the function is a no-op and returns `false`. -#### Declaration #### +#### Declaration ``` bool SbFileTruncate(SbFile file, int64_t length) ``` -### SbFileWrite ### +### SbFileWrite Writes the given buffer into `file` at the file's current position, overwriting any data that was previously there. @@ -380,13 +380,13 @@ in a loop to ensure that all data is written. `file`: The SbFile to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` int SbFileWrite(SbFile file, const char *data, int size) ``` -### SbFileWriteAll ### +### SbFileWriteAll Writes the given buffer into `file`, starting at the beginning of the file, and overwriting any data that was previously there. Unlike SbFileWrite, this @@ -397,7 +397,7 @@ The return value identifies the number of bytes written, or `-1` on error. `file`: The file to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. -#### Declaration #### +#### Declaration ``` 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 7a9108a25280..049838f80b65 100644 --- a/cobalt/site/docs/reference/starboard/modules/gles.md +++ b/cobalt/site/docs/reference/starboard/modules/gles.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: gles.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `gles.h` The GLES API provides an interface with accompanying type declarations and defines that together provide a single consistent method of GLES usage across @@ -11,37 +11,37 @@ 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 the functions from GLES 3.0 they are calling from the interface are valid. -## Macros ## +## Macros -### SB_GL_DEPTH_BUFFER_BIT ### +### SB_GL_DEPTH_BUFFER_BIT Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) -### SB_GL_READ_BUFFER ### +### SB_GL_READ_BUFFER Previously defined in [https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h](https://www.khronos.org/registry/OpenGL/api/GLES3/gl3.h) . -## Typedefs ## +## Typedefs -### SbGlBoolean ### +### SbGlBoolean The following type definitions were adapted from the types declared in [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2.h) . -#### Definition #### +#### Definition ``` typedef uint8_t SbGlBoolean ``` -### SbGlIntPtr ### +### SbGlIntPtr Some compilers will transform the intptr_t to an int transparently behind the scenes, which is not equivalent to a long int, or long long int, as far as the @@ -49,17 +49,17 @@ compiler is concerned. We check the Starboard configuration and set the types to those exact types used by OpenGL ES 2.0 ( [https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h](https://www.khronos.org/registry/OpenGL/api/GLES2/gl2ext.h) ). -#### Definition #### +#### Definition ``` typedef long int SbGlIntPtr ``` -## Structs ## +## Structs -### SbGlesInterface ### +### SbGlesInterface -#### Members #### +#### Members * `void(*glActiveTexture)(SbGlEnum texture)` diff --git a/cobalt/site/docs/reference/starboard/modules/image.md b/cobalt/site/docs/reference/starboard/modules/image.md index 1427d3995d54..945938a09903 100644 --- a/cobalt/site/docs/reference/starboard/modules/image.md +++ b/cobalt/site/docs/reference/starboard/modules/image.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: image.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `image.h` API for hardware accelerated image decoding. This module allows for the client to feed in raw, encoded data to be decoded directly into an SbDecodeTarget. It @@ -11,7 +11,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(); @@ -28,9 +28,9 @@ SbDecodeTarget result_target = SbImageDecode(provider, data, data_size, mime_type, format); ``` -## Functions ## +## Functions -### SbImageDecode ### +### SbImageDecode Attempt to decode encoded `mime_type` image data `data` of size `data_size` into an SbDecodeTarget of SbDecodeFormatType `format`, possibly using @@ -56,13 +56,13 @@ scenarios regarding the provider may happen: kSbDecodeTargetInvalid will be returned, with any intermediate allocations being cleaned up in the implementation. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbImageDecode(SbDecodeTargetGraphicsContextProvider *context_provider, void *data, int data_size, const char *mime_type, SbDecodeTargetFormat format) ``` -### SbImageIsDecodeSupported ### +### SbImageIsDecodeSupported Whether the current platform supports hardware accelerated decoding an image of mime type `mime_type` into SbDecodeTargetFormat `format`. The `mime_type` must @@ -70,7 +70,7 @@ not be NULL. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. -#### Declaration #### +#### Declaration ``` bool SbImageIsDecodeSupported(const char *mime_type, SbDecodeTargetFormat format) diff --git a/cobalt/site/docs/reference/starboard/modules/input.md b/cobalt/site/docs/reference/starboard/modules/input.md index e8df816a4987..d2dd2db32dc5 100644 --- a/cobalt/site/docs/reference/starboard/modules/input.md +++ b/cobalt/site/docs/reference/starboard/modules/input.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: input.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `input.h` Defines input events and associated data types. -## Enums ## +## Enums -### SbInputDeviceType ### +### SbInputDeviceType Identifies possible input subsystem types. The types of events that each device type produces correspond to `SbInputEventType` values. -#### Values #### +#### Values * `kSbInputDeviceTypeGesture` @@ -57,11 +57,11 @@ type produces correspond to `SbInputEventType` values. Produces `Input` events. -### SbInputEventType ### +### SbInputEventType The action that an input event represents. -#### Values #### +#### Values * `kSbInputEventTypeMove` @@ -86,13 +86,13 @@ The action that an input event represents. [https://w3c.github.io/uievents/#event-type-input](https://w3c.github.io/uievents/#event-type-input) -## Structs ## +## Structs -### SbInputData ### +### SbInputData Event data for `kSbEventTypeInput` events. -#### Members #### +#### Members * `SbWindow window` @@ -160,11 +160,11 @@ Event data for `kSbEventTypeInput` events. Set to true if the input event is part of a composition event. -### SbInputVector ### +### SbInputVector A 2-dimensional vector used to represent points and motion vectors. -#### Members #### +#### Members * `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 2835b20d70d9..ed87e531f4fc 100644 --- a/cobalt/site/docs/reference/starboard/modules/key.md +++ b/cobalt/site/docs/reference/starboard/modules/key.md @@ -1,19 +1,19 @@ ---- -layout: doc -title: "Starboard Module Reference: key.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `key.h` Defines the canonical set of Starboard key codes. -## Enums ## +## Enums -### SbKey ### +### SbKey A standard set of key codes, ordered by value, that represent each possible input key across all kinds of devices. Starboard uses the semi-standard Windows virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx) -#### Values #### +#### Values * `kSbKeyUnknown` * `kSbKeyCancel` @@ -275,11 +275,11 @@ virtual key codes documented at: [https://msdn.microsoft.com/en-us/library/windo * `kSbKeyGamepadRightStickLeft` * `kSbKeyGamepadRightStickRight` -### SbKeyModifiers ### +### SbKeyModifiers Bit-mask of key modifiers. -#### Values #### +#### Values * `kSbKeyModifiersNone` * `kSbKeyModifiersAlt` diff --git a/cobalt/site/docs/reference/starboard/modules/log.md b/cobalt/site/docs/reference/starboard/modules/log.md index 42de5138c303..6cf3a491a2a7 100644 --- a/cobalt/site/docs/reference/starboard/modules/log.md +++ b/cobalt/site/docs/reference/starboard/modules/log.md @@ -1,18 +1,18 @@ ---- -layout: doc -title: "Starboard Module Reference: log.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `log.h` Defines core debug logging functions. -## Enums ## +## Enums -### SbLogPriority ### +### SbLogPriority The priority at which a message should be logged. The platform may be configured to filter logs by priority, or render them differently. -#### Values #### +#### Values * `kSbLogPriorityUnknown` * `kSbLogPriorityInfo` @@ -20,9 +20,9 @@ to filter logs by priority, or render them differently. * `kSbLogPriorityError` * `kSbLogPriorityFatal` -## Functions ## +## Functions -### SbLog ### +### SbLog Writes `message` to the platform's debug output log. This method is thread-safe, and responsible for ensuring that the output from multiple threads is not mixed. @@ -35,55 +35,55 @@ NULL. No formatting is required to be done on the value, including newline termination. That said, platforms can adjust the message to be more suitable for their output method by wrapping the text, stripping unprintable characters, etc. -#### Declaration #### +#### Declaration ``` void SbLog(SbLogPriority priority, const char *message) ``` -### SbLogFlush ### +### SbLogFlush Flushes the log buffer on some platforms. This method is safe to call from multiple threads. -#### Declaration #### +#### Declaration ``` void SbLogFlush() ``` -### SbLogFormat ### +### SbLogFormat A log output method that additionally performs a string format on the data being logged. -#### Declaration #### +#### Declaration ``` void SbLogFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogFormatF ### +### SbLogFormatF Inline wrapper of SbLogFormat that converts from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` void static void static void SbLogFormatF(const char *format,...) SB_PRINTF_FORMAT(1 ``` -### SbLogIsTty ### +### SbLogIsTty Indicates whether the log output goes to a TTY or is being redirected. -#### Declaration #### +#### Declaration ``` bool SbLogIsTty() ``` -### SbLogRaw ### +### SbLogRaw A bare-bones log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). It should not do any @@ -91,13 +91,13 @@ additional formatting. `message`: The message to be logged. Must not be NULL. -#### Declaration #### +#### Declaration ``` void SbLogRaw(const char *message) ``` -### SbLogRawDumpStack ### +### SbLogRawDumpStack Dumps the stack of the current thread to the log in an async-signal-safe manner, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` @@ -108,28 +108,28 @@ dumping the current thread to the log. This parameter lets you remove noise from helper functions that might end up on top of every stack dump so that the stack dump is just the relevant function stack where the problem occurred. -#### Declaration #### +#### Declaration ``` void SbLogRawDumpStack(int frames_to_skip) ``` -### SbLogRawFormat ### +### SbLogRawFormat A formatted log output method that is async-signal-safe, i.e. safe to call from an asynchronous signal handler (e.g. a `SIGSEGV` handler). -#### Declaration #### +#### Declaration ``` void SbLogRawFormat(const char *format, va_list args) SB_PRINTF_FORMAT(1 ``` -### SbLogRawFormatF ### +### SbLogRawFormatF Inline wrapper of SbLogFormat to convert from ellipsis to va_args. -#### Declaration #### +#### Declaration ``` 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 132166c69955..e1c2ae5318e9 100644 --- a/cobalt/site/docs/reference/starboard/modules/media.md +++ b/cobalt/site/docs/reference/starboard/modules/media.md @@ -1,28 +1,28 @@ ---- -layout: doc -title: "Starboard Module Reference: media.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `media.h` Provides media definitions that are common between the Decoder and Player interfaces. -## Macros ## +## Macros -### kSbMediaBitsPerPixelInvalid ### +### kSbMediaBitsPerPixelInvalid Value used when a video's bits per pixel is not known. -### kSbMediaVideoResolutionDimensionInvalid ### +### kSbMediaVideoResolutionDimensionInvalid Value used when a video's resolution is not known. -## Enums ## +## Enums -### SbMediaAudioCodec ### +### SbMediaAudioCodec Types of audio elementary streams that can be supported. -#### Values #### +#### Values * `kSbMediaAudioCodecNone` * `kSbMediaAudioCodecAac` @@ -35,11 +35,11 @@ Types of audio elementary streams that can be supported. * `kSbMediaAudioCodecPcm` * `kSbMediaAudioCodecIamf` -### SbMediaAudioCodingType ### +### SbMediaAudioCodingType Possible audio coding types. -#### Values #### +#### Values * `kSbMediaAudioCodingTypeNone` * `kSbMediaAudioCodingTypeAac` @@ -53,11 +53,11 @@ Possible audio coding types. * `kSbMediaAudioCodingTypeMpeg3` * `kSbMediaAudioCodingTypePcm` -### SbMediaAudioConnector ### +### SbMediaAudioConnector Possible audio connector types. -#### Values #### +#### Values * `kSbMediaAudioConnectorUnknown` * `kSbMediaAudioConnectorAnalog` @@ -76,11 +76,11 @@ Possible audio connector types. * `kSbMediaAudioConnectorSpdif` * `kSbMediaAudioConnectorUsb` -### SbMediaAudioFrameStorageType ### +### SbMediaAudioFrameStorageType Possible audio frame storage types. -#### Values #### +#### Values * `kSbMediaAudioFrameStorageTypeInterleaved` @@ -96,22 +96,22 @@ Possible audio frame storage types. with timestamps 0, 1, 2, etc., the samples are stored in two buffers "L0 L1 L2 ..." and "R0 R1 R2 ...". -### SbMediaAudioSampleType ### +### SbMediaAudioSampleType Possible audio sample types. -#### Values #### +#### Values * `kSbMediaAudioSampleTypeInt16Deprecated` * `kSbMediaAudioSampleTypeFloat32` -### SbMediaRangeId ### +### SbMediaRangeId This corresponds to the WebM Range enum which is part of WebM color data (see [http://www.webmproject.org/docs/container/#Range](http://www.webmproject.org/docs/container/#Range) ). H.264 only uses a bool, which corresponds to the LIMITED/FULL values. Chrome- specific values start at 1000. -#### Values #### +#### Values * `kSbMediaRangeIdUnspecified` @@ -127,13 +127,13 @@ specific values start at 1000. Range is defined by TransferId/MatrixId. * `kSbMediaRangeIdLast` -### SbMediaSupportType ### +### SbMediaSupportType Indicates how confident the device is that it can play media resources of the given type. The values are a direct map of the canPlayType() method specified at the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype](https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom-navigator-canplaytype) -#### Values #### +#### Values * `kSbMediaSupportTypeNotSupported` @@ -145,11 +145,11 @@ the following link: [https://www.w3.org/TR/2011/WD-html5-20110113/video.html#dom The media type seems to be playable. -### SbMediaType ### +### SbMediaType Types of media component streams. -#### Values #### +#### Values * `kSbMediaTypeAudio` @@ -158,11 +158,11 @@ Types of media component streams. Value used for video streams. -### SbMediaVideoCodec ### +### SbMediaVideoCodec Types of video elementary streams that could be supported. -#### Values #### +#### Values * `kSbMediaVideoCodecNone` * `kSbMediaVideoCodecH264` @@ -174,14 +174,14 @@ Types of video elementary streams that could be supported. * `kSbMediaVideoCodecVp8` * `kSbMediaVideoCodecVp9` -## Structs ## +## Structs -### SbMediaAudioConfiguration ### +### SbMediaAudioConfiguration A structure describing the audio configuration parameters of a single audio output. -#### Members #### +#### Members * `SbMediaAudioConnector connector` @@ -200,11 +200,11 @@ output. `0` if this device cannot provide this information, in which case the caller can probably assume stereo output. -### SbMediaAudioSampleInfo ### +### SbMediaAudioSampleInfo The set of information required by the decoder or player for each audio sample. -#### Members #### +#### Members * `SbMediaAudioStreamInfo stream_info` @@ -212,11 +212,11 @@ The set of information required by the decoder or player for each audio sample. * `SbTime discarded_duration_from_front` * `SbTime discarded_duration_from_back` -### SbMediaAudioStreamInfo ### +### SbMediaAudioStreamInfo The set of information required by the decoder or player for each audio stream. -#### Members #### +#### Members * `SbMediaAudioCodec codec` @@ -242,14 +242,14 @@ The set of information required by the decoder or player for each audio stream. The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1: [http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF](http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF) -### SbMediaColorMetadata ### +### SbMediaColorMetadata HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR formats, together with the ColorSpace. HDR reproduces a greater dynamic range of luminosity than is possible with standard digital imaging. See the Consumer Electronics Association press release: [https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx](https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx) -#### Members #### +#### Members * `unsigned int bits_per_channel` @@ -330,7 +330,7 @@ Electronics Association press release: [https://www.cta.tech/News/Press-Releases a row-major ordered 3 x 4 submatrix of the 4 x 4 transform matrix. The 4th row is completed as (0, 0, 0, 1). -### SbMediaMasteringMetadata ### +### SbMediaMasteringMetadata SMPTE 2086 mastering data [http://ieeexplore.ieee.org/document/7291707/](http://ieeexplore.ieee.org/document/7291707/) This standard specifies the metadata items to specify the color volume (the @@ -339,7 +339,7 @@ in mastering video content. The metadata is specified as a set of values independent of any specific digital representation. Also see the WebM container guidelines: [https://www.webmproject.org/docs/container/](https://www.webmproject.org/docs/container/) -#### Members #### +#### Members * `float primary_r_chromaticity_x` @@ -374,11 +374,11 @@ guidelines: [https://www.webmproject.org/docs/container/](https://www.webmprojec Minimum luminance. Shall be represented in candelas per square meter (cd/m^2). In range [0, 9999.99]. -### SbMediaVideoSampleInfo ### +### SbMediaVideoSampleInfo The set of information required by the decoder or player for each video sample. -#### Members #### +#### Members * `SbMediaVideoStreamInfo stream_info` @@ -388,11 +388,11 @@ The set of information required by the decoder or player for each video sample. Indicates whether the associated sample is a key frame (I-frame). Avc video key frames must always start with SPS and PPS NAL units. -### SbMediaVideoStreamInfo ### +### SbMediaVideoStreamInfo The set of information required by the decoder or player for each video stream. -#### Members #### +#### Members * `SbMediaVideoCodec codec` @@ -434,9 +434,9 @@ The set of information required by the decoder or player for each video stream. . This will only be specified on frames where the HDR metadata and color / color space might have changed (e.g. keyframes). -## Functions ## +## Functions -### SbMediaCanPlayMimeAndKeySystem ### +### SbMediaCanPlayMimeAndKeySystem Returns information about whether the playback of the specific media described by `mime` and encrypted using `key_system` can be played. @@ -480,13 +480,13 @@ return `kSbMediaSupportTypeProbably` kSbMediaSupportTypeProbably when implementation supports key system with attributes on one key system, it has to support key system with attributes on all key systems supported. -#### Declaration #### +#### Declaration ``` SbMediaSupportType SbMediaCanPlayMimeAndKeySystem(const char *mime, const char *key_system) ``` -### SbMediaGetAudioBufferBudget ### +### SbMediaGetAudioBufferBudget Specifies the maximum amount of memory used by audio buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -494,13 +494,13 @@ being used by audio buffers but will also make the app less likely to re- download audio data. Note that the app may experience significant difficulty if this value is too low. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioBufferBudget() ``` -### SbMediaGetAudioConfiguration ### +### SbMediaGetAudioConfiguration Retrieves the current physical audio configuration of audio output `output_index` on this device and places it in `out_configuration`, which must @@ -512,37 +512,37 @@ if `output_index` does not exist on this device. `out_configuration`: The variable that holds the audio configuration information. -#### Declaration #### +#### Declaration ``` bool SbMediaGetAudioConfiguration(int output_index, SbMediaAudioConfiguration *out_configuration) ``` -### SbMediaGetAudioOutputCount ### +### SbMediaGetAudioOutputCount Returns the number of audio outputs currently available on this device. Even if the number of outputs or their audio configurations can't be determined, it is expected that the platform will at least return a single output that supports at least stereo. -#### Declaration #### +#### Declaration ``` int SbMediaGetAudioOutputCount() ``` -### SbMediaGetBufferAlignment ### +### 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 #### +#### Declaration ``` int SbMediaGetBufferAlignment() ``` -### SbMediaGetBufferAllocationUnit ### +### SbMediaGetBufferAllocationUnit When the media stack needs more memory to store media buffers, it will allocate extra memory in units returned by SbMediaGetBufferAllocationUnit. This can @@ -550,13 +550,13 @@ 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferAllocationUnit() ``` -### SbMediaGetBufferGarbageCollectionDurationThreshold ### +### SbMediaGetBufferGarbageCollectionDurationThreshold Specifies the duration threshold of media source garbage collection. When the accumulated duration in a source buffer exceeds this value, the media source @@ -567,25 +567,25 @@ 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 #### +#### Declaration ``` SbTime SbMediaGetBufferGarbageCollectionDurationThreshold() ``` -### SbMediaGetBufferPadding ### +### 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. -#### Declaration #### +#### Declaration ``` int SbMediaGetBufferPadding() ``` -### SbMediaGetBufferStorageType ### +### SbMediaGetBufferStorageType Returns SbMediaBufferStorageType of type `SbMediaStorageTypeMemory` or `SbMediaStorageTypeFile`. For memory storage, the media buffers will be stored @@ -595,26 +595,26 @@ by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory". Note that when its value is "file" the media stack will still allocate memory to cache the the buffers in use. -#### Declaration #### +#### Declaration ``` SbMediaBufferStorageType SbMediaGetBufferStorageType() ``` -### SbMediaGetInitialBufferCapacity ### +### SbMediaGetInitialBufferCapacity The amount of memory that will be used to store media buffers allocated during system startup. To allocate a large chunk at startup helps with reducing fragmentation and can avoid failures to allocate incrementally. This can return 0. -#### Declaration #### +#### Declaration ``` int SbMediaGetInitialBufferCapacity() ``` -### SbMediaGetMaxBufferCapacity ### +### SbMediaGetMaxBufferCapacity The maximum amount of memory that will be used to store media buffers. This must be larger than sum of the video budget and audio budget. This is a soft limit @@ -629,13 +629,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetProgressiveBufferBudget ### +### SbMediaGetProgressiveBufferBudget The memory used when playing mp4 videos that is not in DASH format. The resolution of such videos shouldn't go beyond 1080p. Its value should be less @@ -647,13 +647,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaGetVideoBufferBudget ### +### SbMediaGetVideoBufferBudget Specifies the maximum amount of memory used by video buffers of media source before triggering a garbage collection. A large value will cause more memory @@ -666,13 +666,13 @@ width of the video resolution. `resolution_height`: the height of the video resolution. `bits_per_pixel`: the bits per pixel. This value is larger for HDR than non- HDR video. -#### Declaration #### +#### Declaration ``` int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec, int resolution_width, int resolution_height, int bits_per_pixel) ``` -### SbMediaIsBufferPoolAllocateOnDemand ### +### SbMediaIsBufferPoolAllocateOnDemand When either SbMediaGetInitialBufferCapacity or SbMediaGetBufferAllocationUnit isn't zero, media buffers will be allocated using a memory pool. Set the @@ -683,18 +683,18 @@ SbMediaGetInitialBufferCapacity bytes for media buffer on startup and will not release any media buffer memory back to the system even if there is no media buffers allocated. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferPoolAllocateOnDemand() ``` -### SbMediaIsBufferUsingMemoryPool ### +### SbMediaIsBufferUsingMemoryPool If SbMediaGetBufferUsingMemoryPool returns true, it indicates that media buffer pools should be allocated on demand, as opposed to using SbMemory* functions. -#### Declaration #### +#### Declaration ``` bool SbMediaIsBufferUsingMemoryPool() diff --git a/cobalt/site/docs/reference/starboard/modules/memory.md b/cobalt/site/docs/reference/starboard/modules/memory.md index 2fbf7dc94346..6dfa84442426 100644 --- a/cobalt/site/docs/reference/starboard/modules/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/memory.md @@ -1,17 +1,17 @@ ---- -layout: doc -title: "Starboard Module Reference: memory.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `memory.h` Defines functions for memory allocation, alignment, copying, and comparing. -## Porters ## +## 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 @@ -26,14 +26,14 @@ and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree. * The "free" functions are SbMemoryFree() and SbMemoryFreeAligned(). -## Enums ## +## Enums -### SbMemoryMapFlags ### +### SbMemoryMapFlags The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used. -#### Values #### +#### Values * `kSbMemoryMapProtectReserved` @@ -44,9 +44,9 @@ the mapped memory can be used. * `kSbMemoryMapProtectExec` * `kSbMemoryMapProtectReadWrite` -## Functions ## +## Functions -### SbMemoryAllocate ### +### SbMemoryAllocate Allocates and returns a chunk of memory of at least `size` bytes. This function should be called from the client codebase. It is intended to be a drop-in @@ -58,13 +58,13 @@ Note that this function returns `NULL` if it is unable to allocate the memory. return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocate(size_t size) ``` -### SbMemoryAllocateAligned ### +### SbMemoryAllocateAligned Allocates and returns a chunk of memory of at least `size` bytes, aligned to `alignment`. This function should be called from the client codebase. It is @@ -78,87 +78,87 @@ must be a power of two. `size`: The size of the memory to be allocated. If `size` is `0`, the function may return `NULL` or it may return a unique aligned pointer value that can be passed to SbMemoryDeallocateAligned. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAligned(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedChecked ### +### SbMemoryAllocateAlignedChecked Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateAlignedUnchecked ### +### SbMemoryAllocateAlignedUnchecked This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size) ``` -### SbMemoryAllocateChecked ### +### SbMemoryAllocateChecked Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateChecked(size_t size) ``` -### SbMemoryAllocateNoReport ### +### SbMemoryAllocateNoReport Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateNoReport(size_t size) ``` -### SbMemoryAllocateUnchecked ### +### SbMemoryAllocateUnchecked This is the implementation of SbMemoryAllocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryAllocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryAllocateUnchecked(size_t size) ``` -### SbMemoryCalloc ### +### SbMemoryCalloc A wrapper that implements a drop-in replacement for `calloc`, which is used in some packages. -#### Declaration #### +#### Declaration ``` static void* SbMemoryCalloc(size_t count, size_t size) ``` -### SbMemoryDeallocate ### +### SbMemoryDeallocate Frees a previously allocated chunk of memory. If `memory` is NULL, then the operation is a no-op. This function should be called from the client codebase. @@ -166,74 +166,74 @@ It is meant to be a drop-in replacement for `free`. `memory`: The chunk of memory to be freed. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocate(void *memory) ``` -### SbMemoryDeallocateAligned ### +### SbMemoryDeallocateAligned `memory`: The chunk of memory to be freed. If `memory` is NULL, then the function is a no-op. -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateAligned(void *memory) ``` -### SbMemoryDeallocateNoReport ### +### SbMemoryDeallocateNoReport Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport(). -#### Declaration #### +#### Declaration ``` void SbMemoryDeallocateNoReport(void *memory) ``` -### SbMemoryFlush ### +### SbMemoryFlush Flushes any data in the given virtual address range that is cached locally in the current processor core to physical memory, ensuring that data and instruction caches are cleared. This is required to be called on executable memory that has been written to and might be executed in the future. -#### Declaration #### +#### Declaration ``` void SbMemoryFlush(void *virtual_address, int64_t size_bytes) ``` -### SbMemoryFree ### +### SbMemoryFree This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocate(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFree(void *memory) ``` -### SbMemoryFreeAligned ### +### SbMemoryFreeAligned This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead. -#### Declaration #### +#### Declaration ``` void SbMemoryFreeAligned(void *memory) ``` -### SbMemoryMap ### +### SbMemoryMap Allocates `size_bytes` worth of physical memory pages and maps them into an available virtual region. This function returns `SB_MEMORY_MAP_FAILED` on @@ -248,24 +248,24 @@ used, the address space will not be accessible and, if possible, the platform should not count it against any memory budget. `name`: A value that appears in the debugger on some platforms. The value can be up to 32 bytes. -#### Declaration #### +#### Declaration ``` void* SbMemoryMap(int64_t size_bytes, int flags, const char *name) ``` -### SbMemoryProtect ### +### SbMemoryProtect Change the protection of `size_bytes` of memory regions, starting from `virtual_address`, to `flags`, returning `true` on success. -#### Declaration #### +#### Declaration ``` bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags) ``` -### SbMemoryReallocate ### +### SbMemoryReallocate Attempts to resize `memory` to be at least `size` bytes, without touching the contents of memory. @@ -285,39 +285,39 @@ it behaves exactly like SbMemoryAllocateUnchecked. `size`: The size to which `memory` will be resized. If `size` is `0`, the function may return `NULL` or it may return a unique pointer value that can be passed to SbMemoryDeallocate. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocate(void *memory, size_t size) ``` -### SbMemoryReallocateChecked ### +### SbMemoryReallocateChecked Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateChecked(void *memory, size_t size) ``` -### SbMemoryReallocateUnchecked ### +### SbMemoryReallocateUnchecked This is the implementation of SbMemoryReallocate that must be provided by Starboard ports. DO NOT CALL. Call SbMemoryReallocate(...) instead. -#### Declaration #### +#### Declaration ``` void* SbMemoryReallocateUnchecked(void *memory, size_t size) ``` -### SbMemoryUnmap ### +### SbMemoryUnmap Unmap `size_bytes` of physical pages starting from `virtual_address`, returning `true` on success. After this function completes, [virtual_address, @@ -327,7 +327,7 @@ SbMemoryMap(). For example, if one call to `SbMemoryMap(0x1000)` returns `(void*)0xA000`, and another call to `SbMemoryMap(0x1000)` returns `(void*)0xB000`, `SbMemoryUnmap(0xA000, 0x2000)` should free both regions. -#### Declaration #### +#### Declaration ``` bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes) diff --git a/cobalt/site/docs/reference/starboard/modules/microphone.md b/cobalt/site/docs/reference/starboard/modules/microphone.md index 1379f86726ae..497cbe91cec4 100644 --- a/cobalt/site/docs/reference/starboard/modules/microphone.md +++ b/cobalt/site/docs/reference/starboard/modules/microphone.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: microphone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `microphone.h` Defines functions for microphone creation, control, audio data fetching, and destruction. This module supports multiple calls to `SbMicrophoneOpen` and @@ -31,23 +31,23 @@ How to use this API: 1. Destroy the microphone with `SbMicrophoneDestroy`. -## Macros ## +## Macros -### kSbMicrophoneIdInvalid ### +### kSbMicrophoneIdInvalid Well-defined value for an invalid microphone ID handle. -### kSbMicrophoneInvalid ### +### kSbMicrophoneInvalid Well-defined value for an invalid microphone handle. -## Enums ## +## Enums -### SbMicrophoneType ### +### SbMicrophoneType All possible microphone types. -#### Values #### +#### Values * `kSbMicrophoneCamera` @@ -66,37 +66,37 @@ All possible microphone types. Unknown microphone type. The microphone could be different than the other enum descriptions or could fall under one of those descriptions. -## Typedefs ## +## Typedefs -### SbMicrophone ### +### SbMicrophone An opaque handle to an implementation-private structure that represents a microphone. -#### Definition #### +#### Definition ``` typedef struct SbMicrophonePrivate* SbMicrophone ``` -### SbMicrophoneId ### +### SbMicrophoneId An opaque handle to an implementation-private structure that represents a microphone ID. -#### Definition #### +#### Definition ``` typedef struct SbMicrophoneIdPrivate* SbMicrophoneId ``` -## Structs ## +## Structs -### SbMicrophoneInfo ### +### SbMicrophoneInfo Microphone information. -#### Members #### +#### Members * `SbMicrophoneId id` @@ -116,9 +116,9 @@ Microphone information. of the microphone type. For example, "Headset Microphone". The string must be null terminated. -## Functions ## +## Functions -### SbMicrophoneClose ### +### SbMicrophoneClose Closes the microphone port, stops recording audio on `microphone`, and clears the unread buffer if it is not empty. If the microphone has already been @@ -127,13 +127,13 @@ is closed. `microphone`: The microphone to close. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneClose(SbMicrophone microphone) ``` -### SbMicrophoneCreate ### +### SbMicrophoneCreate Creates a microphone with the specified ID, audio sample rate, and cached audio buffer size. Starboard only requires support for creating one microphone at a @@ -153,25 +153,25 @@ from the audio buffer if it has been read, and new audio data can be read from this buffer in smaller chunks than this size. This parameter must be set to a value greater than zero and the ideal size is `2^n`. -#### Declaration #### +#### Declaration ``` SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size_bytes) ``` -### SbMicrophoneDestroy ### +### SbMicrophoneDestroy Destroys a microphone. If the microphone is in started state, it is first stopped and then destroyed. Any data that has been recorded and not read is thrown away. -#### Declaration #### +#### Declaration ``` void SbMicrophoneDestroy(SbMicrophone microphone) ``` -### SbMicrophoneGetAvailable ### +### SbMicrophoneGetAvailable Retrieves all currently available microphone information and stores it in `out_info_array`. The return value is the number of the available microphones. @@ -184,43 +184,43 @@ indicates that an internal error occurred. placed into this output parameter. `info_array_size`: The size of `out_info_array`. -#### Declaration #### +#### Declaration ``` int SbMicrophoneGetAvailable(SbMicrophoneInfo *out_info_array, int info_array_size) ``` -### SbMicrophoneIdIsValid ### +### SbMicrophoneIdIsValid Indicates whether the given microphone ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIdIsValid(SbMicrophoneId id) ``` -### SbMicrophoneIsSampleRateSupported ### +### SbMicrophoneIsSampleRateSupported Indicates whether the microphone supports the sample rate. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz) ``` -### SbMicrophoneIsValid ### +### SbMicrophoneIsValid Indicates whether the given microphone is valid. -#### Declaration #### +#### Declaration ``` static bool SbMicrophoneIsValid(SbMicrophone microphone) ``` -### SbMicrophoneOpen ### +### SbMicrophoneOpen Opens the microphone port and starts recording audio on `microphone`. @@ -230,13 +230,13 @@ clears the unread buffer. The return value indicates whether the microphone is open. `microphone`: The microphone that will be opened and will start recording audio. -#### Declaration #### +#### Declaration ``` bool SbMicrophoneOpen(SbMicrophone microphone) ``` -### SbMicrophoneRead ### +### SbMicrophoneRead Retrieves the recorded audio data from the microphone and writes that data to `out_audio_data`. @@ -255,7 +255,7 @@ audio data is thrown out. No audio data is read from a stopped microphone. smaller than `min_read_size` of `SbMicrophoneInfo`, the extra audio data that has already been read from the device is discarded. -#### Declaration #### +#### Declaration ``` 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 58f19079f56a..9c18999b7479 100644 --- a/cobalt/site/docs/reference/starboard/modules/mutex.md +++ b/cobalt/site/docs/reference/starboard/modules/mutex.md @@ -1,24 +1,24 @@ ---- -layout: doc -title: "Starboard Module Reference: mutex.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `mutex.h` Defines a mutually exclusive lock that can be used to coordinate with other threads. -## Macros ## +## Macros -### SB_MUTEX_MAX_SIZE ### +### SB_MUTEX_MAX_SIZE Max size of the SbMutex type. -## Enums ## +## Enums -### SbMutexResult ### +### SbMutexResult Enumeration of possible results from acquiring a mutex. -#### Values #### +#### Values * `kSbMutexAcquired` @@ -30,22 +30,22 @@ Enumeration of possible results from acquiring a mutex. The mutex has already been destroyed. -## Typedefs ## +## Typedefs -### SbMutex ### +### SbMutex An opaque handle to a mutex type with reserved memory buffer of size SB_MUTEX_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbMutex SbMutex ``` -## Functions ## +## Functions -### SbMutexAcquire ### +### SbMutexAcquire Acquires `mutex`, blocking indefinitely. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition @@ -53,13 +53,13 @@ blocks forever. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquire(SbMutex *mutex) ``` -### SbMutexAcquireTry ### +### SbMutexAcquireTry Acquires `mutex`, without blocking. The return value identifies the acquisition result. SbMutexes are not reentrant, so a recursive acquisition has undefined @@ -67,52 +67,52 @@ behavior. `mutex`: The mutex to be acquired. -#### Declaration #### +#### Declaration ``` SbMutexResult SbMutexAcquireTry(SbMutex *mutex) ``` -### SbMutexCreate ### +### SbMutexCreate Creates a new mutex. The return value indicates whether the function was able to create a new mutex. `out_mutex`: The handle to the newly created mutex. -#### Declaration #### +#### Declaration ``` bool SbMutexCreate(SbMutex *out_mutex) ``` -### SbMutexDestroy ### +### SbMutexDestroy Destroys a mutex. The return value indicates whether the destruction was successful. Destroying a locked mutex results in undefined behavior. `mutex`: The mutex to be invalidated. -#### Declaration #### +#### Declaration ``` bool SbMutexDestroy(SbMutex *mutex) ``` -### SbMutexIsSuccess ### +### SbMutexIsSuccess Indicates whether the given result is a success. A value of `true` indicates that the mutex was acquired. `result`: The result being checked. -#### Declaration #### +#### Declaration ``` static bool SbMutexIsSuccess(SbMutexResult result) ``` -### SbMutexRelease ### +### SbMutexRelease Releases `mutex` held by the current thread. The return value indicates whether the release was successful. Releases should always be successful if `mutex` is @@ -120,7 +120,7 @@ held by the current thread. `mutex`: The mutex to be released. -#### Declaration #### +#### Declaration ``` bool SbMutexRelease(SbMutex *mutex) diff --git a/cobalt/site/docs/reference/starboard/modules/once.md b/cobalt/site/docs/reference/starboard/modules/once.md index ce3c4d637c8c..3088cd90e625 100644 --- a/cobalt/site/docs/reference/starboard/modules/once.md +++ b/cobalt/site/docs/reference/starboard/modules/once.md @@ -1,43 +1,43 @@ ---- -layout: doc -title: "Starboard Module Reference: once.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `once.h` Onces represent initializations that should only ever happen once per process, in a thread-safe way. -## Macros ## +## Macros -### SB_ONCE_MAX_SIZE ### +### SB_ONCE_MAX_SIZE Max size of the SbOnceControl type. -## Typedefs ## +## Typedefs -### SbOnceControl ### +### SbOnceControl An opaque handle to a once control type with reserved memory buffer of size SB_ONCE_MAX_SIZE and aligned at void pointer type. -#### Definition #### +#### Definition ``` typedef union SbOnceControl SbOnceControl ``` -### SbOnceInitRoutine ### +### SbOnceInitRoutine Function pointer type for methods that can be called via the SbOnce() system. -#### Definition #### +#### Definition ``` typedef void(* SbOnceInitRoutine) (void) ``` -## Functions ## +## Functions -### SbOnce ### +### SbOnce Thread-safely runs `init_routine` only once. @@ -50,7 +50,7 @@ Thread-safely runs `init_routine` only once. * If `once_control` or `init_routine` is invalid, the function returns `false`. -#### Declaration #### +#### Declaration ``` bool SbOnce(SbOnceControl *once_control, SbOnceInitRoutine init_routine) diff --git a/cobalt/site/docs/reference/starboard/modules/player.md b/cobalt/site/docs/reference/starboard/modules/player.md index 8039f6b69b41..e7e740e910eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/player.md +++ b/cobalt/site/docs/reference/starboard/modules/player.md @@ -1,53 +1,53 @@ ---- -layout: doc -title: "Starboard Module Reference: player.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `player.h` Defines an interface for controlling playback of media elementary streams. -## Macros ## +## Macros -### SB_PLAYER_INITIAL_TICKET ### +### SB_PLAYER_INITIAL_TICKET The value of the initial ticket held by the player before the first seek. The player will use this ticket value to make the first call to SbPlayerStatusFunc with kSbPlayerStateInitialized. -### SB_PLAYER_NO_DURATION ### +### SB_PLAYER_NO_DURATION The value to pass into SbPlayerCreate's `duration_pts` argument for cases where the duration is unknown, such as for live streams. -### kSbPlayerInvalid ### +### kSbPlayerInvalid Well-defined value for an invalid player. -### kSbPlayerWriteDurationLocal ### +### kSbPlayerWriteDurationLocal The audio write duration when all the audio connectors are local. -### kSbPlayerWriteDurationRemote ### +### kSbPlayerWriteDurationRemote The audio write duration when at least one of the audio connectors are remote. -## Enums ## +## Enums -### SbPlayerDecoderState ### +### SbPlayerDecoderState An indicator of whether the decoder can accept more samples. -#### Values #### +#### Values * `kSbPlayerDecoderStateNeedsData` The decoder is asking for one more sample. -### SbPlayerSampleSideDataType ### +### SbPlayerSampleSideDataType Identify the type of side data accompanied with `SbPlayerSampleInfo`, as side data may come from multiple sources. -#### Values #### +#### Values * `kMatroskaBlockAdditional` @@ -56,11 +56,11 @@ data may come from multiple sources. . The first 8 bytes of the data contains the value of BlockAddID in big endian format, followed by the content of BlockAdditional. -### SbPlayerState ### +### SbPlayerState An indicator of the general playback state. -#### Values #### +#### Values * `kSbPlayerStateInitialized` @@ -84,31 +84,31 @@ An indicator of the general playback state. The player has been destroyed, and will send no more callbacks. -## Typedefs ## +## Typedefs -### SbPlayer ### +### SbPlayer An opaque handle to an implementation-private structure representing a player. -#### Definition #### +#### Definition ``` typedef struct SbPlayerPrivate* SbPlayer ``` -### SbPlayerDeallocateSampleFunc ### +### SbPlayerDeallocateSampleFunc Callback to free the given sample buffer data. When more than one buffer are sent in SbPlayerWriteSample(), the implementation only has to call this callback with `sample_buffer` points to the the first buffer. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer) ``` -### SbPlayerDecoderStatusFunc ### +### SbPlayerDecoderStatusFunc Callback for decoder status updates, called in response to a call to SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called @@ -122,45 +122,45 @@ player will make at most one call to SbPlayerWriteSample() or SbPlayerWriteEndOfStream(). The player implementation should update the decoder status again after such call to notify its user to continue writing more frames. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerDecoderStatusFunc) (SbPlayer player, void *context, SbMediaType type, SbPlayerDecoderState state, int ticket) ``` -### SbPlayerErrorFunc ### +### SbPlayerErrorFunc Callback for player errors, that may set a `message`. `error`: indicates the error code. `message`: provides specific informative diagnostic message about the error condition encountered. It is ok for the message to be an empty string or NULL if no information is available. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerErrorFunc) (SbPlayer player, void *context, SbPlayerError error, const char *message) ``` -### SbPlayerStatusFunc ### +### SbPlayerStatusFunc Callback for player status updates. These callbacks will happen on a different thread than the calling thread, and it is not valid to call SbPlayer functions from within this callback. -#### Definition #### +#### Definition ``` typedef void(* SbPlayerStatusFunc) (SbPlayer player, void *context, SbPlayerState state, int ticket) ``` -## Structs ## +## Structs -### SbPlayerCreationParam ### +### SbPlayerCreationParam The playback related parameters to pass into SbPlayerCreate() and SbPlayerGetPreferredOutputMode(). -#### Members #### +#### Members * `SbDrmSystem drm_system` @@ -186,11 +186,11 @@ SbPlayerGetPreferredOutputMode(). should be made available for the application to pull via calls to SbPlayerGetCurrentFrame(). -### SbPlayerInfo ### +### SbPlayerInfo Information about the current media playback state. -#### Members #### +#### Members * `SbTime current_media_timestamp` @@ -237,11 +237,11 @@ Information about the current media playback state. faster than normal speed. When it is less than one, the video is played in a slower than normal speed. Negative speeds are not supported. -### SbPlayerSampleInfo ### +### SbPlayerSampleInfo Information about the samples to be written into SbPlayerWriteSamples(). -#### Members #### +#### Members * `SbMediaType type` * `const void * buffer` @@ -274,12 +274,12 @@ Information about the samples to be written into SbPlayerWriteSamples(). The DRM system related info for the media sample. This value is required for encrypted samples. Otherwise, it must be `NULL`. -### SbPlayerSampleSideData ### +### SbPlayerSampleSideData Side data accompanied with `SbPlayerSampleInfo`, it can be arbitrary binary data coming from multiple sources. -#### Members #### +#### Members * `SbPlayerSampleSideDataType type` * `const uint8_t * data` @@ -290,9 +290,9 @@ coming from multiple sources. The size of the data pointed by `data`, in bytes. -## Functions ## +## Functions -### SbPlayerDestroy ### +### SbPlayerDestroy Destroys `player`, freeing all associated resources. @@ -307,13 +307,13 @@ Destroys `player`, freeing all associated resources. SbPlayerDestroy has been called on that player. `player`: The player to be destroyed. Must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` void SbPlayerDestroy(SbPlayer player) ``` -### SbPlayerGetAudioConfiguration ### +### SbPlayerGetAudioConfiguration Returns the audio configurations used by `player`. @@ -371,13 +371,13 @@ be greater than or equal to 0. `out_audio_configuration`: The information about the audio output, refer to `SbMediaAudioConfiguration` for more details. Must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbPlayerGetAudioConfiguration(SbPlayer player, int index, SbMediaAudioConfiguration *out_audio_configuration) ``` -### SbPlayerGetCurrentFrame ### +### SbPlayerGetCurrentFrame Given a player created with the kSbPlayerOutputModeDecodeToTexture output mode, it will return a SbDecodeTarget representing the current frame to be rasterized. @@ -389,13 +389,13 @@ kSbDecodeTargetInvalid is returned. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player) ``` -### SbPlayerGetMaximumNumberOfSamplesPerWrite ### +### 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 @@ -409,13 +409,13 @@ to retain from those structures. of sample for which the number is retrieved. See the `SbMediaType` enum in media.h. -#### Declaration #### +#### Declaration ``` int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type) ``` -### SbPlayerGetPreferredOutputMode ### +### SbPlayerGetPreferredOutputMode Returns the preferred output mode of the implementation when a video described by `creation_param` is played. It is assumed that it is okay to call @@ -433,23 +433,23 @@ whether the video described by `creation_param` can be played on the platform, and the implementation should try its best effort to return a valid output mode. `creation_param` must not be NULL. -#### Declaration #### +#### Declaration ``` SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param) ``` -### SbPlayerIsValid ### +### SbPlayerIsValid Returns whether the given player handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbPlayerIsValid(SbPlayer player) ``` -### SbPlayerSetBounds ### +### SbPlayerSetBounds Sets the player bounds to the given graphics plane coordinates. The changes do not take effect until the next graphics frame buffer swap. The default bounds @@ -470,13 +470,13 @@ smaller z-index. `x`: The x-coordinate of the upper-left corner of the player. `y`: The y-coordinate of the upper-left corner of the player. `width`: The width of the player, in pixels. `height`: The height of the player, in pixels. -#### Declaration #### +#### Declaration ``` void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height) ``` -### SbPlayerSetPlaybackRate ### +### SbPlayerSetPlaybackRate Set the playback rate of the `player`. `rate` is default to 1.0 which indicates the playback is at its original speed. A `rate` greater than one will make the @@ -491,13 +491,13 @@ to support. `player` must not be `kSbPlayerInvalid`. -#### Declaration #### +#### Declaration ``` bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate) ``` -### SbPlayerSetVolume ### +### SbPlayerSetVolume Sets the player's volume. @@ -506,13 +506,13 @@ Sets the player's volume. `0.0` and `1.0`, inclusive. A value of `0.0` means that the audio should be muted, and a value of `1.0` means that it should be played at full volume. -#### Declaration #### +#### Declaration ``` void SbPlayerSetVolume(SbPlayer player, double volume) ``` -### SbPlayerWriteEndOfStream ### +### SbPlayerWriteEndOfStream Writes a marker to `player`'s input stream of `stream_type` indicating that there are no more samples for that media type for the remainder of this media @@ -522,13 +522,13 @@ contents, after a call to SbPlayerSeek. `player`: The player to which the marker is written. `stream_type`: The type of stream for which the marker is written. -#### Declaration #### +#### Declaration ``` void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type) ``` -### SbPlayerWriteSamples ### +### SbPlayerWriteSamples `sample_type`: The type of sample being written. See the `SbMediaType` enum in media.h. `sample_infos`: A pointer to an array of SbPlayerSampleInfo with @@ -540,7 +540,7 @@ be copied if its content will be used after SbPlayerWriteSamples() returns. `sample_infos`. It has to be at least one, and less than the return value of SbPlayerGetMaximumNumberOfSamplesPerWrite(). -#### Declaration #### +#### Declaration ``` void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos) diff --git a/cobalt/site/docs/reference/starboard/modules/socket.md b/cobalt/site/docs/reference/starboard/modules/socket.md index 9e0f81b98334..744c04e3847d 100644 --- a/cobalt/site/docs/reference/starboard/modules/socket.md +++ b/cobalt/site/docs/reference/starboard/modules/socket.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket.h` Defines Starboard socket I/O functions. Starboard supports IPv4 and IPv6, TCP and UDP, server and client sockets. Some platforms may not support IPv6, some @@ -18,19 +18,19 @@ the connection, thus requiring use of either an SbSocketWaiter or spin-polling. TODO: For platforms that do not support sockets at all, they must support at least a high-level HTTP client API (to be defined later). -## Macros ## +## Macros -### kSbSocketInvalid ### +### kSbSocketInvalid Well-defined value for an invalid socket handle. -## Enums ## +## Enums -### SbSocketAddressType ### +### SbSocketAddressType All possible address types. -#### Values #### +#### Values * `kSbSocketAddressTypeIpv4` @@ -39,13 +39,13 @@ All possible address types. An IPv6 address, which uses 16 entries of the address buffer. -### SbSocketError ### +### SbSocketError Enumeration of all Starboard socket operation results. Despite the enum name, note that the value actually describes the outcome of an operation, which is not always an error. -#### Values #### +#### Values * `kSbSocketOk` @@ -63,11 +63,11 @@ always an error. The operation failed for some other reason not specified above. -### SbSocketProtocol ### +### SbSocketProtocol All possible IP socket types. -#### Values #### +#### Values * `kSbSocketProtocolTcp` @@ -77,11 +77,11 @@ All possible IP socket types. The UDP/IP protocol, an unreliable, connectionless, discrete packet (datagram) protocol. -### SbSocketResolveFilter ### +### SbSocketResolveFilter Bits that can be set when calling SbSocketResolve to filter the results. -#### Values #### +#### Values * `kSbSocketResolveFilterNone` @@ -93,25 +93,25 @@ Bits that can be set when calling SbSocketResolve to filter the results. Include Ipv6 addresses. -## Typedefs ## +## Typedefs -### SbSocket ### +### SbSocket A handle to a socket. -#### Definition #### +#### Definition ``` typedef SbSocketPrivate* SbSocket ``` -## Structs ## +## Structs -### SbSocketAddress ### +### SbSocketAddress A representation of any possible supported address type. -#### Members #### +#### Members * `uint8_t address` @@ -126,11 +126,11 @@ A representation of any possible supported address type. The port component of this socket address. If not specified, it will be zero, which is officially undefined. -### SbSocketResolution ### +### SbSocketResolution The result of a host name resolution. -#### Members #### +#### Members * `SbSocketAddress* addresses` @@ -139,9 +139,9 @@ The result of a host name resolution. The length of the `addresses` array. -## Functions ## +## Functions -### SbSocketAccept ### +### SbSocketAccept Accepts a pending connection on `socket` and returns a new SbSocket representing that connection. This function sets the error on `socket` and returns @@ -149,13 +149,13 @@ that connection. This function sets the error on `socket` and returns `socket`: The SbSocket that is accepting a pending connection. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketAccept(SbSocket socket) ``` -### SbSocketBind ### +### SbSocketBind Binds `socket` to a specific local interface and port specified by `local_address`. This function sets and returns the socket error if it is unable @@ -170,24 +170,24 @@ local address to which the socket is to be bound. This value must not be `NULL`. * Setting the IP address to `0.0.0.0` means that the socket should be bound to all interfaces. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketBind(SbSocket socket, const SbSocketAddress *local_address) ``` -### SbSocketClearLastError ### +### SbSocketClearLastError Clears the last error set on `socket`. The return value indicates whether the socket error was cleared. -#### Declaration #### +#### Declaration ``` bool SbSocketClearLastError(SbSocket socket) ``` -### SbSocketConnect ### +### SbSocketConnect Opens a connection of `socket`'s type to the host and port specified by `address`. This function sets and returns the socket error if it is unable to @@ -197,13 +197,13 @@ successfully.) `socket`: The type of connection that should be opened. `address`: The host and port to which the socket should connect. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketConnect(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketCreate ### +### SbSocketCreate Creates a new non-blocking socket for protocol `protocol` using address family `address_type`. @@ -216,13 +216,13 @@ Creates a new non-blocking socket for protocol `protocol` using address family `address_type`: The type of IP address to use for the socket. `protocol`: The protocol to use for the socket. -#### Declaration #### +#### Declaration ``` SbSocket SbSocketCreate(SbSocketAddressType address_type, SbSocketProtocol protocol) ``` -### SbSocketDestroy ### +### SbSocketDestroy Destroys the `socket` by flushing it, closing any connection that may be active on it, and reclaiming any resources associated with it, including any @@ -234,25 +234,25 @@ more. `socket`: The SbSocket to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketDestroy(SbSocket socket) ``` -### SbSocketFreeResolution ### +### SbSocketFreeResolution Frees a resolution allocated by SbSocketResolve. `resolution`: The resolution to be freed. -#### Declaration #### +#### Declaration ``` void SbSocketFreeResolution(SbSocketResolution *resolution) ``` -### SbSocketGetInterfaceAddress ### +### SbSocketGetInterfaceAddress Gets the source address and the netmask that would be used to connect to the destination. The netmask parameter is optional, and only populated if a non-NULL @@ -288,26 +288,26 @@ this output variable. `out_netmask`: This parameter is optional. If a non-NULL value is passed in, this function places the netmask associated with the source address in this output variable. -#### Declaration #### +#### Declaration ``` bool SbSocketGetInterfaceAddress(const SbSocketAddress *const destination, SbSocketAddress *out_source_address, SbSocketAddress *out_netmask) ``` -### SbSocketGetLastError ### +### SbSocketGetLastError Returns the last error set on `socket`. If `socket` is not valid, this function returns `kSbSocketErrorFailed`. `socket`: The SbSocket that the last error is returned for. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketGetLastError(SbSocket socket) ``` -### SbSocketGetLocalAddress ### +### SbSocketGetLocalAddress Gets the address that this socket is bound to locally, if the socket is connected. The return value indicates whether the address was retrieved @@ -316,59 +316,59 @@ successfully. `socket`: The SbSocket for which the local address is retrieved. `out_address`: The SbSocket's local address. -#### Declaration #### +#### Declaration ``` bool SbSocketGetLocalAddress(SbSocket socket, SbSocketAddress *out_address) ``` -### SbSocketIsConnected ### +### SbSocketIsConnected Indicates whether `socket` is connected to anything. Invalid sockets are not connected. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnected(SbSocket socket) ``` -### SbSocketIsConnectedAndIdle ### +### SbSocketIsConnectedAndIdle Returns whether `socket` is connected to anything, and, if so, whether it is receiving any data. `socket`: The SbSocket to be checked. -#### Declaration #### +#### Declaration ``` bool SbSocketIsConnectedAndIdle(SbSocket socket) ``` -### SbSocketIsIpv6Supported ### +### SbSocketIsIpv6Supported Returns whether IPV6 is supported on the current platform. -#### Declaration #### +#### Declaration ``` bool SbSocketIsIpv6Supported() ``` -### SbSocketIsValid ### +### SbSocketIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketIsValid(SbSocket socket) ``` -### SbSocketJoinMulticastGroup ### +### SbSocketJoinMulticastGroup Joins `socket` to an IP multicast group identified by `address`. The equivalent of IP_ADD_MEMBERSHIP. The return value indicates whether the socket was joined @@ -377,13 +377,13 @@ to the group successfully. `socket`: The SbSocket to be joined to the IP multicast group. `address`: The location of the IP multicast group. -#### Declaration #### +#### Declaration ``` bool SbSocketJoinMulticastGroup(SbSocket socket, const SbSocketAddress *address) ``` -### SbSocketListen ### +### SbSocketListen Causes `socket` to listen on the local address that `socket` was previously bound to by SbSocketBind. This function sets and returns the socket error if it @@ -392,13 +392,13 @@ connection successfully.) `socket`: The SbSocket on which the function operates. -#### Declaration #### +#### Declaration ``` SbSocketError SbSocketListen(SbSocket socket) ``` -### SbSocketReceiveFrom ### +### SbSocketReceiveFrom Reads up to `data_size` bytes from `socket` into `out_data` and places the source address of the packet in `out_source` if out_source is not NULL. Returns @@ -420,13 +420,13 @@ the address is unnecessary, but allowed. the socket. Must not be NULL. `data_size`: The number of bytes to read. `out_source`: The source address of the packet. -#### Declaration #### +#### Declaration ``` int SbSocketReceiveFrom(SbSocket socket, char *out_data, int data_size, SbSocketAddress *out_source) ``` -### SbSocketResolve ### +### SbSocketResolve Synchronously resolves `hostname` into the returned SbSocketResolution , which must be freed with SbSocketFreeResolution. The function returns `NULL` if it is @@ -438,13 +438,13 @@ not specify an IP address family filter, all address families are included. However, if one IP address family filter is specified, only that address family is included. The function ignores unrecognized filter bits. -#### Declaration #### +#### Declaration ``` SbSocketResolution* SbSocketResolve(const char *hostname, int filters) ``` -### SbSocketSendTo ### +### SbSocketSendTo Writes up to `data_size` bytes of `data` to `destination` via `socket`. Returns the number of bytes written, or a negative number if there is an error, in which @@ -466,13 +466,13 @@ to multiple sources from a single UDP server socket. TCP has two endpoints connected persistently, so setting `destination` when sending to a TCP socket will cause an error. -#### Declaration #### +#### Declaration ``` int SbSocketSendTo(SbSocket socket, const char *data, int data_size, const SbSocketAddress *destination) ``` -### SbSocketSetBroadcast ### +### SbSocketSetBroadcast Sets the `SO_BROADCAST`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -483,13 +483,13 @@ the broadcast address. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetBroadcast(SbSocket socket, bool value) ``` -### SbSocketSetReceiveBufferSize ### +### SbSocketSetReceiveBufferSize Sets the `SO_RCVBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -497,13 +497,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReceiveBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetReuseAddress ### +### SbSocketSetReuseAddress Sets the `SO_REUSEADDR`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -514,13 +514,13 @@ to it. `socket`: The SbSocket for which the option is set. `value`: The new value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetReuseAddress(SbSocket socket, bool value) ``` -### SbSocketSetSendBufferSize ### +### SbSocketSetSendBufferSize Sets the `SO_SNDBUF`, or equivalent, option to `size` on `socket`. The return value indicates whether the option was actually set. @@ -528,13 +528,13 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `size`: The value for the option. -#### Declaration #### +#### Declaration ``` bool SbSocketSetSendBufferSize(SbSocket socket, int32_t size) ``` -### SbSocketSetTcpKeepAlive ### +### SbSocketSetTcpKeepAlive Sets the `SO_KEEPALIVE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -545,13 +545,13 @@ 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`. -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpKeepAlive(SbSocket socket, bool value, SbTime period) ``` -### SbSocketSetTcpNoDelay ### +### SbSocketSetTcpNoDelay Sets the `TCP_NODELAY`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -564,13 +564,13 @@ behavior. `socket`: The SbSocket for which the option is set. `value`: Indicates whether the Nagle algorithm should be disabled (`value`=`true`). -#### Declaration #### +#### Declaration ``` bool SbSocketSetTcpNoDelay(SbSocket socket, bool value) ``` -### SbSocketSetTcpWindowScaling ### +### SbSocketSetTcpWindowScaling Sets the `SO_WINSCALE`, or equivalent, option to `value` on `socket`. The return value indicates whether the option was actually set. @@ -578,7 +578,7 @@ value indicates whether the option was actually set. `socket`: The SbSocket for which the option is set. `value`: The value for the option. -#### Declaration #### +#### Declaration ``` 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 738fafb11dec..146938cbebd9 100644 --- a/cobalt/site/docs/reference/starboard/modules/socket_waiter.md +++ b/cobalt/site/docs/reference/starboard/modules/socket_waiter.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: socket_waiter.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `socket_waiter.h` Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to: @@ -26,19 +26,19 @@ thread, it needs to call SbSocketWaiterWakeUp() on the SbSocketWaiter after queuing the work item, or the SbSocketWaiter is not otherwise guaranteed to wake up. -## Macros ## +## Macros -### kSbSocketWaiterInvalid ### +### kSbSocketWaiterInvalid Well-defined value for an invalid socket watcher handle. -## Enums ## +## Enums -### SbSocketWaiterInterest ### +### SbSocketWaiterInterest All the interests that a socket may register for on a waiter. -#### Values #### +#### Values * `kSbSocketWaiterInterestNone` @@ -50,11 +50,11 @@ All the interests that a socket may register for on a waiter. An interest in or readiness to write to a socket without blocking. -### SbSocketWaiterResult ### +### SbSocketWaiterResult Possible reasons why a call to SbSocketWaiterWaitTimed returned. -#### Values #### +#### Values * `kSbSocketWaiterResultInvalid` @@ -66,31 +66,31 @@ Possible reasons why a call to SbSocketWaiterWaitTimed returned. The wait stopped because a call to SbSocketWaiterWakeUp was consumed. -## Typedefs ## +## Typedefs -### SbSocketWaiter ### +### SbSocketWaiter A handle to a socket waiter. -#### Definition #### +#### Definition ``` typedef SbSocketWaiterPrivate* SbSocketWaiter ``` -### SbSocketWaiterCallback ### +### SbSocketWaiterCallback Function pointer for socket waiter callbacks. -#### Definition #### +#### Definition ``` typedef void(* SbSocketWaiterCallback) (SbSocketWaiter waiter, SbSocket socket, void *context, int ready_interests) ``` -## Functions ## +## Functions -### SbSocketWaiterAdd ### +### SbSocketWaiterAdd Adds a new socket to be waited on by the `waiter` with a bitfield of `interests`. This function should only be called on the thread that waits on @@ -120,25 +120,25 @@ socket: `callback`, even if not all registered `interests` became ready, which allows for adding it again in the `callback`. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterAdd(SbSocketWaiter waiter, SbSocket socket, void *context, SbSocketWaiterCallback callback, int interests, bool persistent) ``` -### SbSocketWaiterCreate ### +### SbSocketWaiterCreate The results of two threads waiting on the same waiter is undefined and will not work. Except for the SbSocketWaiterWakeUp() function, SbSocketWaiters are not thread-safe and don't expect to be modified concurrently. -#### Declaration #### +#### Declaration ``` SbSocketWaiter SbSocketWaiterCreate() ``` -### SbSocketWaiterDestroy ### +### SbSocketWaiterDestroy Destroys `waiter` and removes all sockets still registered by way of SbSocketWaiterAdd. This function may be called on any thread as long as there is @@ -146,23 +146,23 @@ no risk of concurrent access to the waiter. `waiter`: The SbSocketWaiter to be destroyed. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterDestroy(SbSocketWaiter waiter) ``` -### SbSocketWaiterIsValid ### +### SbSocketWaiterIsValid Returns whether the given socket handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbSocketWaiterIsValid(SbSocketWaiter watcher) ``` -### SbSocketWaiterRemove ### +### SbSocketWaiterRemove Removes a socket, previously added with SbSocketWaiterAdd(), from a waiter. This function should only be called on the thread that waits on this waiter. @@ -174,26 +174,26 @@ returns `true`. `waiter`: The waiter from which the socket is removed. `socket`: The socket to remove from the waiter. -#### Declaration #### +#### Declaration ``` bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket) ``` -### SbSocketWaiterWait ### +### SbSocketWaiterWait Waits on all registered sockets, calling the registered callbacks if and when the corresponding sockets become ready for an interested operation. This version exits only after SbSocketWaiterWakeUp() is called. This function should only be called on the thread that waits on this waiter. -#### Declaration #### +#### Declaration ``` void SbSocketWaiterWait(SbSocketWaiter waiter) ``` -### SbSocketWaiterWaitTimed ### +### SbSocketWaiterWaitTimed Behaves similarly to SbSocketWaiterWait(), but this function also causes `waiter` to exit on its own after at least `duration` has passed if @@ -207,13 +207,13 @@ 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 #### +#### Declaration ``` SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter, SbTime duration) ``` -### SbSocketWaiterWakeUp ### +### SbSocketWaiterWakeUp Wakes up `waiter` once. This is the only thread-safe waiter function. It can can be called from a SbSocketWaiterCallback to wake up its own waiter, and it can @@ -230,7 +230,7 @@ next 7 times they are called. `waiter`: The socket waiter to be woken up. -#### Declaration #### +#### Declaration ``` 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 e46a2cac70cd..ea4ad46b3f87 100644 --- a/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md +++ b/cobalt/site/docs/reference/starboard/modules/speech_synthesis.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: speech_synthesis.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `speech_synthesis.h` A basic text-to-speech API intended to be used for audio accessibility. @@ -11,29 +11,29 @@ non-visual navigation of the application. Note that these functions do not have to be thread-safe. They must only be called from a single application thread. -## Functions ## +## Functions -### SbSpeechSynthesisCancel ### +### SbSpeechSynthesisCancel Cancels all speaking and queued speech synthesis audio. Must return immediately. -#### Declaration #### +#### Declaration ``` void SbSpeechSynthesisCancel() ``` -### SbSpeechSynthesisIsSupported ### +### SbSpeechSynthesisIsSupported Returns whether the platform supports speech synthesis -#### Declaration #### +#### Declaration ``` bool SbSpeechSynthesisIsSupported() ``` -### SbSpeechSynthesisSpeak ### +### SbSpeechSynthesisSpeak Enqueues `text`, a UTF-8 string, to be spoken. Returns immediately. @@ -44,7 +44,7 @@ If audio from previous SbSpeechSynthesisSpeak() invocations is still processing, the current speaking should continue and this new text should be queued to play when the previous utterances are complete. -#### Declaration #### +#### Declaration ``` 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 c98207b67d98..b486ac84c525 100644 --- a/cobalt/site/docs/reference/starboard/modules/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/storage.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: storage.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `storage.h` Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and retrieval API that is intended for robust long-term, per-user storage. Some @@ -15,27 +15,27 @@ record for a user will result in undefined behavior. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbStorageInvalidRecord ### +### kSbStorageInvalidRecord Well-defined value for an invalid storage record handle. -## Typedefs ## +## Typedefs -### SbStorageRecord ### +### SbStorageRecord A handle to an open storage record. -#### Definition #### +#### Definition ``` typedef SbStorageRecordPrivate* SbStorageRecord ``` -## Functions ## +## Functions -### SbStorageCloseRecord ### +### SbStorageCloseRecord Closes `record`, synchronously ensuring that all written data is flushed. This function performs blocking I/O on the calling thread. @@ -47,13 +47,13 @@ deleted (or, even better, untouched). `record`: The storage record to close. `record` is invalid after this point, and subsequent calls referring to `record` will fail. -#### Declaration #### +#### Declaration ``` bool SbStorageCloseRecord(SbStorageRecord record) ``` -### SbStorageDeleteRecord ### +### SbStorageDeleteRecord Deletes the `SbStorageRecord` for `user` named `name`. The return value indicates whether the record existed and was successfully deleted. If the record @@ -68,36 +68,36 @@ function performs blocking I/O on the calling thread. `user`: The user for whom the record will be deleted. `name`: The filesystem- safe name of the record to open. -#### Declaration #### +#### Declaration ``` bool SbStorageDeleteRecord(SbUser user, const char *name) ``` -### SbStorageGetRecordSize ### +### SbStorageGetRecordSize Returns the size of `record`, or `-1` if there is an error. This function performs blocking I/O on the calling thread. `record`: The record to retrieve the size of. -#### Declaration #### +#### Declaration ``` int64_t SbStorageGetRecordSize(SbStorageRecord record) ``` -### SbStorageIsValidRecord ### +### SbStorageIsValidRecord Returns whether the given storage record handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbStorageIsValidRecord(SbStorageRecord record) ``` -### SbStorageOpenRecord ### +### SbStorageOpenRecord Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on the calling thread until the open is completed. If `user` is not a valid @@ -111,13 +111,13 @@ would have been saved with the previous version of SbStorageOpenRecord. `user`: The user for which the storage record will be opened. `name`: The filesystem-safe name of the record to open. -#### Declaration #### +#### Declaration ``` SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) ``` -### SbStorageReadRecord ### +### SbStorageReadRecord Reads up to `data_size` bytes from `record`, starting at the beginning of the record. The function returns the actual number of bytes read, which must be <= @@ -128,13 +128,13 @@ the calling thread until the entire record is read or an error is encountered. `record`: The record to be read. `out_data`: The data read from the record. `data_size`: The amount of data, in bytes, to read. -#### Declaration #### +#### Declaration ``` int64_t SbStorageReadRecord(SbStorageRecord record, char *out_data, int64_t data_size) ``` -### SbStorageWriteRecord ### +### SbStorageWriteRecord Replaces the data in `record` with `data_size` bytes from `data`. This function always deletes any previous data in that record. The return value indicates @@ -151,7 +151,7 @@ after a short time, even if there is an unexpected process termination before `record`: The record to be written to. `data`: The data to write to the record. `data_size`: The amount of `data`, in bytes, to write to the record. -#### Declaration #### +#### Declaration ``` 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 95790d4acff4..5e9796880177 100644 --- a/cobalt/site/docs/reference/starboard/modules/string.md +++ b/cobalt/site/docs/reference/starboard/modules/string.md @@ -1,13 +1,13 @@ ---- -layout: doc -title: "Starboard Module Reference: string.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `string.h` Defines functions for interacting with c-style strings. -## Functions ## +## Functions -### SbStringCompareNoCase ### +### SbStringCompareNoCase Compares two strings, ignoring differences in case. The return value is: @@ -21,13 +21,13 @@ This function is meant to be a drop-in replacement for `strcasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCase(const char *string1, const char *string2) ``` -### SbStringCompareNoCaseN ### +### SbStringCompareNoCaseN Compares the first `count` characters of two strings, ignoring differences in case. The return value is: @@ -43,13 +43,13 @@ This function is meant to be a drop-in replacement for `strncasecmp`. `string1`: The first string to compare. `string2`: The second string to compare. `count`: The number of characters to compare. -#### Declaration #### +#### Declaration ``` int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) ``` -### SbStringDuplicate ### +### SbStringDuplicate Copies `source` into a buffer that is allocated by this function and that can be freed with SbMemoryDeallocate. This function is meant to be a drop-in @@ -57,13 +57,13 @@ replacement for `strdup`. `source`: The string to be copied. -#### Declaration #### +#### Declaration ``` char* SbStringDuplicate(const char *source) ``` -### SbStringFormat ### +### SbStringFormat Produces a string formatted with `format` and `arguments`, placing as much of the result that will fit into `out_buffer`. The return value specifies the @@ -76,13 +76,13 @@ This function is meant to be a drop-in replacement for `vsnprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatF ### +### SbStringFormatF An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This function is meant to be a drop-in replacement for `snprintf`. @@ -91,13 +91,13 @@ function is meant to be a drop-in replacement for `snprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 ``` -### SbStringFormatUnsafeF ### +### SbStringFormatUnsafeF An inline wrapper of SbStringFormat that is meant to be a drop-in replacement for the unsafe but commonly used `sprintf`. @@ -106,13 +106,13 @@ for the unsafe but commonly used `sprintf`. string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 ``` -### SbStringFormatWide ### +### SbStringFormatWide This function is identical to SbStringFormat, but is for wide characters. It is meant to be a drop-in replacement for `vswprintf`. @@ -121,13 +121,13 @@ meant to be a drop-in replacement for `vswprintf`. The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `arguments`: Variable arguments used in the string. -#### Declaration #### +#### Declaration ``` int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) ``` -### SbStringFormatWideF ### +### SbStringFormatWideF An inline wrapper of SbStringFormatWide that converts from ellipsis to `va_args`. @@ -136,13 +136,13 @@ An inline wrapper of SbStringFormatWide that converts from ellipsis to The size of `out_buffer`. `format`: A string that specifies how the data should be formatted. `...`: Arguments used in the string. -#### Declaration #### +#### Declaration ``` static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) ``` -### SbStringScan ### +### SbStringScan Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The return value specifies the number of successfully matched items, which may be @@ -154,20 +154,20 @@ This function is meant to be a drop-in replacement for `vsscanf`. for in `buffer`. `arguments`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` int SbStringScan(const char *buffer, const char *pattern, va_list arguments) ``` -### SbStringScanF ### +### SbStringScanF An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: Values matching `pattern` that were extracted from `buffer`. -#### Declaration #### +#### Declaration ``` static int SbStringScanF(const char *buffer, const char *pattern,...) diff --git a/cobalt/site/docs/reference/starboard/modules/system.md b/cobalt/site/docs/reference/starboard/modules/system.md index 32fd3032ee05..86437a3d0804 100644 --- a/cobalt/site/docs/reference/starboard/modules/system.md +++ b/cobalt/site/docs/reference/starboard/modules/system.md @@ -1,21 +1,21 @@ ---- -layout: doc -title: "Starboard Module Reference: system.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `system.h` Defines a broad set of APIs that allow the client application to query build and runtime properties of the enclosing system. -## Enums ## +## Enums -### SbSystemCapabilityId ### +### SbSystemCapabilityId Runtime capabilities are boolean properties of a platform that can't be determined at compile-time. They may vary from device to device, but they will not change over the course of a single execution. They often specify particular behavior of other APIs within the bounds of their operating range. -#### Values #### +#### Values * `kSbSystemCapabilityReversedEnterAndBack` @@ -26,11 +26,11 @@ behavior of other APIs within the bounds of their operating range. only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call. -### SbSystemPathId ### +### SbSystemPathId Enumeration of special paths that the platform can define. -#### Values #### +#### Values * `kSbSystemPathContentDirectory` @@ -66,22 +66,22 @@ Enumeration of special paths that the platform can define. for storing the updates. See starboard/doc/evergreen/cobalt_evergreen_overview.md -### SbSystemPlatformErrorResponse ### +### SbSystemPlatformErrorResponse Possible responses for `SbSystemPlatformErrorCallback`. -#### Values #### +#### Values * `kSbSystemPlatformErrorResponsePositive` * `kSbSystemPlatformErrorResponseNegative` * `kSbSystemPlatformErrorResponseCancel` -### SbSystemPlatformErrorType ### +### SbSystemPlatformErrorType Enumeration of possible values for the `type` parameter passed to the `SbSystemRaisePlatformError` function. -#### Values #### +#### Values * `kSbSystemPlatformErrorTypeConnectionError` @@ -90,12 +90,12 @@ Enumeration of possible values for the `type` parameter passed to the `kSbSystemPlatformErrorResponsePositive` then the request should be retried, otherwise the app should be stopped. -### SbSystemPropertyId ### +### SbSystemPropertyId System properties that can be queried for. Many of these are used in User-Agent string generation. -#### Values #### +#### Values * `kSbSystemPropertyCertificationScope` @@ -156,9 +156,9 @@ string generation. Type of the device, e.g. such as "TV", "STB", "OTT" Please see Youtube Technical requirements for a full list of allowed values -## Typedefs ## +## Typedefs -### SbSystemComparator ### +### SbSystemComparator Pointer to a function to compare two items. The return value uses standard `*cmp` semantics: @@ -171,23 +171,23 @@ Pointer to a function to compare two items. The return value uses standard `a`: The first value to compare. `b`: The second value to compare. -#### Definition #### +#### Definition ``` typedef int(* SbSystemComparator) (const void *a, const void *b) ``` -### SbSystemError ### +### SbSystemError A type that can represent a system error code across all Starboard platforms. -#### Definition #### +#### Definition ``` typedef int SbSystemError ``` -### SbSystemPlatformErrorCallback ### +### SbSystemPlatformErrorCallback Type of callback function that may be called in response to an error notification from `SbSystemRaisePlatformError`. `response` is a code to indicate @@ -195,36 +195,36 @@ the user's response, e.g. if the platform raised a dialog to notify the user of the error. `user_data` is the opaque pointer that was passed to the call to `SbSystemRaisePlatformError`. -#### Definition #### +#### Definition ``` typedef void(* SbSystemPlatformErrorCallback) (SbSystemPlatformErrorResponse response, void *user_data) ``` -## Functions ## +## Functions -### SbSystemBreakIntoDebugger ### +### SbSystemBreakIntoDebugger Breaks the current program into the debugger, if a debugger is attached. If a debugger is not attached, this function aborts the program. -#### Declaration #### +#### Declaration ``` SB_NORETURN void SbSystemBreakIntoDebugger() ``` -### SbSystemClearLastError ### +### SbSystemClearLastError Clears the last error set by a Starboard call in the current thread. -#### Declaration #### +#### Declaration ``` void SbSystemClearLastError() ``` -### SbSystemGetErrorString ### +### SbSystemGetErrorString Generates a human-readable string for an error. The return value specifies the total desired length of the string. @@ -233,13 +233,13 @@ total desired length of the string. The generated string. This value may be null, and it is always terminated with a null byte. `string_length`: The maximum length of the error string. -#### Declaration #### +#### Declaration ``` int SbSystemGetErrorString(SbSystemError error, char *out_string, int string_length) ``` -### SbSystemGetExtension ### +### SbSystemGetExtension Returns pointer to a constant global struct implementing the extension named `name`, if it is implemented. Otherwise return NULL. The `name` string must not @@ -261,25 +261,25 @@ application may only get the extension once, meaning updated values would be ignored. As the version of extensions are incremented, fields may be added to the end of the struct, but never removed (only deprecated). -#### Declaration #### +#### Declaration ``` const void* SbSystemGetExtension(const char *name) ``` -### SbSystemGetLastError ### +### SbSystemGetLastError Gets the last platform-specific error code produced by any Starboard call in the current thread for diagnostic purposes. Semantic reactions to Starboard function call results should be modeled explicitly. -#### Declaration #### +#### Declaration ``` SbSystemError SbSystemGetLastError() ``` -### SbSystemGetLocaleId ### +### SbSystemGetLocaleId Gets the system's current POSIX-style Locale ID. The locale represents the location, language, and cultural conventions that the system wants to use, which @@ -296,25 +296,25 @@ RFC 5646 describes BCP 47 language codes: [https://tools.ietf.org/html/bcp47](ht For more information than you probably want about POSIX locales, see: [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html) -#### Declaration #### +#### Declaration ``` const char* SbSystemGetLocaleId() ``` -### SbSystemGetNumberOfProcessors ### +### SbSystemGetNumberOfProcessors Returns the number of processor cores available to this application. If the process is sandboxed to a subset of the physical cores, the function returns that sandboxed limit. -#### Declaration #### +#### Declaration ``` int SbSystemGetNumberOfProcessors() ``` -### SbSystemGetProperty ### +### SbSystemGetProperty Retrieves the platform-defined system property specified by `property_id` and places its value as a zero-terminated string into the user-allocated `out_value` @@ -335,13 +335,13 @@ returns `false` under any of the following conditions and, in any such case, defined system property specified by `property_id`. `value_length`: The length of the system property. -#### Declaration #### +#### Declaration ``` bool SbSystemGetProperty(SbSystemPropertyId property_id, char *out_value, int value_length) ``` -### SbSystemGetRandomData ### +### SbSystemGetRandomData A cryptographically secure random number generator that produces an arbitrary, non-negative number of `buffer_size` random, non-negative bytes. The generated @@ -350,24 +350,24 @@ number is placed in `out_buffer`. This function does not require manual seeding. `out_buffer`: A pointer for the generated random number. This value must not be null. `buffer_size`: The size of the random number, in bytes. -#### Declaration #### +#### Declaration ``` void SbSystemGetRandomData(void *out_buffer, int buffer_size) ``` -### SbSystemGetRandomUInt64 ### +### SbSystemGetRandomUInt64 A cryptographically secure random number generator that gets 64 random bits and returns them as an `uint64_t`. This function does not require manual seeding. -#### Declaration #### +#### Declaration ``` uint64_t SbSystemGetRandomUInt64() ``` -### SbSystemGetStack ### +### SbSystemGetStack Places up to `stack_size` instruction pointer addresses of the current execution stack into `out_stack`. The return value specifies the number of entries added. @@ -384,62 +384,62 @@ what it means to be async-signal-safe on POSIX: [http://pubs.opengroup.org/onlin `stack_size`: The maximum number of instruction pointer addresses to be placed into `out_stack` from the current execution stack. -#### Declaration #### +#### Declaration ``` int SbSystemGetStack(void **out_stack, int stack_size) ``` -### SbSystemGetTotalCPUMemory ### +### SbSystemGetTotalCPUMemory Returns the total CPU memory (in bytes) potentially available to this application. If the process is sandboxed to a maximum allowable limit, the function returns the lesser of the physical and sandbox limits. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalCPUMemory() ``` -### SbSystemGetTotalGPUMemory ### +### SbSystemGetTotalGPUMemory Returns the total GPU memory (in bytes) available for use by this application. This function may only be called the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetTotalGPUMemory() ``` -### SbSystemGetUsedCPUMemory ### +### SbSystemGetUsedCPUMemory Returns the total physical CPU memory (in bytes) used by this application. This value should always be less than (or, in particularly exciting situations, equal to) SbSystemGetTotalCPUMemory(). -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedCPUMemory() ``` -### SbSystemGetUsedGPUMemory ### +### SbSystemGetUsedGPUMemory Returns the current amount of GPU memory (in bytes) that is currently being used by this application. This function may only be called if the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is `true`. -#### Declaration #### +#### Declaration ``` int64_t SbSystemGetUsedGPUMemory() ``` -### SbSystemHasCapability ### +### SbSystemHasCapability Returns whether the platform has the runtime capability specified by `capability_id`. Returns false for any unknown capabilities. This implementation @@ -447,48 +447,48 @@ must be thread-safe. `capability_id`: The runtime capability to check. -#### Declaration #### +#### Declaration ``` bool SbSystemHasCapability(SbSystemCapabilityId capability_id) ``` -### SbSystemHideSplashScreen ### +### SbSystemHideSplashScreen Hides the system splash screen on systems that support a splash screen that is displayed while the application is loading. This function may be called from any thread and must be idempotent. -#### Declaration #### +#### Declaration ``` void SbSystemHideSplashScreen() ``` -### SbSystemIsDebuggerAttached ### +### SbSystemIsDebuggerAttached Attempts to determine whether the current program is running inside or attached to a debugger. The function returns `false` if neither of those cases is true. -#### Declaration #### +#### Declaration ``` bool SbSystemIsDebuggerAttached() ``` -### SbSystemNetworkIsDisconnected ### +### SbSystemNetworkIsDisconnected Returns if the device is disconnected from network. "Disconnected" is chosen over connected because disconnection can be determined with more certainty than connection usually. -#### Declaration #### +#### Declaration ``` bool SbSystemNetworkIsDisconnected() ``` -### SbSystemRaisePlatformError ### +### SbSystemRaisePlatformError Cobalt calls this function to notify the platform that an error has occurred in the application that the platform may need to handle. The platform is expected @@ -510,13 +510,13 @@ caller know that the user has reacted to the error. `user_data`: An opaque pointer that the platform should pass as an argument to the callback function, if it is called. -#### Declaration #### +#### Declaration ``` bool SbSystemRaisePlatformError(SbSystemPlatformErrorType type, SbSystemPlatformErrorCallback callback, void *user_data) ``` -### SbSystemRequestBlur ### +### SbSystemRequestBlur Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to "unfocused application" in a @@ -526,13 +526,13 @@ This function eventually causes a `kSbEventTypeBlur` event to be dispatched to the application. Before the `kSbEventTypeBlur` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestBlur() ``` -### SbSystemRequestConceal ### +### SbSystemRequestConceal Requests that the application move into the Concealed state at the next convenient point. This should roughly correspond to "minimization" in a @@ -547,13 +547,13 @@ In the Concealed state, the application will be invisible, but probably still be running background tasks. The expectation is that an external system event will bring the application out of the Concealed state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestConceal() ``` -### SbSystemRequestFocus ### +### SbSystemRequestFocus Requests that the application move into the Started state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -564,13 +564,13 @@ This function eventually causes a `kSbEventTypeFocus` event to be dispatched to the application. Before `kSbEventTypeFocus` is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFocus() ``` -### SbSystemRequestFreeze ### +### SbSystemRequestFreeze Requests that the application move into the Frozen state at the next convenient point. @@ -583,13 +583,13 @@ In the Frozen state, the application will be resident, but probably not running. The expectation is that an external system event will bring the application out of the Frozen state. -#### Declaration #### +#### Declaration ``` void SbSystemRequestFreeze() ``` -### SbSystemRequestReveal ### +### SbSystemRequestReveal Requests that the application move into the Blurred state at the next convenient point. This should roughly correspond to a "focused application" in a @@ -600,13 +600,13 @@ This function eventually causes a `kSbEventTypeReveal` event to be dispatched to the application. Before the `kSbEventTypeReveal` event is dispatched, some work may continue to be done, and unrelated system events may be dispatched. -#### Declaration #### +#### Declaration ``` void SbSystemRequestReveal() ``` -### SbSystemRequestStop ### +### SbSystemRequestStop Requests that the application be terminated gracefully at the next convenient point. In the meantime, some work may continue to be done, and unrelated system @@ -617,13 +617,13 @@ it returns `error_level`, if that has any meaning on the current platform. `error_level`: An integer that serves as the return value for the process that is eventually terminated as a result of a call to this function. -#### Declaration #### +#### Declaration ``` void SbSystemRequestStop(int error_level) ``` -### SbSystemSignWithCertificationSecretKey ### +### SbSystemSignWithCertificationSecretKey Computes a HMAC-SHA256 digest of `message` into `digest` using the application's certification secret. The `message` and the `digest` pointers must not be NULL. @@ -633,13 +633,13 @@ greater), since 32-bytes will be written into it. Returns false in the case of an error, or if it is not implemented. In this case the contents of `digest` will be undefined. -#### Declaration #### +#### Declaration ``` bool SbSystemSignWithCertificationSecretKey(const uint8_t *message, size_t message_size_in_bytes, uint8_t *digest, size_t digest_size_in_bytes) ``` -### SbSystemSupportsResume ### +### SbSystemSupportsResume Returns false if the platform doesn't need resume after suspend support. In such case Cobalt will free up the resource it retains for resume after suspend. Note @@ -647,13 +647,13 @@ that if this function returns false, the Starboard implementation cannot send kSbEventTypeResume to the event handler. The return value of this function cannot change over the life time of the application. -#### Declaration #### +#### Declaration ``` bool SbSystemSupportsResume() ``` -### SbSystemSymbolize ### +### SbSystemSymbolize Looks up `address` as an instruction pointer and places up to (`buffer_size - 1`) characters of the symbol associated with it in `out_buffer`, which must not @@ -665,7 +665,7 @@ The return value indicates whether the function found a reasonable match for This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals. -#### Declaration #### +#### Declaration ``` 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 844047739b61..81a8697bbf96 100644 --- a/cobalt/site/docs/reference/starboard/modules/thread.md +++ b/cobalt/site/docs/reference/starboard/modules/thread.md @@ -1,35 +1,35 @@ ---- -layout: doc -title: "Starboard Module Reference: thread.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `thread.h` Defines functionality related to thread creation and cleanup. -## Macros ## +## Macros -### kSbThreadContextInvalid ### +### kSbThreadContextInvalid Well-defined value for an invalid thread context. -### kSbThreadInvalidId ### +### kSbThreadInvalidId Well-defined constant value to mean "no thread ID." -### kSbThreadLocalKeyInvalid ### +### kSbThreadLocalKeyInvalid Well-defined constant value to mean "no thread local key." -### kSbThreadNoAffinity ### +### kSbThreadNoAffinity Well-defined constant value to mean "no affinity." -### kSbThreadSamplerInvalid ### +### kSbThreadSamplerInvalid Well-defined value for an invalid thread sampler. -## Enums ## +## Enums -### SbThreadPriority ### +### SbThreadPriority A spectrum of thread priorities. Platforms map them appropriately to their own priority system. Note that scheduling is platform-specific, and what these @@ -39,7 +39,7 @@ In particular, several of these priority values can map to the same priority on a given platform. The only guarantee is that each lower priority should be treated less-than-or-equal-to a higher priority. -#### Values #### +#### Values * `kSbThreadPriorityLowest` @@ -79,116 +79,116 @@ treated less-than-or-equal-to a higher priority. inherit the priority of the spawning thread, or it may mean a specific default priority, or it may mean something else, depending on the platform. -## Typedefs ## +## Typedefs -### SbThread ### +### SbThread An opaque handle to a thread type. -#### Definition #### +#### Definition ``` typedef void* SbThread ``` -### SbThreadAffinity ### +### SbThreadAffinity Type for thread core affinity. This generally will be a single cpu (or core or hyperthread) identifier. Some platforms may not support affinity, and some may have specific rules about how it must be used. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadAffinity ``` -### SbThreadContext ### +### SbThreadContext A handle to the context of a frozen thread. -#### Definition #### +#### Definition ``` typedef SbThreadContextPrivate* SbThreadContext ``` -### SbThreadEntryPoint ### +### SbThreadEntryPoint Function pointer type for SbThreadCreate. `context` is a pointer-sized bit of data passed in from the calling thread. -#### Definition #### +#### Definition ``` typedef void*(* SbThreadEntryPoint) (void *context) ``` -### SbThreadId ### +### SbThreadId An ID type that is unique per thread. -#### Definition #### +#### Definition ``` typedef int32_t SbThreadId ``` -### SbThreadLocalDestructor ### +### SbThreadLocalDestructor Function pointer type for Thread-Local destructors. -#### Definition #### +#### Definition ``` typedef void(* SbThreadLocalDestructor) (void *value) ``` -### SbThreadLocalKey ### +### SbThreadLocalKey A handle to a thread-local key. -#### Definition #### +#### Definition ``` typedef SbThreadLocalKeyPrivate* SbThreadLocalKey ``` -### SbThreadSampler ### +### SbThreadSampler A handle to a thread sampler. -#### Definition #### +#### Definition ``` typedef SbThreadSamplerPrivate* SbThreadSampler ``` -## Functions ## +## Functions -### SbThreadContextGetPointer ### +### SbThreadContextGetPointer Gets the specified pointer-type `property` from the specified `context`. Returns `true` if successful and `out_value` has been modified, otherwise returns `false` and `out_value` is not modified. -#### Declaration #### +#### Declaration ``` bool SbThreadContextGetPointer(SbThreadContext context, SbThreadContextProperty property, void **out_value) ``` -### SbThreadContextIsValid ### +### SbThreadContextIsValid Returns whether the given thread context is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadContextIsValid(SbThreadContext context) ``` -### SbThreadCreate ### +### SbThreadCreate Creates a new thread, which starts immediately. @@ -214,13 +214,13 @@ used in production builds. `entry_point`: A pointer to a function that will be executed on the newly created thread. `context`: This value will be passed to the `entry_point` function. -#### Declaration #### +#### Declaration ``` SbThread SbThreadCreate(int64_t stack_size, SbThreadPriority priority, SbThreadAffinity affinity, bool joinable, const char *name, SbThreadEntryPoint entry_point, void *context) ``` -### SbThreadCreateLocalKey ### +### SbThreadCreateLocalKey Creates and returns a new, unique key for thread local data. If the function does not succeed, the function returns `kSbThreadLocalKeyInvalid`. @@ -233,13 +233,13 @@ value is not NULL. `destructor`: A pointer to a function. The value may be NULL if no clean up is needed. -#### Declaration #### +#### Declaration ``` SbThreadLocalKey SbThreadCreateLocalKey(SbThreadLocalDestructor destructor) ``` -### SbThreadDestroyLocalKey ### +### SbThreadDestroyLocalKey Destroys thread local data for the specified key. The function is a no-op if the key is invalid (kSbThreadLocalKeyInvalid`) or has already been destroyed. This @@ -247,13 +247,13 @@ function does NOT call the destructor on any stored values. `key`: The key for which to destroy thread local data. -#### Declaration #### +#### Declaration ``` void SbThreadDestroyLocalKey(SbThreadLocalKey key) ``` -### SbThreadDetach ### +### SbThreadDetach Detaches `thread`, which prevents it from being joined. This is sort of like a non-blocking join. This function is a no-op if the thread is already detached or @@ -261,33 +261,33 @@ if the thread is already being joined by another thread. `thread`: The thread to be detached. -#### Declaration #### +#### Declaration ``` void SbThreadDetach(SbThread thread) ``` -### SbThreadGetCurrent ### +### SbThreadGetCurrent Returns the handle of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThread SbThreadGetCurrent() ``` -### SbThreadGetId ### +### SbThreadGetId Returns the Thread ID of the currently executing thread. -#### Declaration #### +#### Declaration ``` SbThreadId SbThreadGetId() ``` -### SbThreadGetLocalValue ### +### SbThreadGetLocalValue Returns the pointer-sized value for `key` in the currently executing thread's local storage. Returns `NULL` if key is `kSbThreadLocalKeyInvalid` or if the key @@ -295,97 +295,97 @@ has already been destroyed. `key`: The key for which to return the value. -#### Declaration #### +#### Declaration ``` void* SbThreadGetLocalValue(SbThreadLocalKey key) ``` -### SbThreadGetName ### +### SbThreadGetName Returns the debug name of the currently executing thread. -#### Declaration #### +#### Declaration ``` void SbThreadGetName(char *buffer, int buffer_size) ``` -### SbThreadIsCurrent ### +### SbThreadIsCurrent Returns whether `thread` is the current thread. `thread`: The thread to check. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsCurrent(SbThread thread) ``` -### SbThreadIsEqual ### +### SbThreadIsEqual Indicates whether `thread1` and `thread2` refer to the same thread. `thread1`: The first thread to compare. `thread2`: The second thread to compare. -#### Declaration #### +#### Declaration ``` bool SbThreadIsEqual(SbThread thread1, SbThread thread2) ``` -### SbThreadIsValid ### +### SbThreadIsValid Returns whether the given thread handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValid(SbThread thread) ``` -### SbThreadIsValidAffinity ### +### SbThreadIsValidAffinity Returns whether the given thread affinity is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidAffinity(SbThreadAffinity affinity) ``` -### SbThreadIsValidId ### +### SbThreadIsValidId Returns whether the given thread ID is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidId(SbThreadId id) ``` -### SbThreadIsValidLocalKey ### +### SbThreadIsValidLocalKey Returns whether the given thread local variable key is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidLocalKey(SbThreadLocalKey key) ``` -### SbThreadIsValidPriority ### +### SbThreadIsValidPriority Returns whether the given thread priority is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadIsValidPriority(SbThreadPriority priority) ``` -### SbThreadJoin ### +### SbThreadJoin Joins the thread on which this function is called with joinable `thread`. This function blocks the caller until the designated thread exits, and then cleans up @@ -403,36 +403,36 @@ must have been created with SbThreadCreate. `out_return`: If this is not `NULL`, then the SbThreadJoin function populates it with the return value of the thread's `main` function. -#### Declaration #### +#### Declaration ``` bool SbThreadJoin(SbThread thread, void **out_return) ``` -### SbThreadSamplerCreate ### +### SbThreadSamplerCreate Creates a new thread sampler for the specified `thread`. If successful, this function returns the newly created handle. If unsuccessful, this function returns `kSbThreadSamplerInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadSampler SbThreadSamplerCreate(SbThread thread) ``` -### SbThreadSamplerDestroy ### +### SbThreadSamplerDestroy Destroys the `sampler` and frees whatever resources it was using. -#### Declaration #### +#### Declaration ``` void SbThreadSamplerDestroy(SbThreadSampler sampler) ``` -### SbThreadSamplerFreeze ### +### SbThreadSamplerFreeze Suspends execution of the thread that `sampler` was created for. @@ -440,47 +440,47 @@ If successful, this function returns a `SbThreadContext` for the frozen thread, from which properties may be read while the thread remains frozen. If unsuccessful, this function returns `kSbThreadContextInvalid`. -#### Declaration #### +#### Declaration ``` SbThreadContext SbThreadSamplerFreeze(SbThreadSampler sampler) ``` -### SbThreadSamplerIsSupported ### +### SbThreadSamplerIsSupported Whether the current platform supports thread sampling. The result of this function must not change over the course of the program, which means that the results of this function may be cached indefinitely. If this returns false, `SbThreadSamplerCreate` will return an invalid sampler. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerIsSupported() ``` -### SbThreadSamplerIsValid ### +### SbThreadSamplerIsValid Returns whether the given thread sampler is valid. -#### Declaration #### +#### Declaration ``` static bool SbThreadSamplerIsValid(SbThreadSampler sampler) ``` -### SbThreadSamplerThaw ### +### SbThreadSamplerThaw Resumes execution of the thread that `sampler` was created for. This invalidates the context returned from `SbThreadSamplerFreeze`. -#### Declaration #### +#### Declaration ``` bool SbThreadSamplerThaw(SbThreadSampler sampler) ``` -### SbThreadSetLocalValue ### +### SbThreadSetLocalValue Sets the pointer-sized value for `key` in the currently executing thread's local storage. The return value indicates whether `key` is valid and has not already @@ -489,26 +489,26 @@ been destroyed. `key`: The key for which to set the key value. `value`: The new pointer-sized key value. -#### Declaration #### +#### Declaration ``` bool SbThreadSetLocalValue(SbThreadLocalKey key, void *value) ``` -### SbThreadSetName ### +### SbThreadSetName Sets the debug name of the currently executing thread by copying the specified name string. `name`: The name to assign to the thread. -#### Declaration #### +#### Declaration ``` void SbThreadSetName(const char *name) ``` -### SbThreadSleep ### +### SbThreadSleep Sleeps the currently executing thread. @@ -516,17 +516,17 @@ Sleeps the currently executing thread. executing thread should sleep. The function is a no-op if this value is negative or `0`. -#### Declaration #### +#### Declaration ``` void SbThreadSleep(SbTime duration) ``` -### SbThreadYield ### +### SbThreadYield Yields the currently executing thread, so another thread has a chance to run. -#### Declaration #### +#### Declaration ``` void SbThreadYield() diff --git a/cobalt/site/docs/reference/starboard/modules/time.md b/cobalt/site/docs/reference/starboard/modules/time.md index 17ea6ad5d004..e5c8cd2fedd0 100644 --- a/cobalt/site/docs/reference/starboard/modules/time.md +++ b/cobalt/site/docs/reference/starboard/modules/time.md @@ -1,59 +1,59 @@ ---- -layout: doc -title: "Starboard Module Reference: time.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time.h` Provides access to system time and timers. -## Macros ## +## Macros -### kSbTimeDay ### +### kSbTimeDay One day in SbTime units (microseconds). -### kSbTimeHour ### +### kSbTimeHour One hour in SbTime units (microseconds). -### kSbTimeMax ### +### kSbTimeMax The maximum value of an SbTime. -### kSbTimeMillisecond ### +### kSbTimeMillisecond One millisecond in SbTime units (microseconds). -### kSbTimeMinute ### +### kSbTimeMinute One minute in SbTime units (microseconds). -### kSbTimeNanosecondsPerMicrosecond ### +### kSbTimeNanosecondsPerMicrosecond How many nanoseconds in one SbTime unit (microseconds). -### kSbTimeSecond ### +### kSbTimeSecond One second in SbTime units (microseconds). -### kSbTimeToPosixDelta ### +### kSbTimeToPosixDelta A term that can be added to an SbTime to convert it into the number of microseconds since the POSIX epoch. -## Typedefs ## +## Typedefs -### SbTime ### +### SbTime The number of microseconds since the epoch of January 1, 1601 UTC, or the number of microseconds between two times. Always microseconds, ALWAYS UTC. -#### Definition #### +#### Definition ``` typedef int64_t SbTime ``` -### SbTimeMonotonic ### +### SbTimeMonotonic A number of microseconds from some point. The main property of this time is that it increases monotonically. It should also be as high-resolution a timer as we @@ -61,38 +61,38 @@ can get on a platform. So, it is good for measuring the time between two calls without worrying about a system clock adjustment. It's not good for getting the wall clock time. -#### Definition #### +#### Definition ``` typedef int64_t SbTimeMonotonic ``` -## Functions ## +## Functions -### SbTimeFromPosix ### +### SbTimeFromPosix Converts microseconds from the POSIX epoch into an `SbTime`. `time`: A time that measures the number of microseconds since January 1, 1970, 00:00:00, UTC. -#### Declaration #### +#### Declaration ``` static SbTime SbTimeFromPosix(int64_t time) ``` -### SbTimeGetMonotonicNow ### +### SbTimeGetMonotonicNow Gets a monotonically increasing time representing right now. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicNow() ``` -### SbTimeGetMonotonicThreadNow ### +### SbTimeGetMonotonicThreadNow Gets a monotonically increasing time representing how long the current thread has been in the executing state (i.e. not pre-empted nor waiting on an event). @@ -100,44 +100,44 @@ This is not necessarily total time and is intended to allow measuring thread execution time between two timestamps. If this is not available then SbTimeGetMonotonicNow() should be used. -#### Declaration #### +#### Declaration ``` SbTimeMonotonic SbTimeGetMonotonicThreadNow() ``` -### SbTimeGetNow ### +### SbTimeGetNow Gets the current system time as an `SbTime`. -#### Declaration #### +#### Declaration ``` SbTime SbTimeGetNow() ``` -### SbTimeIsTimeThreadNowSupported ### +### SbTimeIsTimeThreadNowSupported Returns whether the current platform supports time thread now -#### Declaration #### +#### Declaration ``` bool SbTimeIsTimeThreadNowSupported() ``` -### SbTimeNarrow ### +### SbTimeNarrow Safely narrows a number from a more precise unit to a less precise one. This function rounds negative values toward negative infinity. -#### Declaration #### +#### Declaration ``` static int64_t SbTimeNarrow(int64_t time, int64_t divisor) ``` -### SbTimeToPosix ### +### SbTimeToPosix Converts `SbTime` into microseconds from the POSIX epoch. @@ -145,7 +145,7 @@ Converts `SbTime` into microseconds from the POSIX epoch. January 1, 1601, UTC, or that measures the number of microseconds between two times. -#### Declaration #### +#### Declaration ``` static int64_t SbTimeToPosix(SbTime time) diff --git a/cobalt/site/docs/reference/starboard/modules/time_zone.md b/cobalt/site/docs/reference/starboard/modules/time_zone.md index 5768bc358b3b..e82ca6dcbfe2 100644 --- a/cobalt/site/docs/reference/starboard/modules/time_zone.md +++ b/cobalt/site/docs/reference/starboard/modules/time_zone.md @@ -1,38 +1,38 @@ ---- -layout: doc -title: "Starboard Module Reference: time_zone.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `time_zone.h` Provides access to the system time zone information. -## Typedefs ## +## Typedefs -### SbTimeZone ### +### SbTimeZone 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). -#### Definition #### +#### Definition ``` typedef int SbTimeZone ``` -## Functions ## +## Functions -### SbTimeZoneGetCurrent ### +### SbTimeZoneGetCurrent Gets the system's current SbTimeZone in minutes. -#### Declaration #### +#### Declaration ``` SbTimeZone SbTimeZoneGetCurrent() ``` -### SbTimeZoneGetName ### +### 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 @@ -40,7 +40,7 @@ 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". -#### Declaration #### +#### Declaration ``` const char* SbTimeZoneGetName() diff --git a/cobalt/site/docs/reference/starboard/modules/types.md b/cobalt/site/docs/reference/starboard/modules/types.md index 90867a69542f..e1f372cc60c4 100644 --- a/cobalt/site/docs/reference/starboard/modules/types.md +++ b/cobalt/site/docs/reference/starboard/modules/types.md @@ -1,15 +1,15 @@ ---- -layout: doc -title: "Starboard Module Reference: types.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `types.h` Provides a suite of standard types that should be universally available on all platforms, specifically focused on explicitly-sized integer types and booleans. This module also includes some related ubiquitous definitions like limits of the explicitly-sized integer types, and standard pointer and int32 sentinel values. -## Macros ## +## Macros -### kSbInvalidInt ### +### kSbInvalidInt A value that represents an int that is probably invalid. diff --git a/cobalt/site/docs/reference/starboard/modules/ui_navigation.md b/cobalt/site/docs/reference/starboard/modules/ui_navigation.md index a0ecfb1eafb8..cb4176713005 100644 --- a/cobalt/site/docs/reference/starboard/modules/ui_navigation.md +++ b/cobalt/site/docs/reference/starboard/modules/ui_navigation.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: ui_navigation.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `ui_navigation.h` API to allow applications to take advantage of the platform's native UI engine. This is mainly to drive the animation of visual elements and to signal which of @@ -19,20 +19,20 @@ SbUiNavItem in case the native UI engine moves individual items in response to user interaction. If the navigation item is a container, then the content offset will also be queried to determine the placement of its content items. -## Macros ## +## Macros -### kSbUiNavItemInvalid ### +### kSbUiNavItemInvalid Well-defined value for an invalid navigation item. -## Enums ## +## Enums -### SbUiNavItemType ### +### SbUiNavItemType Navigation items may be one of the following types. This must be specified upon item creation and may not change during the item's lifespan. -#### Values #### +#### Values * `kSbUiNavItemTypeFocus` @@ -42,29 +42,29 @@ item creation and may not change during the item's lifespan. This is a container of navigation items which can also be containers themselves or focusable items. Containers themselves cannot be focused. -## Typedefs ## +## Typedefs -### SbUiNavItem ### +### SbUiNavItem An opaque handle to an implementation-private structure representing a navigation item. -#### Definition #### +#### Definition ``` typedef struct SbUiNavItemPrivate* SbUiNavItem ``` -## Structs ## +## Structs -### SbUiNavCallbacks ### +### SbUiNavCallbacks This structure specifies all the callbacks which the platform UI engine should invoke for various interaction events on navigation items. These callbacks may be invoked from any thread at any frequency. The `callback_context` is the value that was passed on creation of the relevant SbUiNavItem. -#### Members #### +#### Members * `void(*onblur)(SbUiNavItem item, void *callback_context)` @@ -77,12 +77,12 @@ that was passed on creation of the relevant SbUiNavItem. Invoke when an item's content offset is changed. This is only used with container items. -### SbUiNavInterface ### +### SbUiNavInterface This structure declares the interface to the UI navigation implementation. All function pointers must be specified if the platform supports UI navigation. -#### Members #### +#### Members * `SbUiNavItem(*create_item)(SbUiNavItemType type, const SbUiNavCallbacks *callbacks, void *callback_context)` @@ -237,7 +237,7 @@ function pointers must be specified if the platform supports UI navigation. Call `update_function` with `context` to perform a series of UI navigation changes atomically before returning. -### SbUiNavItemDir ### +### SbUiNavItemDir Navigation items of type kSbUiNavItemTypeContainer have directionality. If directionality is not specified for a container, it should default to left-to- @@ -270,12 +270,12 @@ right and top-to-bottom. Bottom-to-top is similar to right-to-left, but for the Y position. ``` -#### Members #### +#### Members * `bool is_left_to_right` * `bool is_top_to_bottom` -### SbUiNavMatrix2x3 ### +### SbUiNavMatrix2x3 This represents a 2x3 transform matrix in row-major order. @@ -284,38 +284,38 @@ This represents a 2x3 transform matrix in row-major order. /// | c d ty | ``` -#### Members #### +#### Members * `float m` -### SbUiNavMatrix4 ### +### SbUiNavMatrix4 This represents a 4x4 transform matrix in row-major order. -#### Members #### +#### Members * `float m` -## Functions ## +## Functions -### SbUiNavGetInterface ### +### SbUiNavGetInterface Retrieve the platform's UI navigation implementation. If the platform does not provide one, then return false without modifying `out_interface`. Otherwise, initialize all members of `out_interface` and return true. The `out_interface` pointer must not be NULL. -#### Declaration #### +#### Declaration ``` bool SbUiNavGetInterface(SbUiNavInterface *out_interface) ``` -### SbUiNavItemIsValid ### +### SbUiNavItemIsValid Returns whether the given navigation item handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbUiNavItemIsValid(SbUiNavItem item) diff --git a/cobalt/site/docs/reference/starboard/modules/user.md b/cobalt/site/docs/reference/starboard/modules/user.md index a30cc95b00f9..9442ced8f978 100644 --- a/cobalt/site/docs/reference/starboard/modules/user.md +++ b/cobalt/site/docs/reference/starboard/modules/user.md @@ -1,7 +1,7 @@ ---- -layout: doc -title: "Starboard Module Reference: user.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `user.h` Defines a user management API. This module defines functions only for managing signed-in users. Platforms that do not have users must still implement this API, @@ -10,19 +10,19 @@ always reporting a single user that is current and signed in. These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls. -## Macros ## +## Macros -### kSbUserInvalid ### +### kSbUserInvalid Well-defined value for an invalid user. -## Enums ## +## Enums -### SbUserPropertyId ### +### SbUserPropertyId A set of string properties that can be queried on a user. -#### Values #### +#### Values * `kSbUserPropertyAvatarUrl` @@ -38,21 +38,21 @@ A set of string properties that can be queried on a user. A unique user ID of a user. -## Typedefs ## +## Typedefs -### SbUser ### +### SbUser A handle to a user. -#### Definition #### +#### Definition ``` typedef SbUserPrivate* SbUser ``` -## Functions ## +## Functions -### SbUserGetCurrent ### +### SbUserGetCurrent Gets the current primary user, if one exists. This is the user that is determined, in a platform-specific way, to be the primary user controlling the @@ -63,13 +63,13 @@ appropriate for the platform. It is expected that there will be a unique SbUser per signed-in user, and that the referenced objects will persist for the lifetime of the app. -#### Declaration #### +#### Declaration ``` SbUser SbUserGetCurrent() ``` -### SbUserGetProperty ### +### SbUserGetProperty Retrieves the value of `property_id` for `user` and places it in `out_value`. The function returns: @@ -83,13 +83,13 @@ The function returns: The property for which the data is requested. `out_value`: The retrieved property value. `value_size`: The size of the retrieved property value. -#### Declaration #### +#### Declaration ``` bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) ``` -### SbUserGetPropertySize ### +### SbUserGetPropertySize Returns the size of the value of `property_id` for `user`, INCLUDING the terminating null character. The function returns `0` if `user` is invalid or if @@ -98,13 +98,13 @@ terminating null character. The function returns `0` if `user` is invalid or if `user`: The user for which property size data is being retrieved. `property_id`: The property for which the data is requested. -#### Declaration #### +#### Declaration ``` int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) ``` -### SbUserGetSignedIn ### +### SbUserGetSignedIn Gets a list of up to `users_size` signed-in users and places the results in `out_users`. The return value identifies the actual number of signed-in users, @@ -116,17 +116,17 @@ the referenced objects will persist for the lifetime of the app. `out_users`: Handles for the retrieved users. `users_size`: The maximum number of signed-in users to retrieve. -#### Declaration #### +#### Declaration ``` int SbUserGetSignedIn(SbUser *out_users, int users_size) ``` -### SbUserIsValid ### +### SbUserIsValid Returns whether the given user handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbUserIsValid(SbUser user) diff --git a/cobalt/site/docs/reference/starboard/modules/window.md b/cobalt/site/docs/reference/starboard/modules/window.md index 53cda4a6d17e..af49c22be727 100644 --- a/cobalt/site/docs/reference/starboard/modules/window.md +++ b/cobalt/site/docs/reference/starboard/modules/window.md @@ -1,40 +1,40 @@ ---- -layout: doc -title: "Starboard Module Reference: window.h" ---- +Project: /youtube/cobalt/_project.yaml +Book: /youtube/cobalt/_book.yaml + +# Starboard Module Reference: `window.h` Provides functionality to handle Window creation and management. -## Macros ## +## Macros -### kSbEventOnScreenKeyboardInvalidTicket ### +### kSbEventOnScreenKeyboardInvalidTicket System-triggered OnScreenKeyboard events have ticket value kSbEventOnScreenKeyboardInvalidTicket. -### kSbWindowInvalid ### +### kSbWindowInvalid Well-defined value for an invalid window handle. -## Typedefs ## +## Typedefs -### SbWindow ### +### SbWindow A handle to a window. -#### Definition #### +#### Definition ``` typedef SbWindowPrivate* SbWindow ``` -## Structs ## +## Structs -### SbWindowOptions ### +### SbWindowOptions Options that can be requested at window creation time. -#### Members #### +#### Members * `SbWindowSize size` @@ -48,25 +48,25 @@ Options that can be requested at window creation time. The name of the window to create. -### SbWindowRect ### +### SbWindowRect Defines a rectangle via a point `(x, y)` and a size `(width, height)`. This structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect. -#### Members #### +#### Members * `float x` * `float y` * `float width` * `float height` -### SbWindowSize ### +### SbWindowSize The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window. -#### Members #### +#### Members * `int width` @@ -93,9 +93,9 @@ that would be created to back that window. A value of 0.0f means the ratio could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f). -## Functions ## +## Functions -### SbWindowBlurOnScreenKeyboard ### +### SbWindowBlurOnScreenKeyboard Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred. kSbEventTypeOnScreenKeyboardBlurred has data `ticket`. Calling @@ -103,13 +103,13 @@ 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 #### +#### Declaration ``` void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowCreate ### +### SbWindowCreate Creates and returns a new system window with the given `options`, which may be `NULL`. The function returns `kSbWindowInvalid` if it cannot create the @@ -131,25 +131,25 @@ entry point. `options`: Options that specify parameters for the window being created. -#### Declaration #### +#### Declaration ``` SbWindow SbWindowCreate(const SbWindowOptions *options) ``` -### SbWindowDestroy ### +### SbWindowDestroy Destroys `window`, reclaiming associated resources. `window`: The `SbWindow` to destroy. -#### Declaration #### +#### Declaration ``` bool SbWindowDestroy(SbWindow window) ``` -### SbWindowFocusOnScreenKeyboard ### +### SbWindowFocusOnScreenKeyboard Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused. kSbEventTypeOnScreenKeyboardFocused has data `ticket`. Calling @@ -157,38 +157,38 @@ 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 #### +#### Declaration ``` void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowGetDiagonalSizeInInches ### +### SbWindowGetDiagonalSizeInInches Gets the size of the diagonal between two opposing screen corners. A return value of 0 means that starboard does not know what the screen diagonal is. -#### Declaration #### +#### Declaration ``` float SbWindowGetDiagonalSizeInInches(SbWindow window) ``` -### SbWindowGetOnScreenKeyboardBoundingRect ### +### 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 #### +#### Declaration ``` bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect) ``` -### SbWindowGetPlatformHandle ### +### SbWindowGetPlatformHandle Gets the platform-specific handle for `window`, which can be passed as an EGLNativeWindowType to initialize EGL/GLES. This return value is entirely @@ -196,13 +196,13 @@ platform-specific, so there are no constraints about expected ranges. `window`: The SbWindow to retrieve the platform handle for. -#### Declaration #### +#### Declaration ``` void* SbWindowGetPlatformHandle(SbWindow window) ``` -### SbWindowGetSize ### +### SbWindowGetSize Retrieves the dimensions of `window` and sets `size` accordingly. This function returns `true` if it completes successfully. If the function returns `false`, @@ -210,81 +210,81 @@ then `size` will not have been modified. `window`: The SbWindow to retrieve the size of. `size`: The retrieved size. -#### Declaration #### +#### Declaration ``` bool SbWindowGetSize(SbWindow window, SbWindowSize *size) ``` -### SbWindowHideOnScreenKeyboard ### +### 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 #### +#### Declaration ``` void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket) ``` -### SbWindowIsOnScreenKeyboardShown ### +### SbWindowIsOnScreenKeyboardShown Determine if the on screen keyboard is shown. -#### Declaration #### +#### Declaration ``` bool SbWindowIsOnScreenKeyboardShown(SbWindow window) ``` -### SbWindowIsValid ### +### SbWindowIsValid Returns whether the given window handle is valid. -#### Declaration #### +#### Declaration ``` static bool SbWindowIsValid(SbWindow window) ``` -### SbWindowOnScreenKeyboardIsSupported ### +### SbWindowOnScreenKeyboardIsSupported Return whether the current platform supports an on screen keyboard -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardIsSupported() ``` -### SbWindowOnScreenKeyboardSuggestionsSupported ### +### SbWindowOnScreenKeyboardSuggestionsSupported Determine if the on screen keyboard has suggestions implemented. If this returns false, then calling SbWindowUpdateOnScreenKeyboardSuggestions() will be undefined. -#### Declaration #### +#### Declaration ``` bool SbWindowOnScreenKeyboardSuggestionsSupported(SbWindow window) ``` -### SbWindowSetDefaultOptions ### +### SbWindowSetDefaultOptions Sets the default options for system windows. `options`: The option values to use as default values. This object must not be `NULL`. -#### Declaration #### +#### Declaration ``` void SbWindowSetDefaultOptions(SbWindowOptions *options) ``` -### SbWindowSetOnScreenKeyboardKeepFocus ### +### 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 @@ -293,13 +293,13 @@ OnScreenKeyboard via input; focus may only be moved via events sent by the app. OnScreenKeyboard via input. `keepFocus` is initialized to false in the OnScreenKeyboard constructor. -#### Declaration #### +#### Declaration ``` void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus) ``` -### SbWindowShowOnScreenKeyboard ### +### SbWindowShowOnScreenKeyboard Show the on screen keyboard and populate the input with text `input_text`. Fire kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary. @@ -309,13 +309,13 @@ 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 #### +#### Declaration ``` void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket) ``` -### SbWindowUpdateOnScreenKeyboardSuggestions ### +### SbWindowUpdateOnScreenKeyboardSuggestions Update the on screen keyboard custom suggestions. Fire kSbEventTypeOnScreenKeyboardSuggestionsUpdated. @@ -323,7 +323,7 @@ kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data `ticket`. The suggestions should remain up-to-date when the keyboard is shown after being hidden. -#### Declaration #### +#### Declaration ``` void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions[], int num_suggestions, int ticket) diff --git a/starboard/build/doc/migration_changes.md b/starboard/build/doc/migration_changes.md index c63a3bf1ee82..c58729abae80 100644 --- a/starboard/build/doc/migration_changes.md +++ b/starboard/build/doc/migration_changes.md @@ -42,7 +42,7 @@ variables. ## Notes: * *Starboard Implementation:* If your platform defined - `STARBOARD_IMPLENTATION` in its implementation, you would now add the above + `STARBOARD_IMPLEMENTATION` in its implementation, you would now add the above config with `configs += ["//starboard/build/config:starboard_implementation"]`. diff --git a/starboard/doc/evergreen/cobalt_evergreen_lite.md b/starboard/doc/evergreen/cobalt_evergreen_lite.md index 06dacf953fb9..7e2b9e734e58 100644 --- a/starboard/doc/evergreen/cobalt_evergreen_lite.md +++ b/starboard/doc/evergreen/cobalt_evergreen_lite.md @@ -1,4 +1,4 @@ -Evergreen Lite Partner Doc +# Evergreen Lite Partner Doc ## What is Cobalt Evergreen Lite?