Skip to content

Update packed normals implementation to match F3DEX3 beta#567

Merged
Lilaa3 merged 3 commits intoFast-64:mainfrom
sauraen:UpdateEX3Normals
Aug 2, 2025
Merged

Update packed normals implementation to match F3DEX3 beta#567
Lilaa3 merged 3 commits intoFast-64:mainfrom
sauraen:UpdateEX3Normals

Conversation

@sauraen
Copy link
Collaborator

@sauraen sauraen commented Jul 29, 2025

The ReuniteVersions branch of F3DEX3 has been merged, putting it in beta.

The only change to the microcode which requires a fast64 change is that packed normals (normals encoded in the unused 16 bits of each vertex) have been changed from octahedral encoding to a simple 5-6-5 bit encoding. The latter was created by HailToDodongo and is used in Tiny3D. As discussed in the F3DEX3 documentation https://hackern64.github.io/F3DEX3/removed.html :

Previous F3DEX3 versions encoded packed normals into the unused 2 bytes of each vertex using a variant of octahedral encoding. Using this method, the normals were effectively as precise as with the vanilla method of replacing vertex RGB with normal XYZ. However, the decoding of this format was inefficient, partly due to the requirement to also support vanilla normals at vanilla performance. Once HailToDodongo showed that the community was willing to accept the moderate precision loss of the much simpler 5-6-5 bit encoding in Tiny3D, this was adopted in F3DEX3.

This PR adds the new encoding as well as an option to use the new or old encoding, which defaults to the new one. This option is included in case people are developing romhacks on older F3DEX3 versions and don't want to update yet. It's also included because HailToDodongo's Tiny3D external export tool converts the octahedral encoded normals to 5-6-5 encoding; he'll need to simply remove that conversion from his tool, but until he does that, fast64 directly using the 5-6-5 encoding will corrupt Tiny3D meshes.

This is tested with a variety of demo meshes using packed normals in OoT.

@sauraen sauraen requested review from Lilaa3 and Yanis002 July 29, 2025 04:34
@Lilaa3
Copy link
Collaborator

Lilaa3 commented Jul 29, 2025

It's also included because HailToDodongo's Tiny3D external export tool converts the octahedral encoded normals to 5-6-5 encoding; he'll need to simply remove that conversion from his tool

I don´t think export side stuff applies to tiny3d?

Copy link
Collaborator

@Lilaa3 Lilaa3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code looks good, I don´t have a testing environment for newer ex3 right now though so I'll take your and hopefully @Yanis002 's word. (Is there any branch for hackeroot or hackersm64? I didn´t see one)

@HailToDodongo
Copy link
Contributor

This is indeed completely independent of tiny3d.
t3d's converter works on GLTF files, which are not subject to any f3d mesh conversion.
So normals are converted from the data there which is just a full float vector.

Or more generally, any mesh conversion refactors in f3d can be done without worrying about t3d,
the only thing that could break things would be renaming internal properties of materials (e.g. tex0.S.clamp), but that's not the case here

Copy link
Collaborator

@Yanis002 Yanis002 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry for the late review, code looks fine to me and it exports properly for OoT with my scene (though it crashed in-game but there's a very high chance I missed something I need to do in HackerOoT with the new updates)

@Yanis002
Copy link
Collaborator

Code looks good, I don´t have a testing environment for newer ex3 right now though so I'll take your and hopefully @Yanis002 's word. (Is there any branch for hackeroot or hackersm64? I didn´t see one)

I opened a PR for HackerOoT earlier to update the patches HackerN64/HackerOoT#180, not sure about HackerSM64 though

@Lilaa3 Lilaa3 merged commit 518ce00 into Fast-64:main Aug 2, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants