Gfx GX Fn GXSetZTexture - wowjinxy/libPorpoise GitHub Wiki

GXSetZTexture

  • Category: Texture Environment
  • Matrix Status: Partial
  • Matrix Notes: Parity-checked SDK input semantics; last-stage routing and format-aware decode implemented; z-texture op now runs in u24-style depth arithmetic (add/replace + u24 bias) before depth write. Remaining HW depth-pipeline details stay approximated.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Tev/GXSetZTexture.html
  • SDK source: reference/gx/GXTev.c (GXSetZTexture, around lines 1074+)
  • Verified SDK behavior:
    • Accepts op in GX_ZT_DISABLE/GX_ZT_ADD/GX_ZT_REPLACE.
    • Accepts fmt in GX_TF_Z8/GX_TF_Z16/GX_TF_Z24X8; invalid formats assert and default to Z24 path.
    • Programs bias as unsigned u24 (right-justified), not signed.
    • Z texture is taken from the last active TEV stage.

libPorpoise Implementation

  • Runtime implementation area: src/gx
  • Public API surface: include/dolphin/gx
  • Current implementation:
    • GXSetZTexture in src/gx/pc_gx.c now validates op/fmt with fail-soft defaults and stores u24 bias.
    • Depth uniform upload now keeps bias unsigned and exports both normalized and integer-u24 bias uniforms to shader.
    • Shader (src/gx/shaders/default.frag) now samples z-texture from the last active TEV stage (u_num_tev_stages - 1) and decodes by format:
      • mode Z8: uses low 8 bits.
      • mode Z16: reconstructs from high(A) + low(R) byte.
      • mode Z24X8: reconstructs from RGB bytes.
    • Shader applies ADD/REPLACE and bias in u24-style integer domain (quantized 24-bit depth), then normalizes back to gl_FragDepth.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: void GXSetZTexture(GXZTexOp op, GXTexFmt fmt, u32 bias)
    • Porpoise: same
  • Behavioral parity:
    • SDK: u24 bias + op/fmt programming for z-texture stage.
    • Porpoise: now mirrors input semantics and format decode path in PC shader.
  • Known divergence:
    • Hardware-accurate interaction with full GX depth compare/compression path remains approximate in GL backend.
    • TEV last-stage “texture color unavailable when ztex enabled” is not modeled bit-exactly in all shader paths.

Validation Checklist

  • GX demo coverage checked (regression-safe functional update)
  • Pikmin usage path checked (build sanity target)
  • Matrix status updated if needed
  • Notes updated with concrete file/function references

Working Notes

  • Build sanity: cmake --build build_pikmin_win32 --config Debug --target pikmin_demo passed after patch.