Skip to content

Latest commit

 

History

History
185 lines (142 loc) · 6.73 KB

development-guide.md

File metadata and controls

185 lines (142 loc) · 6.73 KB

Development Guide

Backlog

The following things is the current project development direction.

Correctness issues

important issue is in bold style.

  • fix indirect rendering in windows dx12 native
  • fix mesh lod graph
  • spd not support none pot target, and small target(the current impl will access out of boundary of image).
  • 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
  • light uniform array not skip none exist light
    • missing length info, breaks path tracing light sampling impl
  • 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 parallel compute hash issue(disable the clear cache in test runner to reproduce this issue)
  • fix scene gpu lighting is globally shared in gles mode
  • fix some mesh can not be picked in cpu picking (maybe related to u16 index format)
  • fix missing blur pass in ssao
  • 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
  • fix oit loop32 depth test and msaa support

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

  • storage/texture shrink
  • improve bindgroup cache implementation
  • improve indirect draw, reduce dispatch call count (see DeviceSceneModelRenderBatchCombined)
  • 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

Useful commands

most used testing and developing commands (write it down for convenience)

run main test viewer

cargo run --bin viewer
cargo run --release --bin viewer # run it in release mode (most common to use)
cargo run --release --bin 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.

cargo t --package package_name test_name -- --nocapture

generate documents and open it in default browser (currently the project is extremely lack of documentation)

cargo doc --no-deps --open

check if any dependency has different version in used. it's not a big problem but should be cared.

cargo tree -d

the samply profiler is recommended to investigate cpu performance issue. the most used command is:

cargo build --release --bin viewer
samply record ./target/release/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 rust-lang/rust#107033. 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 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.

cargo run --bin viewer --features tracy # run viewer enable tracy
cargo run --bin viewer --features tracy-heap-debug # run viewer enable tracy and tracy-heap-debug

Testing

Runing test requires cargo-nextest. 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

cargo nextest run --no-fail-fast

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