Gfx GX Fn GXInitTexObj - wowjinxy/libPorpoise GitHub Wiki

GXInitTexObj

  • Category: Texture
  • Matrix Status: Implemented
  • Matrix Notes: Verified against SDK docs/source; now matches default mip/non-mip filter initialization semantics (including CI mipmap default) and initializes max LOD from texture dimensions.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXInitTexObj.html
  • SDK source: reference/gx/GXTexture.c (GXInitTexObj)
  • SDK behavior:
    • Signature: void GXInitTexObj(GXTexObj* obj, void* image_ptr, u16 width, u16 height, GXTexFmt format, GXTexWrapMode wrap_s, GXTexWrapMode wrap_t, GXBool mipmap).
    • Clears texture object state and initializes image pointer/size/format/wrap.
    • Default mag filter is GX_LINEAR.
    • Default min filter:
      • non-mipmap: GX_LINEAR
      • mipmap + non-CI: GX_LIN_MIP_LIN
      • mipmap + CI: GX_LIN_MIP_NEAR
    • Mipmap path initializes max LOD from the larger of width/height.

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXInitTexObj)
  • Behavior:
    • Signature matches SDK declaration.
    • Resets texture object and sets pointer/size/format/wrap/mipmap flags.
    • Default min/mag filter behavior now matches SDK defaults above.
    • Initializes TEXOBJ_MAX_LOD from texture dimensions when mipmapped.
    • PC backend uses fail-soft clamping for invalid sizes (0 -> 1, >1024 -> 1024) instead of debug asserts.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXInitTexObj(GXTexObj*, void*, u16, u16, GXTexFmt, GXTexWrapMode, GXTexWrapMode, GXBool)
    • Porpoise: same (with const void* image pointer in API surface)
  • Behavioral parity:
    • SDK: initializes object state, wrap, default filters, mip defaults.
    • Porpoise: matches these defaults after fix; stores equivalent object metadata used by PC load path.
  • Known divergence:
    • SDK uses asserts for invalid dimensions/alignment in debug builds; Porpoise uses fail-soft clamping for dimensions here.
    • Full hardware SU/TMEM behavior is handled elsewhere and remains approximate on PC backend.

Validation Checklist

  • GX demo coverage checked
  • Pikmin usage path checked
  • Matrix status updated if needed
  • Notes updated with concrete file/function references

Working Notes

  • GXInitTexObj default min-filter for mipmapped textures was previously too coarse and now follows SDK behavior.