starboard/extension/configuration.h

// Copyright 2023 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 STARBOARD_EXTENSION_CONFIGURATION_H_
#define STARBOARD_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. 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.
  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)();

  // Deprecated
  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. 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)();

  // The fields below this point were added in version 3 or later.

  // Determines whether compiled Javascript caching code is enabled.
  bool (*CobaltCanStoreCompiledJavascript)();
} CobaltExtensionConfigurationApi;

#ifdef __cplusplus
}  // extern "C"
#endif

#endif  // STARBOARD_EXTENSION_CONFIGURATION_H_