`z_camera` with Partial Docs (4 Non-Equivalent)

[engineer124]

This decompiles and partially docs the camera system. To try and summarize the camera system:

Summary Majora's mask has 4 core camera's that are stored in globalCtx. There is functionality to have more than 4 cameras by allocating space on the Zelda Arean Heap, but neither OoT nor MM takes advantage of this. The main camera is used during regular gameplay and the 3 sub camera's are used primarily for cutscenes to ensure smooth cuts between cameras.

The main purpose of camera is to define and update the camera behavior. The result of this file is primarily to determine the camera eye, at, up, fov, roll. Camera.c is not involved in calculating the projection matrices. That is covered by z_view and libultra files. The results of camera are then sent to z_view, which are then sent to libultra, to get the persepctive matrices.

The core of camera are the functions that determine camera behaviour. These can be though of as "action functions" (comments about that name below). These can be seen here: https://github.com/engineer124/mm/blob/57431239ff4765250d45ba5705eba1e1c8f9f5ce/src/code/z_camera_data.c#L3431-L3503 These functions take up a large portion of camera.c and are located in the middle of the file. The files at the top of camera.c are mainly internal support functions for these action functions. The functions at the bottom of camera.c are mainly external functions to both support these action functions and control the logic as to which action function is running (only 1 action function can be active at once per camera).

For a summary of how these action functions are chosen, see a summary I made in discord: TLDR: They're determine by a table from camera settings and camera modes https://discord.com/channels/688807550715560050/688851976746041391/875352729067851798

The other complex system that might be hard to understand first is what's going with camera_data.c and most of z64camera.h. I'll leave links of previous explanations on what's going on for reference: https://github.com/engineer124/mm/blob/57431239ff4765250d45ba5705eba1e1c8f9f5ce/include/z64camera.h#L436-L452 https://discord.com/channels/688807550715560050/838852326231769089/930266412080050176

Below are a list of names that I am not satisfied with, and are a top priority for me to find more adequate names, particularly because there's a lot of other documentation in camera that are depending on figuring out names for these:

bgCamData & csCamData & CamData The camera will often continually read data from asset data to update its settings. There are two varieties of this, which have the same struct:

• bgCamData reads poly data from the poly that the tracked actor is interacting with (this track actor is most often Player). This poly is in practice always pulled from the scene, but in theory one could assign bgCamData to a dynaActor (with a mesh).
• csCamData reads cutscene data from the scene based on the current cutscene playing (these are usually quick and small cutscenes).

Both together are called CamData. This struct contains three elements:

• setting -> the camera setting to be used
• data -> A customizable array of Vec3s data that can be used with that setting. This is commonly used as position data, but there are cases of rotation, field of view, and more unknown data
• numData -> number of Vec3s used by the data

The issue I have is that both Data is in the struct name, and as Vec3s data which makes for some vague function names and variables, especially in a system with so much data. I’ve been playing around with CamSceneData, but it could theoretically apply to dynaActors as well. Currently, csCamData is in the main repo as CsCameraEntry, so maybe that could be the names: CsCamEntry/BgCamEntry/CamEntry. Maybe something more specific could be CamSetData or CameraSettingData in full.

trackActor & target The camera keeps track of two actors which assist in its updating of behaviours:

• The trackActor is a pointer to the actor that the camera is tracking. Most often, this is Player. In OoT, it’s always player but MM generalized it so that it could point to any generic actor. This is usually what ends up at the center of the screen, and is what the camera points at
• The target is a pointer to the actor that the trackActor is targeting, i.e. most often this is simply a z-target.

I really want to drop the Actor from trackActor but are the two names track/target clear enough? Should it be something like primaryTarget/secondaryTarget for those two names possibly?

ActionFunc These are the main camera functions that define the update behaviour that’s called each frame. They can be thought of as action Functions, in where only one action function is assigned to the camera at once, and it’s called every frame. These functions use a combination of data from player, the environment, preset data, geometry to act almost like an ai to update the camera’s eye, at, up, fov, and roll as common variables. I’m not sure I like using the term “action function” for this though.

Flags1 & Flags2 & ParamFlags There are three sets of flags that I am struggling to differentiate from one another.

• Flags1: These flags are very specific to camera settings, modes, and CamData. They have limited scope, but I am unsure of a name that captures just these three names. From OoT Debug strings, the names they used originally appears to have been engine, so an option for this is engineFlags
• Flags2: These flags seem to be the generic flags that are used all over camera and are manipulated all over the repo. These likely won’t have any specific name, but I am considering stateFlags at the risk of that being a term that should be exclusive to player
• ParamFlags: This set of flag is used specifically for setting data in the camera struct. Data involves: eye, at, up, fov, roll, target, and targetPosRot. Similar to Flags1, I’m not sure of a single name that encompasses these, but it is limited in scope to just setting these values.

Additional Comments

• In addition to the 4 non-equivalents, there is one “non-matching” Camera_Jump2 that is verified to be matching, but can not be brought in due to issues in disassembling data into the wrong asm files. Once the non-equivalent Camera_Jump3 is matching, then both Camera_Jump2 and Camera_Jump3 can have the pragmas removed.
• I would say most of camera is able to be documented now. The only things left that are needed from the rest of the repo are playerFlags. Majora’s Mask Randomizer has some fantastic docs on a majority of MM’s player Flags, which I was able to test in game to confirm on a first order level. Of course, these will need to be verified later as player is decomped and documentation improves.
• The other main thing waiting on the rest of the repo are camera settings. There are camera settings in-game that I can see are set in the camera struct, but I am unable to trace back where they are set (I did a lot of asm digging too). So many setting names remain their original name from debug strings, and a renaming of those will wait until more info is available. Some settings were given new names though, and those are mainly the settings that I fully understand. This same principle applies to camera_data.c. the variables named are the ones where I'm happy with the camera setting name.
• I’m still unsure whether I should break this up into smaller PRs. There’s not really any way to break up this system. Everything revolves around the action functions: camera.h, camera_data.c, the support functions around. It’s hard to properly review those without the context of the action.
• The biggest struggle with naming is finding a consistent and clear way to name all the “mathy” temps. There are a lot of calculations that happen in spherical coordinates, a lot of vectors and lines connecting many different points with long names. Also, I don’t fully understand all the math happening in some places yet, but I know I can figure it out with time and a little whiteboard geometry pictures.
• Also, the actionFuncHeap structs for each actionFunction are probably the least documented part. This goes in hand with the previous point of needing to work out the style of docs for the mathy parts before these can be documented. As well as documentation of the support functions
• Regarding the 4 non-equivalent functions, I have had consistent issues setting up those functions on decompme. I'm not sure where in the enless number of camera structs decompme doesn't like, but I apologize for not being able to provide decompme's for those functions yet. Once this is open, I'll try to work with the decompme discord to get these 4 functions up and running
• There's overlap documentation from https://github.com/zeldaret/mm/pull/588, so you can ignore all the distortion code changes in z_view and z_quake and give reviews in that corresponding file
• This is a project that’s been worked on and off over the last 6 months, and I’m sure I’ve had many more comments I wanted to mention that have been lost. So I’ll try to add more comments as I think of them and as the review progresses.
• Finally, I'd like to give a huge shoutout to Krim for his work on OoT's camera, which layed the foundation for MM's camera, particularly all the structs for each of the action function. By figuring that out for OoT, it made decompiling MM's camera much easier and structured.

[engineer124]

The file camera.c has been split into three parts temporarily for Github to better process these files. camera_part1.c contains the first third of camera, camera_part3.c contains the last third of camera. And all the action functions (2/3) were left in camera.c

[engineer124]

Drafting until https://github.com/zeldaret/mm/pull/644 is merged

[Kenix3]

Personally, I like target more than trackActor

I also agree that actionFunc is a little wonky, but cameras are technically objects that exist in the scene, so using the same terminology as actors isn't that bad.

[engineer124]

Personally, I like target more than trackActor

In regards to actors, there are two distinct actors to consider:

Actor 1: The actor that the camera is pointing at. This was previously called "trackActor" but has since been changed to focalActor. In OoT, this is exclusively Player, but MM generalized this to be any actor

Actor 2: The actor that player is z-targeting, this is currently called targetActor.

So target and targetActor should be reserved for the z-targeting system, while trackActor -> focalActor is the currently proposed name for the LookAtActor, i.e. player or the main actor that the camera is pointing at

[engineer124]

Undrafting this and opening this up for proper PR review

[Kenix3]

Personally, I like target more than trackActor

In regards to actors, there are two distinct actors to consider:

Actor 1: The actor that the camera is pointing at. This was previously called "trackActor" but has since been changed to focalActor. In OoT, this is exclusively Player, but MM generalized this to be any actor

Actor 2: The actor that player is z-targeting, this is currently called targetActor.

So target and targetActor should be reserved for the z-targeting system, while trackActor -> focalActor is the currently proposed name for the LookAtActor, i.e. player or the main actor that the camera is pointing at

This sounds fine to me.

[engineer124]

I still don't like at being the only name since it reads like an adverb in some names

One idea I've been brainstoming is that SM64 has a section at the top of camera.c explaining "pitch/yaw/roll", which is a description I've adopted in this PR.

Perhaps I could add another section below clarifying the terms at/eye. Specifically, I could mention that any code with the term at in the file is in the context of a position, and not an adverb.