Viz - short for visuals - is the client library and service implementations for compositing and gpu presentation.
See //services/viz for more information about Viz overall.
For understanding compositing related terminology, check out //cc. For understanding display compositor's position in the graphics stack, check out Compositor Stack slides. For more comprehensive list of design docs relating to Viz, check out WIP list of design doc.
Table of Contents
Mojo Interface: The interface definition, found in a .mojom file. This is an abstract interface and can be thought of as a process/thread-independent C++ abstract class.
Mojo Implementation: The default implementation of a mojom interface for production. Many interfaces will only have a single implementation that we ship.
Alternate Mojo Implementations: Secondary implementations of a mojom interface for platform-specific details, for tests, etc.
Service: Where Mojo implementations live and run.
Host: A privileged process that provides access to viz Mojo interfaces for Clients. Most services in Chrome don’t have these, and Clients find the service directly, but they are more common in Viz. Currently the Host is in the browser process. In a fully-realized mus+ash, the Host moves outside of Chrome to the window server.
Client: All users of a Mojo interface who are not the Host. They will usually need to go through the Host to gain access to the Mojo interface.
Host-side Wrapper: A C++ wrapper around a Mojo interface for use in Hosts, that often also exposes or uses some privileged interfaces that Clients don’t have. Generally prefer to use the Mojo interfaces directly, but sometimes we need another C++ helper around it.
Client-side Wrapper: A C++ wrapper around a Mojo interface for use in Clients. Generally prefer to use the Mojo interface directly, but sometimes we need another C++ helper around it.
Host/Client-side Abstraction: A C++ wrapper around a Mojo interface that is also a subclass of a C++ interface. Generally prefer to use the Mojo interfaces directly, but sometimes we need a higher-level C++ abstraction, usually because other subclasses cannot use the Mojo interface.
To keep dependencies clear into the Viz source tree, all source code files should appear in leaf directories.
Data types and simple helpers that are used by the client library, or by clients directly, and by service implementations.
Client library for accessing Viz services. May be used from privileged (eg browser) or unprivileged (eg renderer) processes. The client library should remain agnostic about how to communicate with viz (in other words should not use mojo bindings), as some viz clients use mojo but others use it in-process or via other IPC mechanisms.
Can depend on: |
---|
viz/common/ |
Privileged client library for owning and controlling Viz services. May only be used from privileged (eg browser) processes.
This should not depend on other parts of Viz, as they are core data types and helpers only, and can be used from anywhere else in Viz.
Can depend on: |
---|
viz/common/ |
Service-side implementations of Viz Mojo interfaces, which are found in //services/viz. Each component of the service-side implementation is located in its own sub-directory.
As of this writing, these service components may be instantiated and used directly from the browser process. But these services are intended to be abstracted away through Mojo interfaces so that they are able to live entirely outside the browser process, and gain in-process access to the Gpu.
Display compositor: The display compositor uses Gpu or software to composite a set of frames, from multiple clients, into a single backing store for display to the user. Also deals in getting screenshots of content by drawing to offscreen buffers.
The top-level scheduler that coordinates when the compositor should draw, along with when clients should be submitting frames.
This component is platform-agnostic, with any platform-specific details abstracted away from it. It accesses Gpu services through the command buffer as a client even though it is in the same process as the Gpu service in order to be scheduled as a peer among other clients.
Can depend on: |
---|
viz/common/* |
viz/service/surfaces/ |
Platform details for display compositor: While the display compositor is platform-agnostic, this component provides implementations of platform-specific behaviour needed for the display compositor, and injected into it.
Code here supports presentation of the backing store drawn by the display compositor (typically thought of as SwapBuffers), as well as the use of overlays.
Can depend on: |
---|
viz/common/* |
viz/service/display/<some_interfaces> |
Dependencies onto viz/service/display should generally only be for interfaces that the embedder must provide to the display.
Frame sinks: This component implements the Mojo interfaces to send frames, resources, and other data types from viz/common/
for display to the compositing service. It receives and organizes relationships between what should be composited.
Can depend on: |
---|
viz/common/* |
viz/service/display/ |
viz/service/display_embedder/ |
viz/service/hit_test/ |
viz/service/surfaces/ |
viz/service/transitions/ |
FrameSinkVideoCaptureImpl: This component implements the Mojo interfaces to capture frames that are sent to the compositing service, producing a stream of video frames. It provides a capture pipeline where asynchronous GPU readback is executed (via CopyOutputRequests, and then CopyOutputResults are applied to a pool of shared memory buffers backing video frames that are sent to privileged consumers.
A capturer instance is created via FrameSinkManager's CreateVideoCapturer() method.
Can depend on: |
---|
media/base/* |
media/capture/* |
media/mojo/* |
viz/common/* |
viz/service/frame_sinks/* |
GL: This component implements the Mojo interfaces for allocating (and deallocating) gpu memory buffers, setting up a channel for the command buffer, etc.
Can depend on: |
---|
viz/common/* |
Hit testing: Service-side code to resolve input events to individual clients.
Can depend on: |
---|
viz/common/* |
viz/service/surfaces/ |
Main: TODO(fsamuel): This will hold implementation of the root interface from which other service interfaces are accessed.
As the root of the service/ code structure, it instantiates and connects all other parts of Viz.
Can depend on: |
---|
viz/common/* |
viz/service/* |
Surfaces: This component acts like the data model for the compositing service. It holds data received from frame sinks, and provides access to them for the display compositor.
Can depend on: |
---|
viz/common/* |
Transitions: This directory is in support of the view transitions project. See //third_party/blink/rendering/core/document_transition/README.md
Can depend on: |
---|
viz/common/ |
viz/service/surfaces/ |
Viz related runtime feature flags, aka base::Feature
s, should go in components/viz/common/features.h.
When adding a new feature kMyFeature
, it's recommended that you add a helper function IsMyFeatureEnabled()
to check if the feature is enabled. Code should then use IsMyFeatureEnabled()
instead of checking base::FeatureList::IsEnabled(kMyFeature)`.
Preconditions can be platform or hardware specific checks to determine if a feature is supported on a given device. These preconditions should be validated before checking the base::FeatureList
, as once the list is consulted the session will be reflected in any ongoing Finch trial. If we were to disable the implementation due to preconditions after registering with Finch, then we will be providing incorrect data to the study.
base::FeatureList::IsEnabled()
caches the feature's value internally on the first lookup, making all subsequent lookups cheap. Thus, it is acceptable for it to be called in a hot code path.
Note base::ScopedFeatureList
resets/invalidates the feature‘s internal cache on initialization so that the feature’s value may be controlled across test cases as desired. This does not hold, however, if the calling code itself chooses to cache the feature's value in a variable with static storage duration. This pattern is discouraged:
bool IsMyFeatureEnabled() { static bool enabled = base::FeatureList::IsEnabled(kMyFeature); // NO! return enabled; }
The first time IsMyFeatureEnabled()
is called from the test runner process the feature state is cached within the static enabled
variable. If a later test uses base::ScopedFeatureList
to change the feature state, that change will not be reflected in IsMyFeatureEnabled()
and the test will (most likely) fail.
Ensure that features are enabled/disabled for testing before any viz code is initialized. As a general rule base::ScopedFeatureList
should be the first thing initialized in a test fixture to avoid data races and incorrect feature values.
Viz makes extensive use of Mojo, and there are conflicting patterns with regard to naming types around Mojo interfaces in the codebase today. This aims to provide a standard to adhere to for future naming to increase our consistency within the team.
For a given mojo service called TimeTraveller
, we would use the following.
Mojo Interface: mojom::TimeTraveller
Mojo Implementation: TimeTravellerImpl
Alternative Mojo Implementation: DescriptivePrefixTimeTravellerImpl
Host-side Wrapper: HostTimeTraveller
Client-side Wrapper: ClientTimeTraveller
Host/Client-side Abstraction: OtherAbstractionName