Cameraz

include/nbl/builtin/hlsl/math/quaternions.hlsl

@@ -380,18 +380,150 @@ struct static_cast_helper<math::truncated_quaternion<T>, math::quaternion<T> >
 template<typename T>
 struct static_cast_helper<matrix<T,3,3>, math::quaternion<T> >
 {
-    static inline matrix<T,3,3> cast(const math::quaternion<T> q)
+    static inline matrix<T,3,3> cast(NBL_CONST_REF_ARG(math::quaternion<T>) q)
     {
         return q.__constructMatrix();
     }
 };
 
+template<typename T>
+inline bool is_finite_quaternion(NBL_CONST_REF_ARG(math::quaternion<T>) q)
+{
+    return !hlsl::isnan(q.data.x) &&
+        !hlsl::isnan(q.data.y) &&
+        !hlsl::isnan(q.data.z) &&
+        !hlsl::isnan(q.data.w);
+}
+
+template<typename T>
+inline T score_matrix_to_quaternion_cast_candidate(
+    NBL_CONST_REF_ARG(matrix<T,3,3>) target,
+    NBL_CONST_REF_ARG(math::quaternion<T>) candidate)
+{
+    if (!is_finite_quaternion(candidate))
+        return bit_cast<T>(numeric_limits<T>::infinity);
+
+    const vector<T,3> rebuiltRight = candidate.transformVector(vector<T,3>(T(1), T(0), T(0)), true);
+    const vector<T,3> rebuiltUp = candidate.transformVector(vector<T,3>(T(0), T(1), T(0)), true);
+    const vector<T,3> rebuiltForward = candidate.transformVector(vector<T,3>(T(0), T(0), T(1)), true);
+    return
+        hlsl::length(rebuiltRight - target[0]) +
+        hlsl::length(rebuiltUp - target[1]) +
+        hlsl::length(rebuiltForward - target[2]);
+}
+
+template<typename T>
+inline math::quaternion<T> direct_matrix_to_quaternion_cast(NBL_CONST_REF_ARG(matrix<T,3,3>) input)
+{
+    typedef math::quaternion<T> quaternion_t;
+    typedef typename quaternion_t::data_type data_type;
+
+    const T xLengthSq = hlsl::dot(input[0], input[0]);
+    const T yLengthSq = hlsl::dot(input[1], input[1]);
+    const T zLengthSq = hlsl::dot(input[2], input[2]);
+    const T uniformScaleSq = (xLengthSq + yLengthSq + zLengthSq) / T(3.0);
+    if (uniformScaleSq < numeric_limits<T>::min)
+    {
+        quaternion_t retval;
+        retval.data = hlsl::promote<data_type>(bit_cast<T>(numeric_limits<T>::quiet_NaN));
+        return retval;
+    }
+
+    const T uniformScale = hlsl::sqrt(uniformScaleSq);
+    matrix<T,3,3> m = input;
+    m /= uniformScale;
+
+    const T m00 = m[0][0];
+    const T m11 = m[1][1];
+    const T m22 = m[2][2];
+    const T neg_m00 = -m00;
+    const T neg_m11 = -m11;
+    const T neg_m22 = -m22;
+    const data_type Qx = data_type(m00, m00, neg_m00, neg_m00);
+    const data_type Qy = data_type(m11, neg_m11, m11, neg_m11);
+    const data_type Qz = data_type(m22, neg_m22, neg_m22, m22);
+    const data_type tmp = Qx + Qy + Qz;
+
+    quaternion_t retval;
+    if (tmp.x > T(0.0))
+    {
+        const T scales = hlsl::sqrt(tmp.x + T(1.0));
+        const T invscales = T(0.5) / scales;
+        retval.data.x = (m[2][1] - m[1][2]) * invscales;
+        retval.data.y = (m[0][2] - m[2][0]) * invscales;
+        retval.data.z = (m[1][0] - m[0][1]) * invscales;
+        retval.data.w = scales * T(0.5);
+    }
+    else if (tmp.y > T(0.0))
+    {
+        const T scales = hlsl::sqrt(tmp.y + T(1.0));
+        const T invscales = T(0.5) / scales;
+        retval.data.x = scales * T(0.5);
+        retval.data.y = (m[0][1] + m[1][0]) * invscales;
+        retval.data.z = (m[2][0] + m[0][2]) * invscales;
+        retval.data.w = (m[2][1] - m[1][2]) * invscales;
+    }
+    else if (tmp.z > T(0.0))
+    {
+        const T scales = hlsl::sqrt(tmp.z + T(1.0));
+        const T invscales = T(0.5) / scales;
+        retval.data.x = (m[0][1] + m[1][0]) * invscales;
+        retval.data.y = scales * T(0.5);
+        retval.data.z = (m[1][2] + m[2][1]) * invscales;
+        retval.data.w = (m[0][2] - m[2][0]) * invscales;
+    }
+    else
+    {
+        const T scales = hlsl::sqrt(tmp.w + T(1.0));
+        const T invscales = T(0.5) / scales;
+        retval.data.x = (m[0][2] + m[2][0]) * invscales;
+        retval.data.y = (m[1][2] + m[2][1]) * invscales;
+        retval.data.z = scales * T(0.5);
+        retval.data.w = (m[1][0] - m[0][1]) * invscales;
+    }
+
+    retval.data *= uniformScale;
+    return retval;
+}
+
+template<typename T>
+inline math::quaternion<T> matrix_to_quaternion_cast(NBL_CONST_REF_ARG(matrix<T,3,3>) m)
+{
+    const math::quaternion<T> directCandidate = math::quaternion<T>::create(m, true);
+    const math::quaternion<T> transposedCandidate = math::quaternion<T>::create(hlsl::transpose(m), true);
+    const math::quaternion<T> directFallback = direct_matrix_to_quaternion_cast(m);
+    const math::quaternion<T> transposedFallback = direct_matrix_to_quaternion_cast(hlsl::transpose(m));
+
+    const T directScore = score_matrix_to_quaternion_cast_candidate(m, directCandidate);
+    const T transposedScore = score_matrix_to_quaternion_cast_candidate(m, transposedCandidate);
+    const T directFallbackScore = score_matrix_to_quaternion_cast_candidate(m, directFallback);
+    const T transposedFallbackScore = score_matrix_to_quaternion_cast_candidate(m, transposedFallback);
+
+    math::quaternion<T> bestCandidate = directCandidate;
+    T bestScore = directScore;
+
+    if (transposedScore < bestScore)
+    {
+        bestCandidate = transposedCandidate;
+        bestScore = transposedScore;
+    }
+    if (directFallbackScore < bestScore)
+    {
+        bestCandidate = directFallback;
+        bestScore = directFallbackScore;
+    }
+    if (transposedFallbackScore < bestScore)
+        bestCandidate = transposedFallback;
+
+    return bestCandidate;
+}
+
 template<typename T>
 struct static_cast_helper<math::quaternion<T>, matrix<T,3,3> >
 {
-    static inline math::quaternion<T> cast(const matrix<T,3,3> m)
+    static inline math::quaternion<T> cast(NBL_CONST_REF_ARG(matrix<T,3,3>) m)
     {
-        return math::quaternion<T>::create(m, true);
+        return matrix_to_quaternion_cast(m);
     }
 };
 }

include/nbl/ext/Cameras/CArcballCamera.hpp

@@ -0,0 +1,89 @@
+// Copyright (C) 2018-2024 - DevSH Graphics Programming Sp. z O.O.
+// This file is part of the "Nabla Engine".
+// For conditions of distribution and use, see copyright notice in nabla.h
+
+#ifndef _C_ARCBALL_CAMERA_HPP_
+#define _C_ARCBALL_CAMERA_HPP_
+
+#include <algorithm>
+#include <cmath>
+
+#include "CSphericalTargetCamera.hpp"
+
+namespace nbl::core
+{
+
+/// @brief Target-relative camera with planar target translation and bounded arcball orbiting.
+///
+/// The runtime state is inherited from `CSphericalTargetCamera`. Translation
+/// moves the target in the current view plane. Rotation updates orbit yaw and
+/// pitch under a symmetric pitch limit.
+class CArcballCamera final : public CSphericalTargetCamera
+{
+public:
+    using base_t = CSphericalTargetCamera;
+
+    CArcballCamera(const hlsl::float64_t3& position, const hlsl::float64_t3& target)
+        : base_t(position, target)
+    {
+        m_orbitUv.y = std::clamp(m_orbitUv.y, MinPitch, MaxPitch);
+        applyPose();
+    }
+    ~CArcballCamera() = default;
+
+    const typename base_t::CGimbal& getGimbal() override { return m_gimbal; }
+
+    /// @brief Apply one frame of semantic translation and rotation input to the arcball rig.
+    virtual bool manipulate(std::span<const CVirtualGimbalEvent> virtualEvents, const hlsl::float64_t4x4* referenceFrame = nullptr) override
+    {
+        if (not virtualEvents.size() and not referenceFrame)
+            return false;
+
+        if (referenceFrame)
+        {
+            CReferenceTransform reference = {};
+            SCameraTargetRelativeState resolvedState = {};
+            if (!tryExtractReferenceTransform(reference, referenceFrame) ||
+                !tryResolveReferenceTargetRelativeState(reference, resolvedState))
+            {
+                return false;
+            }
+
+            resolvedState.orbitUv.y = std::clamp(resolvedState.orbitUv.y, MinPitch, MaxPitch);
+            adoptTargetRelativeState(resolvedState);
+        }
+
+        const auto impulse = m_gimbal.accumulate<AllowedVirtualEvents>(virtualEvents);
+
+        const auto deltaRotation = scaleVirtualRotation(impulse.dVirtualRotation);
+        const auto deltaTranslation = scaleVirtualTranslation(impulse.dVirtualTranslate);
+        const double deltaDistance = scaleUnscaledVirtualTranslation(impulse.dVirtualTranslate.z);
+
+        m_orbitUv.x += deltaRotation.y;
+        m_orbitUv.y = std::clamp(m_orbitUv.y + deltaRotation.x, MinPitch, MaxPitch);
+        m_distance = std::clamp<float>(m_distance + static_cast<float>(deltaDistance), MinDistance, MaxDistance);
+
+        const auto basis = computeBasis(m_orbitUv, m_distance);
+        applyPlanarTargetTranslation(deltaTranslation, basis);
+
+        return applyPose();
+    }
+
+    virtual uint32_t getAllowedVirtualEvents() const override { return AllowedVirtualEvents; }
+    virtual CameraKind getKind() const override { return CameraKind::Arcball; }
+    /// @brief Return the stable user-facing identifier for this concrete camera kind.
+    virtual std::string_view getIdentifier() const override { return "Arcball Camera"; }
+
+    static inline constexpr float MinDistance = base_t::MinDistance;
+    static inline constexpr float MaxDistance = base_t::MaxDistance;
+
+private:
+
+    static inline constexpr auto AllowedVirtualEvents = CVirtualGimbalEvent::Translate | CVirtualGimbalEvent::Rotate;
+    static inline constexpr double MaxPitch = SCameraTargetRelativeRigDefaults::ArcballPitchLimitRad;
+    static inline constexpr double MinPitch = -MaxPitch;
+};
+
+}
+
+#endif

include/nbl/ext/Cameras/CCameraFileUtilities.hpp

@@ -0,0 +1,94 @@
+#ifndef _C_CAMERA_FILE_UTILITIES_HPP_
+#define _C_CAMERA_FILE_UTILITIES_HPP_
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "nbl/system/IFile.h"
+#include "nbl/system/ISystem.h"
+
+namespace nbl::system
+{
+
+/// @brief Shared file I/O helpers used by camera persistence and scripted-runtime loaders.
+///
+/// The helpers keep camera-facing persistence code independent from ad-hoc file
+/// handling and provide one place for consistent error propagation.
+struct CCameraFileUtilities final
+{
+public:
+    /// @brief Read a whole file into a byte buffer.
+    static inline bool readBinaryFile(
+        ISystem& system,
+        const path& filePath,
+        std::vector<uint8_t>& outPayload,
+        std::string* error = nullptr,
+        const std::string_view openError = {})
+    {
+        ISystem::future_t<core::smart_refctd_ptr<IFile>> future;
+        system.createFile(future, filePath, IFile::ECF_READ | IFile::ECF_MAPPABLE);
+        auto file = future.acquire();
+        if (!file || !file->get())
+        {
+            if (error && !openError.empty())
+                *error = std::string(openError);
+            return false;
+        }
+
+        auto& input = *file->get();
+        const auto fileSize = input.getSize();
+        outPayload.resize(fileSize);
+        if (outPayload.empty())
+            return true;
+
+        IFile::success_t readResult;
+        input.read(readResult, outPayload.data(), 0, fileSize);
+        if (!static_cast<bool>(readResult))
+        {
+            if (error && !openError.empty())
+                *error = std::string(openError);
+            return false;
+        }
+        return true;
+    }
+
+    /// @brief Read a whole file and interpret its payload as UTF-8 text.
+    static inline bool readTextFile(
+        ISystem& system,
+        const path& filePath,
+        std::string& outText,
+        std::string* error = nullptr,
+        const std::string_view openError = {})
+    {
+        std::vector<uint8_t> payload;
+        if (!readBinaryFile(system, filePath, payload, error, openError))
+            return false;
+
+        outText.assign(reinterpret_cast<const char*>(payload.data()), payload.size());
+        return true;
+    }
+
+    /// @brief Overwrite a file with the provided text payload.
+    static inline bool writeTextFile(
+        ISystem& system,
+        const path& filePath,
+        const std::string_view text)
+    {
+        ISystem::future_t<core::smart_refctd_ptr<IFile>> future;
+        system.createFile(future, filePath, IFile::ECF_WRITE);
+        auto file = future.acquire();
+        if (!file || !file->get())
+            return false;
+        if (text.empty())
+            return true;
+
+        IFile::success_t writeResult;
+        (*file)->write(writeResult, text.data(), 0, text.size());
+        return static_cast<bool>(writeResult);
+    }
+};
+
+} // namespace nbl::system
+
+#endif // _C_CAMERA_FILE_UTILITIES_HPP_