Skip to content

Commit 860f0d1

Browse files
LDAPLDAP
authored
Update README
Updated README.md to enhance documentation and examples.
1 parent fefa8f8 commit 860f0d1

1 file changed

Lines changed: 67 additions & 69 deletions

File tree

‎README.md‎

Lines changed: 67 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,40 @@
22

33
~ _A Vulkan development framework._ ~
44

5+
<p align="left">
6+
<img src="images/ABeautifulGame.png" width="650" />
7+
</p>
8+
59

610
Merian is split into multiple components:
711

812
- [`merian`](https://github.com/LDAP/merian/tree/main/include/merian): Provides core abstractions and utilities (Vulkan context, memory allocation, configuration, IO, ...).
913
- [`merian-graph`](https://github.com/LDAP/merian/tree/main/include/merian-graph): Implements an extensible Vulkan processing graph. Already implemented nodes can be found [here](https://github.com/LDAP/merian/tree/main/include/merian-graph/nodes).
1014
- [`merian-shaders`](https://github.com/LDAP/merian/tree/main/include/merian-shaders): Reusable shader code plus the scene representation, glTF/FBX loaders, material system and texture management.
1115

12-
`merian-graph-run` is a generic executable that loads a processing graph from a JSON file and runs it (`merian-graph-run [options] [graph.json [args...]]`; without an argument it starts with an empty graph). Options:
16+
Merian aims for compatibility with Windows, Linux as well as all major GPU vendors.
17+
18+
## Getting started
19+
20+
### Build
21+
22+
```bash
23+
git clone --recursive https://github.com/LDAP/merian
24+
# optionally clone any plugin you want to use into subprojects:
25+
# cd subprojects
26+
# git clone https://github.com/LDAP/merian-plugin-quake
27+
meson setup build
28+
# You can enable / disable some feature by appending -Dfeature_name=enabled, for example glslang (GLSL compiler), glfw (windowing), sdl (windowing+audio), performance_profiling, tinygltf, ufbx, pbrt (scene formats) or switch to a debug build with --buildtype=debug/debugoptimized.
29+
cd build
30+
meson compile
31+
meson devenv # needed on Windows to find all the dlls
32+
# this builds all the shared libraries and a runner for merian graphs:
33+
./merian-graph-run
34+
```
35+
36+
### Examples: merian-graph-run
37+
38+
merian ships a generic executable `merian-graph-run` that loads a [`merian-graph`](https://github.com/LDAP/merian/tree/main/include/merian-graph) from a JSON file and runs it (`merian-graph-run [options] [graph.json [args...]]`; without an argument it starts with an empty graph). Options:
1339

1440
- `--loglevel=<trace|debug|info|warn|error>`: log verbosity.
1541
- `--plugin-path=<dir>`: extra plugin search directory (repeatable).
@@ -18,34 +44,61 @@ Merian is split into multiple components:
1844
- `--<name> <value>`: set an override declared in the graph's `cli` block (see the per-graph options below).
1945
- `--help`: with a `graph.json`, also lists that graph's `cli` overrides.
2046

21-
It ships with a set of built-in nodes and can be extended with additional node sets and renderers through its [plugin system](#plugins). Current plugins:
22-
23-
- [merian-plugin-quake](https://github.com/LDAP/Merian-plugin-quake): A scene node for Quake backed by the full power of quakespasm, including GUI support.
24-
25-
## Examples
47+
It ships with a set of built-in nodes and can be extended with additional node sets and renderers through its [plugin system](#plugins).
2648

2749
Example graphs for `merian-graph-run` are in the [`examples`](https://github.com/LDAP/merian/tree/main/examples) folder:
2850

2951
- [`hdr_viewer.json`](https://github.com/LDAP/merian/tree/main/examples/hdr_viewer.json): a tone-mapped HDR image viewer — `merian-graph-run examples/hdr_viewer.json <image.hdr>`.
3052
- [`shadertoy.json`](https://github.com/LDAP/merian/tree/main/examples/shadertoy.json): runs a Shadertoy-style shader — `merian-graph-run examples/shadertoy.json <shader.glsl>`.
31-
- [`gltf.json`](https://github.com/LDAP/merian/tree/main/examples/gltf.json) / [`fbx.json`](https://github.com/LDAP/merian/tree/main/examples/fbx.json): a glTF / FBX scene viewer — `merian-graph-run examples/gltf.json <scene.gltf> [options]`. Options:
53+
- [`gltf.json`](https://github.com/LDAP/merian/tree/main/examples/gltf.json) / [`fbx.json`](https://github.com/LDAP/merian/tree/main/examples/fbx.json) / [`pbrt.json`](https://github.com/LDAP/merian/tree/main/examples/pbrt.json): a glTF / FBX / PBRTv4 scene viewer — `merian-graph-run examples/gltf.json <scene.gltf> [options]`. Options:
3254
- `<scene>` (required): path to the glTF / FBX scene to load.
3355
- `--renderer <pt|mcpg|restir_di>`: renderer, merged from [`examples/renderers`](https://github.com/LDAP/merian/tree/main/examples/renderers) (default: `pt`; the selection persists when the graph is stored). Also accepts a path to a custom renderer fragment, e.g. `--renderer my/renderer.json`.
3456
- `--env-map <path>`: lat-long HDR environment map (sets the env type to `LatLong`).
3557
- `--max-path-length <n>`: maximum path length (`pt`, `mcpg`).
3658
- `--spp <n>`: samples per pixel.
3759

38-
For using merian as a library in your own project, see [merian-example-sum](https://github.com/LDAP/merian-example-sum) (computing a sum on the GPU) and [merian-quake](https://github.com/LDAP/merian-quake), a path tracer for the original Quake game.
60+
### Plugins
3961

40-
Merian aims for compatibility with Windows, Linux as well as all major GPU vendors.
62+
A plugin is a separate repository that builds a `merian-plugin-*` shared library and contributes nodes and/or context extensions, which are discovered automatically at startup by `merian-graph-run` and any merian host. Plugins should never vendor merian but consume it via `dependency('merian')`. To build a plugin alongside merian, clone it into the `subprojects` folder (the directory must be named `merian-plugin-*`); `meson compile` then builds it as part of merian (no `PKG_CONFIG_PATH` needed):
4163

64+
```sh
65+
git clone <plugin-repo> subprojects/merian-plugin-<name>
66+
meson setup build --reconfigure
67+
meson compile -C build
68+
```
4269

43-
<p align="left">
44-
<img src="images/ABeautifulGame.png" width="650" />
45-
</p>
70+
- [merian-plugin-quake](https://github.com/LDAP/Merian-plugin-quake): A scene node for Quake backed by the full power of quakespasm, including GUI support.
4671

72+
## Environment variables
4773

48-
## Getting started
74+
merian reads the following environment variables at startup:
75+
76+
| Variable | Default | Description |
77+
| --- | --- | --- |
78+
| `MERIAN_SHADER_CACHE` | on | Set to `0` to disable the on-disk Slang shader cache (serialized IR modules + compiled SPIR-V). |
79+
| `MERIAN_SHADER_CACHE_DIR` | `./.merian-cache` | Directory for the shader cache. Safe to delete at any time. |
80+
| `MERIAN_SHADER_CACHE_MAX_MB` | `128` | Cache size cap in MiB, enforced (oldest-first) when a shader session is torn down. `0` = unbounded (manage by hand). |
81+
| `MERIAN_TARGET_VK_API_VERSION` | highest supported | Target Vulkan API version, e.g. `1.3`. Clamped to the range supported by the Vulkan headers. |
82+
| `MERIAN_DEFAULT_FILTER_VENDOR_ID` | — | Pick the GPU by PCI vendor id (decimal). |
83+
| `MERIAN_DEFAULT_FILTER_DEVICE_ID` | — | Pick the GPU by device id (decimal). |
84+
| `MERIAN_DEFAULT_FILTER_DEVICE_NAME` | — | Pick the GPU by (a substring of) its name. |
85+
| `MERIAN_DEBUG_UTILS_ASSERT_ERROR` | on | When the `merian-debug-utils` extension is loaded, throw on a validation message of severity error. Set to `false` to only log it. |
86+
| `MERIAN_PLUGIN_PATH` | — | Extra plugin search directories, separated by `:` (`;` on Windows). In addition, the user data dir is searched: `$XDG_DATA_HOME/merian/plugins` (or `$HOME/.local/share/merian/plugins`; `%APPDATA%\merian\plugins` on Windows). |
87+
88+
## Documentation
89+
90+
Documentation is in the `docs` subdirectory of this repository.
91+
92+
Nodes are documented in their [respective subfolder](https://github.com/LDAP/merian/tree/main/include/merian-graph/nodes).
93+
94+
## Integration in your own Project
95+
96+
If you do not want to use merians graph / plugin system, you can use merian in as a library in your own project. Examples:
97+
98+
- [merian-example-sum](https://github.com/LDAP/merian-example-sum) (computing a sum on the GPU)
99+
- [merian-quake](https://github.com/LDAP/merian-quake) (deprecated, if you want to play Quake use merian-plugin-quake).
100+
101+
Merian is similar to the `vulkan_raii.hpp` layer for `vulkan.hpp`. Most objects follow the RAII principle. The `merian` namespace provides shareable handles for most Vulkan types (e.g. `merian::ImageHandle` for `vk::Image`) and objects are automatically destroyed if their reference count becomes 0. The `Context` class initializes and destroys a Vulkan device and holds core objects (PhysicalDevice, Device, Queues, ...). Create a Context using `Context::create(ContextCreateInfo)`. The core `"merian"` extension is always loaded automatically. Make sure your program ends with `[INFO] [context.cpp:XX] context destroyed`. Note that the Vulkan dynamic dispatch loader must be used and the merian build system definition should already ensure that.
49102

50103
```c++
51104
int main() {
@@ -86,7 +139,7 @@ merian::ContextHandle context = merian::Context::create({
86139
});
87140
```
88141

89-
## Include Merian into your Project
142+
### Buildsystem Integration
90143

91144
This library uses the [Meson Build System](https://mesonbuild.com/) and declares a dependency for it:
92145

@@ -116,8 +169,6 @@ exe = executable(
116169
],
117170
# ...
118171
)
119-
120-
121172
```
122173

123174
To allow meson to find Merian, either clone this repo into the `subprojects` folder or add a file `subprojects/merian.wrap` with
@@ -134,56 +185,3 @@ clone-recursive = true
134185
[provide]
135186
merian = merian_dep
136187
```
137-
138-
139-
## Environment variables
140-
141-
merian reads the following environment variables at startup:
142-
143-
| Variable | Default | Description |
144-
| --- | --- | --- |
145-
| `MERIAN_SHADER_CACHE` | on | Set to `0` to disable the on-disk Slang shader cache (serialized IR modules + compiled SPIR-V). |
146-
| `MERIAN_SHADER_CACHE_DIR` | `./.merian-cache` | Directory for the shader cache. Safe to delete at any time. |
147-
| `MERIAN_SHADER_CACHE_MAX_MB` | `128` | Cache size cap in MiB, enforced (oldest-first) when a shader session is torn down. `0` = unbounded (manage by hand). |
148-
| `MERIAN_TARGET_VK_API_VERSION` | highest supported | Target Vulkan API version, e.g. `1.3`. Clamped to the range supported by the Vulkan headers. |
149-
| `MERIAN_DEFAULT_FILTER_VENDOR_ID` | — | Pick the GPU by PCI vendor id (decimal). |
150-
| `MERIAN_DEFAULT_FILTER_DEVICE_ID` | — | Pick the GPU by device id (decimal). |
151-
| `MERIAN_DEFAULT_FILTER_DEVICE_NAME` | — | Pick the GPU by (a substring of) its name. |
152-
| `MERIAN_DEBUG_UTILS_ASSERT_ERROR` | on | When the `merian-debug-utils` extension is loaded, throw on a validation message of severity error. Set to `false` to only log it. |
153-
| `MERIAN_PLUGIN_PATH` | — | Extra plugin search directories, separated by `:` (`;` on Windows). In addition, the user data dir is searched: `$XDG_DATA_HOME/merian/plugins` (or `$HOME/.local/share/merian/plugins`; `%APPDATA%\merian\plugins` on Windows). |
154-
155-
## Plugins
156-
157-
A plugin is a separate repository that builds a `merian-plugin-*` shared library and contributes nodes and/or context extensions, which are discovered automatically at startup by `merian-graph-run` and any merian host. Plugins do not vendor merian — they consume it via `dependency('merian')`.
158-
159-
To build a plugin alongside merian, clone it into the `subprojects` folder (the directory must be named `merian-plugin-*`); `meson compile` then builds it as part of merian (no `PKG_CONFIG_PATH` needed):
160-
161-
```sh
162-
git clone <plugin-repo> subprojects/merian-plugin-<name>
163-
meson setup build --reconfigure
164-
meson compile -C build
165-
```
166-
167-
See [Plugin Development](docs/PluginDevelopment.md) for writing a plugin and building it standalone against an installed merian.
168-
169-
## Documentation
170-
171-
Documentation is in the `docs` subdirectory of this repository.
172-
173-
Nodes are documented in their [respective subfolder](https://github.com/LDAP/merian/tree/main/include/merian-graph/nodes).
174-
175-
## Usage
176-
177-
Merian is similar to the `vulkan_raii.hpp` layer for `vulkan.hpp`. Most objects follow the RAII principle. The `merian` namespace provides shareable handles for most Vulkan types (e.g. `merian::ImageHandle` for `vk::Image`) and objects are automatically destroyed if their reference count becomes 0.
178-
179-
The `Context` class initializes and destroys a Vulkan device and holds core objects (PhysicalDevice, Device, Queues, ...).
180-
181-
Create a Context using `Context::create(ContextCreateInfo)`. The core `"merian"` extension is always loaded automatically. Additional extensions are loaded by name via `ContextCreateInfo::context_extensions`. Vulkan features are requested via `ContextCreateInfo::features` using a `VulkanFeatures` object.
182-
183-
Make sure your program ends with `[INFO] [context.cpp:XX] context destroyed`.
184-
185-
Note that the Vulkan dynamic dispatch loader must be used. The default dispatcher is initialized in `Context`. The merian build system should already ensure that.
186-
187-
```c++
188-
#define VULKAN_HPP_DISPATCH_LOADER_DYNAMIC 1
189-
```

0 commit comments

Comments
 (0)