# Development Guide ## Backlog The following things is the current project development direction. ### foreign features requirement - occulsion test not correctly handle the depth test/write configured object - fix init_frame not for per surface ### Correctness issues important issue is in bold style. - skip_if_not_waked not considering inspect stage - infinity line not displayed if near point is clipped - midc downgrade not support linestrip or triangle strip - improve multi format support in texture pool system - support face side control - support double side config in gltf loader - fix gizmo plane move only one side is visible - disable ssao when channel debug on - fix channel debug in defer mode - support material emissive larger than one - fix defer channel encode decode - fix gltf loader support - fix some mesh can not be picked in cpu picking (maybe related to u16 index format) - blur pass in ssao is not every effective - fix ao should only shadowing diffuse lighting. - ibl brdf lut should use higher precision lut - fix outline shaking - integrate_brdf and ibl lighting shader code should reuse the std micro surface shading code ### Implemented but not yet integrated(tested) features - sky shading - ssr(super naive) ### New features planed - gtao - good shadow - ddgi - physical camera - physical sky/atmosphere - volumetic cloud/fog - point cloud - gaussian splatting - automatic exposure control - fft bloom - contact shadow - skin animation(indirect) - good ssr - visibility rendering - cluster lighting optimization - ray tracing - support light and material MIS - support new high quality sampler ### Infra and framework improvements planed - improve bindgroup cache implementation - viewer async loader - ray tracing - improve the wavefront dispatch performance - let user manual control dispatch rounds - support zero sized state in task graph - parallel compute support buffer reuse pool - shader ptr should support rw convert to readonly - impl bind check for compute pass - support ptr in shader fn - depend on naga unrestricted_pointer_parameters feature support? ### Need help issue - enable frame time query on metal in release mode may panic when load large models Device::create_query_set failed ### Upstream issue - not reported or further investigate - naga metal backend has layout bug, (buffer combine with rtao shader breaks on Metal, workaound by adding manual padding in struct end). - draw on TextureFormat::R8Unorm when enable blend cause strange effect - chrome wgsl not accept f32::MAX float literal - known but not fixed yet - dx12 midc - correct hdr rendering, see ; - huge rust debug symbol cause link or compile failed in reative query(currently workaround by boxing). see: - - - disable fast-math for large world rendering: ### other nice to have improvements in viewer - - framepacing ## Useful commands most used testing and developing commands (write it down for convenience) run main test viewer ```bash cargo run --bin rendiation-viewer cargo run --release --bin rendiation-viewer # run it in release mode (most common to use) cargo run --release --bin rendiation-viewer --no-default-features # run it in release mode without extra debug overhead(should used to profiling and production) ``` run given test when debugging. this is useful to fast relaunch same test in terminal. ```bash cargo t --package package_name test_name -- --nocapture ``` generate documents and open it in default browser (currently the project is extremely lack of documentation) ```bash cargo doc --no-deps --open ``` check if any dependency has different version in used. it's not a big problem but should be cared. ```bash cargo tree -d ``` [the samply profiler](https://github.com/mstange/samply) is recommended to investigate cpu performance issue. the most used command is: ```bash cargo build --profile profiling --bin rendiation-viewer samply record ./target/profiling/rendiation-viewer ``` For GPU debugging and profiling, the metal gpu capture is recommended to investigate gpu workload on macOS. On the other platform that using Nvidia graphics card, the Nsight is recommended. If the webgpu backend switched to Dx12, the Pixi debugger is another good choice. When using Xcode & Instrument to debug memory usage, your binary should manually be signed, or you will get "required kernel recording resources" error. see . Restart the profiler after signing. The `viewer_init_config.json` will be search and loaded when viewer init, if not exist or failed to load, the default init config will be used. The stability of this config file is not guarrenteed. This config can be exported in viewer UI. ## Tracy profiler [tracy](https://github.com/wolfpld/tracy) is a useful tool to investigate memory and performance issues. Tracy has already integrated into viewer application. It is disabled by default behind the `tracy` feature flag because it will using and buffering a lot of memory when enabled. The current integration should use tracy 0.11.1 client to connect. ```bash cargo run --bin rendiation-viewer --features tracy # run viewer enable tracy cargo run --bin rendiation-viewer --features tracy-heap-debug # run viewer enable tracy and tracy-heap-debug ``` ## dhat frame allocation info enable "dhat-heap-profiling" feature, build and run, click profile button. `cargo run -p rendiation-viewer --no-default-features --features "dhat-heap-profiling"` generate flamegraph first install convert tool `cargo install dhat-to-flamegraph`, then: `dhat-to-flamegraph dhat-heap.json -o result.svg --unit blocks` ## Testing Runing test requires [cargo-nextest](https://nexte.st/). We rely on this because some test case modify global variables which causes issue in the mutli-thread test runner. Nestext is multi process so it can simply avoid this issue. Also, Nestest has better user experience. run all test to see if something failed ``` bash cargo nextest run --no-fail-fast ``` ## Packaging install [cargo-bundle](https://github.com/burtonageo/cargo-bundle) `cargo install cargo-bundle` run `cargo bundle -p rendiation-viewer --release` or production config at project root path go target/release/bundle to get your package. This only tested on macos ## Coding style The basic coding style is enforced by rustfmt. Some extra notes are: - If the name of the struct or type contains multiple terminology nouns in sequence, for example "GPU" and "NDC" in " WebGPUNDC", use the "WebGPUxNDC" instead. - Make sure the code looks visually comfortable, adjust the line break and insert empty row in pair with how logic and data flows. Rustfmt can not do that for you. ## Version control - Avoid committing derived data, binary data (including bitmap images) into the repository, We're considering using a separate submodule repository for these assets.. except: - the file size is relatively small(less than 20kb), and - it's act as the fundamental support for some feature. For example the LUT texture used in rendering