WIP rcamera redesign vector

[Crydsch]

rcamera re-design

This PR addresses the rcamera.h redesign as discussed in #2507.

This PR is very similar to #2542.
There we evaluated a quaternion-based design, but noticed a breaking change in
the camera struct. The new design was also more confusing to new users.
As raylib prioritizes simplicity for less-experienced users this was problematic.

This PR aims to keep the camera struct as close as possible to the old one
and not introduce breaking changes.
It therefore also keeps the more intuitive vector based implementation (position, target, up).

The discussed improvements can still be applied though!
Such as the low-level functions for easy custom camera control.

Note: Some changes may still be necessary to improve the camera module and implement the set requirements.

Key-Design notes

All static variables will be removed and the camera struct contains the entire camera state.
It can be directly manipulated at any time and the camera will function accordingly.
This gives users full control over the camera and allows customized modes.

All functions are available in all modes, there are no restrictions.
It may make no sense to use them though - this is at the users discretion.
I did this deliberately to allow for a maximum of freedom for the user.
For example, while at first glance a CameraRoll(..) makes no sense in the CAMERA_FIRST_PERSON mode,
it may be used to implement a "looking around the corner" feature.

The functions CameraYaw(..), CameraPitch(..) and CameraRoll(..) take an angle parameter (in radians) which allow precise manipulation.
A CameraYaw(camera, 90 * DEG2RAD); call results precisely in a 90 degree turn.

Behavioural differences to the old rcamera.h

• CAMERA_FREE is no longer a panning camera, but a real 3D free float camera.

API and usage

API

typedef struct Camera3D {
    Vector3 position;      // Camera position
    Vector3 target;        // Camera target it looks-at
    Vector3 up;            // Camera up vector (rotation around the view axis)
    float fovy;            // Camera field-of-view apperture in Y (degrees) in perspective, used as near plane width in orthographic
    int projection;        // Camera projection: CAMERA_PERSPECTIVE or CAMERA_ORTHOGRAPHIC
    int swingCounter;      // Camera view-bobbing. Set to 0 to deactivate
} Camera3D;

API exposed through raylib.h:
// Update camera position for selected mode
// Camera mode: CAMERA_FREE, CAMERA_FIRST_PERSON, CAMERA_THIRD_PERSON, CAMERA_ORBITAL or CUSTOM
void UpdateCamera(Camera3D *camera, int mode);

API exposed through rcamera.h:
// Returns the cameras forward vector (normalized)
Vector3 GetCameraForward(Camera3D* camera);
// Returns the cameras up vector (normalized)
Vector3 GetCameraUp(Camera3D* camera);
// Returns the cameras right vector (normalized)
Vector3 GetCameraRight(Camera3D* camera);
// Moves the camera in its forward direction
void CameraMoveForward(Camera3D *camera, float distance);
// Moves the camera in its up direction
void CameraMoveUp(Camera3D *camera, float distance);
// Moves the camera target in its right direction
void CameraMoveRight(Camera3D *camera, float distance);
// Moves the camera position closer/farther to/from the camera target
void CameraZoom(Camera3D *camera, float delta);
// Rotates the camera around its up vector
// Yaw is "looking left and right"
// Note: angle must be provided in radians
void CameraYaw(Camera3D *camera, float angle);
// Rotates the camera around its right vector
// Pitch is "looking up and down"
// Note: angle must be provided in radians
void CameraPitch(Camera3D *camera, float angle);
// Rotates the camera around its forward vector
// Roll is "turning your head sideways to the left or right"
// Note: angle must be provided in radians
void CameraRoll(Camera3D *camera, float angle);
// Moves camera slightly to simulate a walking motion
// Note: Only active if camera->swingCounter > 0
void CameraViewBobbing(Camera3D* camera);
// Returns the camera view matrix
Matrix GetCameraViewMatrix(Camera3D* camera);
// Returns the camera projection matrix
Matrix GetCameraProjectionMatrix(Camera3D *camera, float aspect);

Usage

Camera camera = { 0 };
camera.position = (Vector3){ 0.0f, 2.0f, 4.0f };
camera.target = (Vector3){ 0.0f, 2.0f, 0.0f };
camera.up = (Vector3){ 0.0f, 1.0f, 0.0f };
camera.fovy = 60.0f;
camera.projection = CAMERA_PERSPECTIVE;

Using raylib.h (raylib internally):
// This function will handle input and move/turn accordingly.
UpdateCamera(&camera, CAMERA_FIRST_PERSON);

Using rcamera.h (ex. in a different engine):
// Camera movement
if (IsKeyDown(KEY_W)) CameraMoveForward(camera, CAMERA_MOVE_SPEED, true);
if (IsKeyDown(KEY_S)) CameraMoveForward(camera, -CAMERA_MOVE_SPEED, true);
if (IsKeyDown(KEY_D)) CameraMoveRight(camera, CAMERA_MOVE_SPEED, true);
if (IsKeyDown(KEY_A)) CameraMoveRight(camera, -CAMERA_MOVE_SPEED, true);

// Camera rotation
Vector2 mousePositionDelta = GetMouseDelta();
CameraYaw(camera, mousePositionDelta.x * CAMERA_MOUSE_MOVE_SENSITIVITY, false);
CameraPitch(camera, mousePositionDelta.y * CAMERA_MOUSE_MOVE_SENSITIVITY, true, false, false);

TODO

• Core functionality + CAMERA_FREE
• Camera modes CAMERA_FIRST_PERSON, CAMERA_THIRD_PERSON, CAMERA_ORBITAL
• Adapt all examples
• View bobbing
• CAMERA_ORBITAL autorotation
• Frame time compensation
• New input system ?
• Review compatibility with old rcamera.h usage
• Review stand alone mode
• Check all examples for correct functionality/info boxes

Feedback

I'd much appreciate feedback!

If you want to have a look at the code or the demo, you can checkout my feature branch rcamera_redesign_vector or this PR..

The core_3d_camera_first_person example is functional and can be used for testing.

Note: The camera struct was extended by the camera mode and swingCounter (for view bobbing).
This should not be a breaking change, as the struct is initialized by Camera camera = { 0 };
and the camera mode is set with SetCameraMode(..);, both which always produce a valid state.

Edit: Updated API and usage to reflect current iteration (for quick overview)

[raysan5]

@Crydsch Thanks for the redesign, I like this approach more than previous one, less breaking changes and a code simplification. Adding the camera.mode was also considered in the past. Removing the globals in camera is fantastic!

I had problems to switch between camera modes without keeping some of those globals but I think it should be possible to do so without them... I just was not able to do it in the past.

I've been also doing some changes to rcamera.h lately because I needed them for a project, I basically implemented GetFrameTime()-based movements and simplified camera waiving and swinging (aka "bobbing"). For the moment I'm not pushing those changes, they still require some review... actually I find camera rotations implementation quite complex to follow.

As always, I prioritize code simplicity, in case someone in the future needs to review this API.

[Crydsch]

@raysan5 I am Glad to hear you like this approach better :)
I'll continue to work on it then.

The different camera modes will be interesting.
That's the next thing I want to get working.

Now that you mention FrameTime based movements...
I have been thinking about this too.
I posted my thoughts on this in the discussion #2507, as I think it fits better there.

View bobbing is another topic. If you have some simplifications for this,
that would be very helpful for reference! Even if it's not polished yet.
If you are OK with it, i would be very grateful even if you just sent me your changes directly.
I want to integrate view bobbing into the redesign eventually.

The camera rotation functions are not perfect yet - I agree.
In the current state only CAMERA_FREE is implemented, so they will change a bit
when adding the other camera modes anyway. I will try to improve them!

[Crydsch]

Camera modes

All remaining camera modes have been added!
I also tried to improve the rotation functions.

Switching between the different modes is now supported!

Further, I added a void CameraZoom(Camera3D *camera, float delta) function,
which can be usefull in the CAMERA_THIRD_PERSON and CAMERA_ORBITAL modes.

I noticed a small compilation issue with the SetCameraMode() function.
Previously it was defined as void SetCameraMode(Camera camera, int mode), but since we
now need to modify the mode it has been changed to void SetCameraMode(Camera *camera, int mode).
This is a very easy fix for the user though,
just calling it as SetCameraMode(&camera, mode) instead of SetCameraMode(camera, mode).

As in the previous PR, you can see and test everything in action in the core_3d_camera_first_person example.

New Input system

If you approve of the current state, I would like to continue with the
new input system. Here are some thoughts on this:

To stay backwards compatible and keep the simple API with UpdateCamera(), but
still be able to provide an engine agnostic mode I could think of two possibilities.

1. Wrap raylib specific input handling in an #if not defined(CAMERA_STANDALONE).
   or
2. Move the UpdateCamera() function out of the rcamera module and into rcore.

Version 1 makes more sense I think, in terms of where the camera logic is expected.
Version 2 would also create a coupling between the modules again.

If used in another engine the function UpdateCamera() is just not available
and the user is expected to use the new (engine agnostic) input system.

Also we then have to think about which keys to use in UpdateCamera().
One option would be to hardcode W, A, S, D, which is the sane default everywhere.
Or we can keep void SetCameraMoveControls(int keyFront, int keyBack, int keyRight, int keyLeft, int keyUp, int keyDown), if we also keep a global struct.

And lastly, what should we do with the funtions SetCameraPanControl(), SetCameraAltControl and SetCameraSmoothZoomControl?
These are inherently connected to a panning camera, which has been replaced with a real free camera.
We can either remove them, or add a panning camera mode and handle them similar to the
SetCameraMoveControls() function.
This really depends on whether we want to provide a panning camera mode or not - I am open for both.

[raysan5]

@Crydsch Amazing work! I need some time to review it properly and give you a better answer.

About the functions SetCamera*Controls() they can be removed. I don't know if anyone ever used them.

[Crydsch]

@raysan5 Sorry for pushing so quickly. Please take your time for the review, I just wanted to keep working on other parts in the meantime.
Also I had to force-push because I re-based to the upstream master - sorry.

View Bobbing

While trying to design the new input system I noticed that the view bobbing
needs to be investigated first. Especially since it needs to store some state to
produce the frame by frame animation.

Previously this was done with the int swingCounter static variable.
I kept this approach, but added it to the camera struct as we want to remove any static data.
This is no breaking change for the same reasons as with the addition of the camera mode.
The camera struct is normally initialized as Camera3D camera = {0};, which sets a valid state.
And typically followed by SetCameraMode(&camera, CAMERA_*);, which also enables or disables the view bobbing.

The view bobbing is disabled if swingCounter == 0 and can be enable by setting it to 1.
If enabled the counter is increased every frame and produces the animation.
It is automatically enabled with a call to SetCameraMode(&camera, CAMERA_FIRST_PERSON); and disabled for all other camera modes.
This provides ease of use and sane defaults, while still giving the user full control.

I kept the core behaviour as I am not to familiar with view bobbing.
Also I may not be the best to optimize the behaviour, as I personally get motion sick quickly and typically disable it in games I play.
Therefore the function void CameraViewBobbing(Camera3D* camera) may require some review by someone more familiar with it.

Adjusting all examples

The previous change from SetCameraMode(camera, CAMERA_*); to SetCameraMode(&camera, CAMERA_*); needed to be adjusted in all other examples to resolve the compilation issue.
The CI should now build everything correctly again :)
I started and checked every one and made sure they work.

Currently I adjusted the camera_first_person example to showcase all camera modes.
We could keep such a combined camera example (an remove the others) or revert to one example per mode.
Which do you prefer?

Some minor fixes were/are necessary in:

• models_mesh_picking allow toggling camera controls.
• core_3d_picking allow toggling camera controls.
• core_3d_camera_free info box text explaining controls. (not done yet)

New Input System ?

This comment got quite long, but I felt like explaining my thought process.
Therefore I moved it to the discussion #2507 here.

[GoodNike]

Please consider using delta time between frames for camera position calculation.

For now camera speed depends on target FPS, which may be a problem if FPS is adjustable or not stable.

[Crydsch]

@GoodNike
Thanks for mentioning it.
Yes, frame time compensation is planed. I added it to the todo list.

@raysan5
It's been a while since my last pushes, did you have time to review it?
Also I would like to hear what you think about the necessity of an additional input system
(on top of the low-level API).

[raysan5]

@Crydsch Excuse me for the late response! I couldn't check it yet, I've been out for a week and it's a big PR, I'll answer it properly by tomorrow! :)

[raysan5]

@Crydsch Just pushed the latest camera changes I was working on:

• Reviewed camera swinging (up-down movement)
• Reviewed camera tilting (left-right movement)
• Make movement independent of frame-rate
• Removed unneeded variables

It's been about a month but I didn't push them because there is still some issue on the camera rotation for the first-person view, it moves too fast when fixed to 60 fps, the framerate independant movement is not compretely right... in any case I pushed those changes in case they can be helpful for you as a reference.

About all your changes:

New signature for SetCameraMode(&camera, mode)

This is a breaking change and I'm still thinking about the best way to approach it... I understand that from a user point of view it's more intuitive to store the camera mode inside the camera structure but from a pure data point of view, mode only affects how the camera values are internally calculated in the next update. Think about it this way: if we change camera.mode but we don't call CameraUpdate(), nothing changes in the camera, actually, we can manually setup a custom camera independently of the mode stored. Mode only defines CameraUpdate() behaviour.

Still, I think a SetCameraMode(&camera, mode) is more intuitive than SetCameraMode(mode), that should probably be the right approach... Maybe it can just be replaced by a SetCameraUpdateMode(mode) or moved to UpdateCamera(&camera, mode)? Actually, I like that last function, it just passes to UpdateCamera() the required mode for calculation and camera remains agnostic of mode.

Did you try changing between modes at runtime? Does it work as expected? I remember having some issues with it...

New Input System

Personally I prefer option 1 for now, wrap raylib specific input handling in an #if !defined(CAMERA_STANDALONE).

About the keys to use, I would set some default ones as defines and let the user configure them recompiling the module. I would remove all external individual keys configuration and try to find a better solution for keys configuration...

Functions to remove/replace:

void SetCameraPanControl(int keyPan);                   // Set camera pan key to combine with mouse movement (free camera)
void SetCameraAltControl(int keyAlt);                   // Set camera alt key to combine with mouse movement (free camera)
void SetCameraSmoothZoomControl(int szoomKey);          // Set camera smooth zoom key to combine with mouse (free camera)
void SetCameraMoveControls(int keyFront, int keyBack,
                           int keyRight, int keyLeft,
                           int keyUp, int keyDown);     // Set camera move controls (1st person and 3rd person cameras)

In any case, I would keep a global structure for the input values that could be updated by the user if required, it can be just an int inputs[] with all the positions #defined to be updated like SetCameraControl(CAMERA_FIRST_PERSON_MOVE_FORDWARD, KEY_W).

It's not easy to find a good solution... there could be many types of controls involved and supporting all the options (keyboard, mouse, gamepad, touch...) it's almost impossible. Only the most common inputs that users usually wants to configure should be chosen, most of them could be probably just kept inside as #defines.

Camera swinging and tilting

I just pushed a commit with some improvements and clearer comments (and names) about how they work. About exposing those values to be configured by the user, maybe a similar approach to keys input can be used: SetCameraParams(CAMERA_FIRST_PERSON_MOVE_TILTING, 80). In any case, I would keep them internal to camera module because they are not part of the camera data, only define how next camera values are calculated (like the camera.mode).

I think that's it for now. Thank you very much again for all your hard work in this big improvement of the library.

[raysan5]

@Crydsch I'm checking the code more carefully and I see no quaternions are used for camera rotations, it keeps using the same previous Euler maths but now through the raymath functions...

[Crydsch]

@raysan5 The quaternion approach is fundamentally different and would have required a different camera struct (as per the first PR).
Calculating the current quat every frame, just to implement quat-based rotations and then reverting back and updating the vectors just does not make any sense. The code would be unnecessary complex and we would gain nothing from it.

But we can still improve the camera module with the low-level API, general API improvements, removing the static data, enabling the stand alone mode, ...

[raysan5]

Calculating the current quat every frame, just to implement quat-based rotations and then reverting back and updating the vectors just does not make any sense. The code would be unnecessary complex and we would gain nothing from it.

Agree.

[Crydsch]

@raysan5

I had a look at the change regarding camera->mode and found some problems.

1. SetCameraMode(..) includes other logic than just setting camera->mode.
   a) For one it calls DisableCursor(); to retain compatibility with the old camera module functionality. Of course we can shift this responsibility to the user. This makes especially sense, because such a function to catch the cursor is window-system/engine specific.
   b) It resets the up vector (roll) to help switching between camera modes.
   As with 1.a we can shift this responsibility to the user. Changing between camera modes is probably seldom used anyway.
   I guess most users set one mode at the beginning and never change it. If so, they would have to reset roll themselves.

2. camera->mode is not only used by UpdateCamera(..) but also by several low-level functions.
   We could solve this by passing it to those functions as well, it does clutter the API a bit though.

Should we continue with the change anyway?

[raysan5]

@Crydsch I see the issue with the camera.mode, some modes require some specific initialization, it's the same issue we have with current implementation. Probably that's unavoidable...

Which low-level functions depend on the camera.mode? I think they shouldn't depend on it, that's why they are low-level functions. It should be considered only on UpdateCamera() and call the required functions depending on it.

[Crydsch]

@raysan5

The low-level functions requiringcamera.mode are:

• CameraMoveForward(..) and CameraMoveRight(..)
  In the modes CAMERA_FIRST_PERSON and CAMERA_THIRD_PERSON we need to project the forward vector onto the world plane.
  We do not want to move downwards when the player is looking down.

• CameraYaw(..)
  In the modes CAMERA_FREE and CAMERA_FIRST_PERSON we need to rotate the target around the position.
  Whereas in CAMERA_THIRD_PERSON and CAMERA_ORBITAL we need to rotate the position around the target.

• CameraPitch(..)
  When pitching we need to clamp the pitch angle in the modes CAMERA_FIRST_PERSON, CAMERA_THIRD_PERSON and CAMERA_ORBITAL to lock the view vector when locking straight "up" or "down".
  Further, we need to apply the rotation as in CameraYaw(..).

As you can see, there are some dependencies on camera.mode, because the underlying math differs based on the current mode.
I don't think it can be avoided.

[raysan5]

@Crydsch I think those functions shouldn't depend on camera.mode, in any case, they could include some additional config parameter to accomodate on calling, depending on the mode (checked by caller).

For example:

void CameraMoveForward(Camera3D *camera, float distance, Vector3 axisLock);
void CameraPitch(Camera3D *camera, float angle, bool lockView);

[Crydsch]

@raysan5 That might be a possible fix. I'll have a look into those functions. With that change we can then remove camera.mode from the struct and pass it as an argument to UpdateCamera(..).

That would also mean that SetCameraMode(..) becomes obsolete, if we assume it's the users responsibility to reset camera.up when changing camera modes and calling DisableCursor() initially.
I think both those things are reasonable. Especially since DisableCursor() is engine/window system specific.

[Crydsch]

Hey @raysan5

Sorry it has been a while since I worked on this. The semester ended and I was on vacation.
But I found some time and worked on the changes we talked about.

The low-level functions now have additional parameters and no longer rely on camera.mode and it has been remove from the struct altogether.
I am a bit unsure about the variable naming. If you would like something different, please just let me know.
The mode is now passed to UpdateCamera(..). With this, SetCameraMode(..) was also removed.

While adjusting the examples to use the new UpdateCamera(..) function I also changed a few camera modes to something different than CAMERA_FREE where I felt like it gives a better experience, since CAMERA_FREE is now a real free float and just running an example should be easy (whereas the handling of CAMERA_FREE can be a bit confusing).

Looking at your review again, you mentioned removing the Get*Matrix functions, since in raylib the user can always use the same fucntion in raymath.
Still I think it makes sense to have them in the camera module logically, since I would search there first.
Also this may be very usefull in the stand-alone mode. (Even though raymath would be present then too...).
Should we remove or keep them?

Also I rebased onto master again.

PS: I found a new example missing from the VS2022 project ;)
models/models_loading_m3d

[raysan5]

@Crydsch Excuse me for this super-late response, it's a big change and it requires time to review but I can't find the moment to jump into it...

Taking a quick look, it seems and amazing improvement! It does not only simplify the API a lot but also opens a door for future improvements. I'll try to review it more carefully as soon as possible.

Thank you very much for all the work put into it!

[JeffM2501]

I like the general direction of the changes. I have some issues with a few of the names. There is also some inconsistent newline useage.
I am also not a fan of having the view bob data burned into the camera structure itself and the speed data hardcoded. I wonder if there may be benefit in having a camera state structure that keeps track of all the internal state data that the update method needs, like the bob, any mouse positions, and speeds, and have the user pass that in if they are using the built in camera update function.

[theia-ajax]

Hello, just reading through and finding this PR interesting because I've found the default camera behavior to be wanting for many of the reasons this PR exists.

I would just like to throw in my 2 cents that the entire view bobbing feature should just be removed or at least explicitly be an opt-in option for the camera. I would never expect in any engine or toolkit to switch to a default first person camera and get a view bobbing as part of that, especially a view bob that isn't readily configurable or quick to disable.

[nilsbecker]

Just to leave a note here: In the previous predefined cameras, the baked-in mouse buttons assigned to the different motions made it impossible e.g. to pan on macbooks with a touchpad. the new implementation should make sure to 1. choose compatible defaults 2. make buttons and modifier keys configurable in the predefined cameras.

[raysan5]

Merged new camera redesign, reviewing it carefully in following commits...