Program Listing for File Ray.h

↰ Return to documentation for file (include/Karana/Math/Ray.h)

/*
 * Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
 *
 * NOTICE TO USER:
 *
 * This source code and/or documentation (the "Licensed Materials") is
 * the confidential and proprietary information of Karana Dynamics Inc.
 * Use of these Licensed Materials is governed by the terms and conditions
 * of a separate software license agreement between Karana Dynamics and the
 * Licensee ("License Agreement"). Unless expressly permitted under that
 * agreement, any reproduction, modification, distribution, or disclosure
 * of the Licensed Materials, in whole or in part, to any third party
 * without the prior written consent of Karana Dynamics is strictly prohibited.
 *
 * THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
 * KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
 * FITNESS FOR A PARTICULAR PURPOSE.
 *
 * IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
 * INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
 * OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
 *
 * U.S. Government End Users: The Licensed Materials are a "commercial item"
 * as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
 * only as a commercial end item under the terms of this license.
 *
 * Any use of the Licensed Materials in individual or commercial software must
 * include, in the user documentation and internal source code comments,
 * this Notice, Disclaimer, and U.S. Government Use Provision.
 */

/**
 * @file
 * @brief Contains the declarations for the Ray class.
 */

#pragma once

#include "Karana/Math/Defs.h"

namespace Karana::Math {
    /**
     * @class Ray
     * @brief Represents a 3D ray with an origin and direction.
     *
     * It is not required or checked that the direction has unit norm.
     */
    class Ray {
      public:
        /**
         * @brief No argument constructor
         *
         * Initializes direction to notReadyNaN and origin to zero.
         */
        Ray();

        /**
         * @brief Constructor from a pair of 3-vectors
         *
         * @param direction Direction of the ray
         * @param origin Origin of the ray
         */
        Ray(ConstVec3Slice direction, ConstVec3Slice origin = Vec3{0, 0, 0});

        /**
         * @brief Copy constructor.
         *
         * @param other The Ray to copy from.
         */
        Ray(const Ray &other);

        /**
         * @brief Copy assignment operator.
         *
         * @param other The Ray to assign from.
         * @return Reference to this object.
         */
        Ray &operator=(const Ray &other);

        /**
         * @brief Move constructor.
         *
         * @param other The Ray to move from.
         */
        Ray(Ray &&other) noexcept;

        /**
         * @brief Move assignment operator.
         *
         * @param other The Ray to move from.
         * @return Reference to this object.
         */
        Ray &operator=(Ray &&other) noexcept;

        /**
         * @brief Equality operator.
         *
         * @param other Another Ray to compare with.
         * @return True if both components are equal.
         */
        bool operator==(const Ray &other) const;

        /**
         * @brief Check if another ray is approximately equal within precision.
         *
         * @param other The Ray to compare to this one.
         * @param prec Precision tolerance.
         * @return True if approximately equal.
         */
        bool isApprox(const Ray &other, double prec = MATH_EPSILON) const;

        /**
         * @brief Get the direction of the ray.
         *
         * @return Const reference to the ray direction.
         */
        const Vec3 &getDirection() const;

        /**
         * @brief Set the direction of the ray.
         *
         * @param direction New direction.
         */
        void setDirection(ConstVec3Slice direction);

        /**
         * @brief Get the origin of the ray.
         *
         * @return Const reference to the ray origin.
         */
        const Vec3 &getOrigin() const;

        /**
         * @brief Set the origin of the ray.
         *
         * @param origin New origin.
         */
        void setOrigin(ConstVec3Slice origin);

        /**
         * @brief Return object type as a string.
         *
         * @return String "Ray".
         */
        std::string_view typeString() const;

        /**
         * @brief Dump the object as a formatted string.
         *
         * @param prefix Optional prefix for each line.
         * @param precision Number of digits to use for floating point values.
         * @param format_type The format type to use.
         * @param skip_new_line If true, do not add a new line at the end.
         * @return Formatted string representation.
         */
        std::string dumpString(std::string_view prefix = "",
                               unsigned int precision = 10,
                               DumpFormatType format_type = DumpFormatType::DEFAULT_FLOAT,
                               bool skip_new_line = false) const;

        /**
         * @brief Write dumpString to standard output.
         *
         * @param prefix Optional prefix for each line.
         * @param precision Number of digits to use for floating point values.
         * @param format_type The format type to use.
         */
        void dump(std::string_view prefix = "",
                  unsigned int precision = 10,
                  DumpFormatType format_type = DumpFormatType::DEFAULT_FLOAT) const;

        /**
         * @brief Mark the ray as not ready.
         */
        void makeNotReady();

        /**
         * @brief Check if the ray is initialized.
         *
         * @return True if both direction and origin are initialized.
         */
        bool isReady() const;

      private:
        /// Direction of the ray
        Vec3 _direction = {notReadyNaN, notReadyNaN, notReadyNaN};

        /// Origin of the ray
        Vec3 _origin = {0, 0, 0};
    };

} // namespace Karana::Math