1# Graphics Streaming Kit (formerly: Vulkan Cereal)
2
3Graphics Streaming Kit (colloquially known as Gfxstream) is a code generator
4that makes it easier to serialize and forward graphics API calls from one place
5to another:
6
7-   From a virtual machine guest to host for virtualized graphics
8-   From one process to another for IPC graphics
9-   From one computer to another via network sockets
10
11# Build: Linux
12
13The latest directions for the standalone Linux build are provided
14[here](https://crosvm.dev/book/appendix/rutabaga_gfx.html).
15
16# Build: Windows
17
18Make sure the latest CMake is installed. Make sure Visual Studio 2019 is
19installed on your system along with all the Clang C++ toolchain components.
20Then:
21
22```
23mkdir build
24cd build
25cmake . ../ -A x64 -T ClangCL
26```
27
28A solution file should be generated. Then open the solution file in Visual
29studio and build the `gfxstream_backend` target.
30
31# Build: Android for host
32
33Be in the Android build system. Then:
34
35```
36m libgfxstream_backend
37```
38
39It then ends up in `out/host`
40
41This also builds for Android on-device.
42
43# Output artifacts
44
45```
46libgfxstream_backend.(dll|so|dylib)
47```
48
49# Regenerating Vulkan code
50
51To re-generate both guest and Vulkan code, please run:
52
53scripts/generate-gfxstream-vulkan.sh
54
55# Regenerating GLES/RenderControl code
56
57First, build `build/gfxstream-generic-apigen`. Then run:
58
59```
60scripts/generate-apigen-source.sh
61```
62
63# Tests
64
65## Windows Tests
66
67There are a bunch of test executables generated. They require `libEGL.dll` and
68`libGLESv2.dll` and `vulkan-1.dll` to be available, possibly from your GPU
69vendor or ANGLE, in the `%PATH%`.
70
71## Android Host Tests
72
73There are Android mock testa available, runnable on Linux. To build these tests,
74run:
75
76```
77m GfxstreamEnd2EndTests
78```
79
80# Features
81
82## Tracing
83
84The host renderer has optional support for Perfetto tracing which can be enabled
85by defining `GFXSTREAM_BUILD_WITH_TRACING` (enabled by default on Android
86builds).
87
88The `perfetto` and `traced` tools from Perfetto should be installed. Please see
89the [Perfetto Quickstart](https://perfetto.dev/docs/quickstart/linux-tracing) or
90follow these short form instructions:
91
92```
93cd <your Android repo>/external/perfetto
94
95./tools/install-build-deps
96
97./tools/gn gen --args='is_debug=false' out/linux
98
99./tools/ninja -C out/linux traced perfetto
100```
101
102To capture a trace on Linux, start the Perfetto daemon:
103
104```
105./out/linux/traced
106```
107
108Then, run Gfxstream with
109[Cuttlefish](https://source.android.com/docs/devices/cuttlefish):
110
111```
112cvd start --gpu_mode=gfxstream_guest_angle_host_swiftshader
113```
114
115Next, start a trace capture with:
116
117```
118./out/linux/perfetto --txt -c gfxstream_trace.cfg -o gfxstream_trace.perfetto
119```
120
121with `gfxstream_trace.cfg` containing the following or similar:
122
123```
124buffers {
125  size_kb: 4096
126}
127data_sources {
128  config {
129    name: "track_event"
130    track_event_config {
131    }
132  }
133}
134```
135
136Next, end the trace capture with Ctrl + C.
137
138Finally, open https://ui.perfetto.dev/ in your webbrowser and use "Open trace
139file" to view the trace.
140
141# Design Notes
142
143## Guest Vulkan
144
145gfxstream vulkan is the most actively developed component. Some key commponents
146of the current design include:
147
148-   1:1 threading model - each guest Vulkan encoder thread gets host side
149    decoding thread
150-   Support for both virtio-gpu, goldish and testing transports.
151-   Support for Android, Fuchsia, and Linux guests.
152-   Ring Buffer to stream commands, in the style of io_uring.
153-   Mesa embedded to provide
154    [dispatch](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/dispatch.rst)
155    and
156    [objects](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/docs/vulkan/base-objs.rst).
157-   Currently, there are a set of Mesa objects and gfxstream objects. For
158    example, `struct gfxstream_vk_device` and the gfxstream object
159    `goldfish_device` both are internal representations of Vulkan opaque handle
160    `VkDevice`. The Mesa object is used first, since Mesa provides dispatch. The
161    Mesa object contains a key to the hash table to get a gfxstream internal
162    object (for example, `gfxstream_vk_device::internal_object`). Eventually,
163    gfxstream objects will be phased out and Mesa objects used exclusively.
164