eic-opticks/sysrap/FlowAction.h

0001 #pragma once
0002
0003 /**
0004  * Flow-control actions shared by CSG traversal and photon propagation.
0005  *
0006  * FlowAction is returned by routines that advance either a CSG tree traversal
0007  * or a photon propagation step. The caller uses the action to decide whether
0008  * to continue the current loop, terminate it, or process a reached geometry
0009  * boundary. Keeping the action as a scoped enum prevents it from being mixed
0010  * accidentally with unrelated integer flags, indices, or error codes.
0011  *
0012  * The explicit unsigned underlying type preserves the compact representation
0013  * previously used by the unscoped enum. flow_action_name is a constexpr,
0014  * allocation-free formatter intended for diagnostics; it returns "UNKNOWN"
0015  * for values outside the defined enumeration.
0016  */
0017 enum class FlowAction : unsigned
0018 {
0019     Undefined, ///< No action has been selected.
0020     Break,     ///< Stop the current traversal or propagation loop.
0021     Continue,  ///< Continue the current traversal or propagation loop.
0022     Boundary,  ///< A geometry boundary was reached and needs handling.
0023     Pass,      ///< Pass control to the next processing stage.
0024     Start,     ///< Initial action before the first processing step.
0025     Return,    ///< Return control to the caller.
0026     Last       ///< Sentinel one past the final actionable value.
0027 };
0028
0029 /**
0030  * Returns the stable diagnostic name of a flow-control action.
0031  *
0032  * @param action Flow-control action to format.
0033  * @return Uppercase enumerator name, or "UNKNOWN" for an invalid value.
0034  */
0035 constexpr const char* flow_action_name(FlowAction action) noexcept
0036 {
0037     switch (action)
0038     {
0039     case FlowAction::Undefined:
0040         return "UNDEFINED";
0041     case FlowAction::Break:
0042         return "BREAK";
0043     case FlowAction::Continue:
0044         return "CONTINUE";
0045     case FlowAction::Boundary:
0046         return "BOUNDARY";
0047     case FlowAction::Pass:
0048         return "PASS";
0049     case FlowAction::Start:
0050         return "START";
0051     case FlowAction::Return:
0052         return "RETURN";
0053     case FlowAction::Last:
0054         return "LAST";
0055     }
0056     return "UNKNOWN";
0057 }