blob: 9d379c75a580cc30725a5d1f45f9cb45eafdcdcc [file] [log] [blame]
// 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
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#include <stdint.h>
#include "starboard/configuration.h"
#ifdef __cplusplus
extern "C" {
#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/ 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)();
// Determines the size of garbage collection threshold. After this many
// bytes have been allocated, the SpiderMonkey garbage collector will run.
// Lowering this has been found to reduce performance and decrease
// JavaScript memory usage. For example, we have measured on at least one
// platform that performance becomes 7% worse on average in certain cases
// when adjusting this number from 8MB to 1MB.
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/" for more information on when this
// should be used.
bool (*CobaltEnableJit)();
} CobaltExtensionConfigurationApi;
#ifdef __cplusplus
} // extern "C"