| // Copyright 2020 The Cobalt Authors. All Rights Reserved. | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| #ifndef COBALT_EXTENSION_CONFIGURATION_H_ | |
| #define COBALT_EXTENSION_CONFIGURATION_H_ | |
| #include <stdint.h> | |
| #include "starboard/configuration.h" | |
| #ifdef __cplusplus | |
| extern "C" { | |
| #endif | |
| #define kCobaltExtensionConfigurationName "dev.cobalt.extension.Configuration" | |
| typedef struct CobaltExtensionConfigurationApi { | |
| // Name should be the string |kCobaltExtensionConfigurationName|. | |
| // This helps to validate that the extension API is correct. | |
| const char* name; | |
| // This specifies the version of the API that is implemented. | |
| uint32_t version; | |
| // The fields below this point were added in version 1 or later. | |
| // The functions below configure Cobalt. All correspond to some GYP variable, | |
| // but the implementation of this functions will take precedence over the GYP | |
| // variable. | |
| // This variable defines what Cobalt's preferred strategy should be for | |
| // handling internally triggered application exit requests (e.g. the user | |
| // chooses to back out of the application). | |
| // 'stop' -- The application should call SbSystemRequestStop() on exit, | |
| // resulting in a complete shutdown of the application. | |
| // 'suspend' -- The application should call SbSystemRequestSuspend() on | |
| // exit, resulting in the application being "minimized". | |
| // 'noexit' -- The application should never allow the user to trigger an | |
| // exit, this will be managed by the system. | |
| const char* (*CobaltUserOnExitStrategy)(); | |
| // If set to |true|, will enable support for rendering only the regions of | |
| // the display that are modified due to animations, instead of re-rendering | |
| // the entire scene each frame. This feature can reduce startup time where | |
| // usually there is a small loading spinner animating on the screen. On GLES | |
| // renderers, Cobalt will attempt to implement this support by using | |
| // eglSurfaceAttrib(..., EGL_SWAP_BEHAVIOR, EGL_BUFFER_PRESERVED), otherwise | |
| // the dirty region will be silently disabled. On Blitter API platforms, | |
| // if this is enabled, we explicitly create an extra offscreen full-size | |
| // intermediate surface to render into. Note that some GLES driver | |
| // implementations may internally allocate an extra full screen surface to | |
| // support this feature, and many have been noticed to not properly support | |
| // this functionality (but they report that they do), and for these reasons | |
| // this value is defaulted to |false|. | |
| bool (*CobaltRenderDirtyRegionOnly)(); | |
| // Cobalt will call eglSwapInterval() and specify this value before calling | |
| // eglSwapBuffers() each frame. | |
| int (*CobaltEglSwapInterval)(); | |
| // The URL of default build time splash screen - see | |
| // cobalt/doc/splash_screen.md for information about this. | |
| const char* (*CobaltFallbackSplashScreenUrl)(); | |
| // If set to |true|, enables Quic. | |
| bool (*CobaltEnableQuic)(); | |
| // Cache parameters | |
| // The following set of parameters define how much memory is reserved for | |
| // different Cobalt caches. These caches affect CPU *and* GPU memory usage. | |
| // | |
| // The sum of the following caches effectively describes the maximum GPU | |
| // texture memory usage (though it doesn't consider video textures and | |
| // display color buffers): | |
| // - CobaltSkiaCacheSizeInBytes (GLES2 rasterizer only) | |
| // - CobaltImageCacheSizeInBytes | |
| // - CobaltSkiaGlyphAtlasWidth * CobaltSkiaGlyphAtlasHeight | |
| // | |
| // The other caches affect CPU memory usage. | |
| // Determines the capacity of the skia cache. The Skia cache is maintained | |
| // within Skia and is used to cache the results of complicated effects such | |
| // as shadows, so that Skia draw calls that are used repeatedly across | |
| // frames can be cached into surfaces. This setting is only relevant when | |
| // using the hardware-accelerated Skia rasterizer (e.g. as opposed to the | |
| // Blitter API). | |
| int (*CobaltSkiaCacheSizeInBytes)(); | |
| // Determines the amount of GPU memory the offscreen target atlases will | |
| // use. This is specific to the direct-GLES rasterizer and caches any render | |
| // tree nodes which require skia for rendering. Two atlases will be allocated | |
| // from this memory or multiple atlases of the frame size if the limit | |
| // allows. It is recommended that enough memory be reserved for two RGBA | |
| // atlases about a quarter of the frame size. | |
| int (*CobaltOffscreenTargetCacheSizeInBytes)(); | |
| // Determines the capacity of the encoded image cache, which manages encoded | |
| // images downloaded from a web page. These images are cached within CPU | |
| // memory. This not only reduces network traffic to download the encoded | |
| // images, but also allows the downloaded images to be held during suspend. | |
| // Note that there is also a cache for the decoded images whose capacity is | |
| // specified in |CobaltImageCacheSizeInBytes|. The decoded images are often | |
| // cached in the GPU memory and will be released during suspend. | |
| // | |
| // If a system meets the following requirements: | |
| // 1. Has a fast image decoder. | |
| // 2. Has enough CPU memory, or has a unified memory architecture that allows | |
| // sharing of CPU and GPU memory. | |
| // Then it may consider implementing |CobaltEncodedImageCacheSizeInBytes| to | |
| // return a much bigger value, and set the return value of | |
| // |CobaltImageCacheSizeInBytes| to a much smaller value. This allows the app | |
| // to cache significantly more images. | |
| // | |
| // Setting this to 0 can disable the cache completely. | |
| int (*CobaltEncodedImageCacheSizeInBytes)(); | |
| // Determines the capacity of the image cache, which manages image surfaces | |
| // downloaded from a web page. While it depends on the platform, often (and | |
| // ideally) these images are cached within GPU memory. | |
| // Set to -1 to automatically calculate the value at runtime, based on | |
| // features like windows dimensions and the value of | |
| // SbSystemGetTotalGPUMemory(). | |
| int (*CobaltImageCacheSizeInBytes)(); | |
| // Determines the capacity of the local font cache, which manages all fonts | |
| // loaded from local files. Newly encountered sections of font files are | |
| // lazily loaded into the cache, enabling subsequent requests to the same | |
| // file sections to be handled via direct memory access. Once the limit is | |
| // reached, further requests are handled via file stream. | |
| // Setting the value to 0 disables memory caching and causes all font file | |
| // accesses to be done using file streams. | |
| int (*CobaltLocalTypefaceCacheSizeInBytes)(); | |
| // Determines the capacity of the remote font cache, which manages all | |
| // fonts downloaded from a web page. | |
| int (*CobaltRemoteTypefaceCacheSizeInBytes)(); | |
| // Determines the capacity of the mesh cache. Each mesh is held compressed | |
| // in main memory, to be inflated into a GPU buffer when needed for | |
| // projection. | |
| int (*CobaltMeshCacheSizeInBytes)(); | |
| // Only relevant if you are using the Blitter API. | |
| // Determines the capacity of the software surface cache, which is used to | |
| // cache all surfaces that are rendered via a software rasterizer to avoid | |
| // re-rendering them. | |
| int (*CobaltSoftwareSurfaceCacheSizeInBytes)(); | |
| // Modifying this function's return value to be non-1.0f will result in the | |
| // image cache capacity being cleared and then temporarily reduced for the | |
| // duration that a video is playing. This can be useful for some platforms | |
| // if they are particularly constrained for (GPU) memory during video | |
| // playback. When playing a video, the image cache is reduced to: | |
| // CobaltImageCacheSizeInBytes() * | |
| // CobaltImageCacheCapacityMultiplierWhenPlayingVideo(). | |
| float (*CobaltImageCacheCapacityMultiplierWhenPlayingVideo)(); | |
| // Determines the size in pixels of the glyph atlas where rendered glyphs are | |
| // cached. The resulting memory usage is 2 bytes of GPU memory per pixel. | |
| // When a value is used that is too small, thrashing may occur that will | |
| // result in visible stutter. Such thrashing is more likely to occur when CJK | |
| // language glyphs are rendered and when the size of the glyphs in pixels is | |
| // larger, such as for higher resolution displays. | |
| // The negative default values indicates to the engine that these settings | |
| // should be automatically set. | |
| int (*CobaltSkiaGlyphAtlasWidth)(); | |
| int (*CobaltSkiaGlyphAtlasHeight)(); | |
| // This configuration has been deprecated and is only kept for | |
| // backward-compatibility. It has no effect on V8. | |
| int (*CobaltJsGarbageCollectionThresholdInBytes)(); | |
| // When specified this value will reduce the cpu memory consumption by | |
| // the specified amount. -1 disables the value. | |
| int (*CobaltReduceCpuMemoryBy)(); | |
| // When specified this value will reduce the gpu memory consumption by | |
| // the specified amount. -1 disables the value. | |
| int (*CobaltReduceGpuMemoryBy)(); | |
| // Can be set to enable zealous garbage collection, if |javascript_engine| | |
| // supports it. Zealous garbage collection will cause garbage collection | |
| // to occur much more frequently than normal, for the purpose of finding or | |
| // reproducing bugs. | |
| bool (*CobaltGcZeal)(); | |
| // Defines what kind of rasterizer will be used. This can be adjusted to | |
| // force a stub graphics implementation. | |
| // It can be one of the following options: | |
| // 'direct-gles' -- Uses a light wrapper over OpenGL ES to handle most | |
| // draw elements. This will fall back to the skia hardware | |
| // rasterizer for some render tree node types, but is | |
| // generally faster on the CPU and GPU. This can handle | |
| // 360 rendering. | |
| // 'hardware' -- As much hardware acceleration of graphics commands as | |
| // possible. This uses skia to wrap OpenGL ES commands. | |
| // Required for 360 rendering. | |
| // 'stub' -- Stub graphics rasterization. A rasterizer object will | |
| // still be available and valid, but it will do nothing. | |
| const char* (*CobaltRasterizerType)(); | |
| // Controls whether or not just in time code should be used. | |
| // See "cobalt/doc/performance_tuning.md" for more information on when this | |
| // should be used. | |
| bool (*CobaltEnableJit)(); | |
| // The fields below this point were added in version 2 or later. | |
| // A mapping of splash screen topics to fallback URLs. | |
| const char* (*CobaltFallbackSplashScreenTopics)(); | |
| } CobaltExtensionConfigurationApi; | |
| #ifdef __cplusplus | |
| } // extern "C" | |
| #endif | |
| #endif // COBALT_EXTENSION_CONFIGURATION_H_ |