cdx_utils.h Source

  1//=============================================================================
  2//! @file
  3//! @author GEMS
  4//! @date   7 October 2026
  5//! @brief Byte ordering, sign extension and floating-point bit conversions.
  6//=============================================================================
  7// (c) Copyright 2026 General Engine Management Systems (GEMS) Ltd
  8//=============================================================================
  9
 10#ifndef CDX_UTILS_H_INCLUDED
 11#define CDX_UTILS_H_INCLUDED
 12//=============================================================================
 13
 14//=============================================================================
 15// Includes
 16//=============================================================================
 17
 18#if defined(CDX_USER_HEADER) && !defined(CDX_USER_H_INCLUDED)
 19#include CDX_USER_HEADER
 20#endif
 21
 22#include <stdint.h>
 23#include <string.h>
 24
 25#ifdef __cplusplus
 26extern "C" {
 27#endif
 28
 29//! @defgroup CDX_UTILS CDX Numeric Utilities
 30//! @{
 31//=============================================================================
 32// Types
 33//=============================================================================
 34
 35//! @brief 8-bit boolean type.
 36typedef uint8_t bool8_t;
 37//! @brief Ginmake-facing IEEE-754 binary32 scalar.
 38typedef float real32_t;
 39//! @brief Ginmake-facing IEEE-754 binary64 scalar.
 40typedef double real64_t;
 41
 42//=============================================================================
 43// Inline Functions
 44//=============================================================================
 45
 46//-----------------------------------------------------------------------------
 47//! @brief Reverse the byte order of a 16-bit integer.
 48//! @param value Integer to convert.
 49//! @return Integer with its bytes reversed.
 50static inline uint16_t CDX_byteswap16(uint16_t value)
 51{
 52    return (uint16_t)((value << 8u) | (value >> 8u));
 53}
 54//-----------------------------------------------------------------------------
 55//! @brief Reverse the byte order of a 32-bit integer.
 56//! @param value Integer to convert.
 57//! @return Integer with its bytes reversed.
 58static inline uint32_t CDX_byteswap32(uint32_t value)
 59{
 60    return ((uint32_t)CDX_byteswap16((uint16_t)value) << 16u) |
 61        CDX_byteswap16((uint16_t)(value >> 16u));
 62}
 63//-----------------------------------------------------------------------------
 64//! @brief Reverse the byte order of a 64-bit integer.
 65//! @param value Integer to convert.
 66//! @return Integer with its bytes reversed.
 67static inline uint64_t CDX_byteswap64(uint64_t value)
 68{
 69    return ((uint64_t)CDX_byteswap32((uint32_t)value) << 32u) |
 70        CDX_byteswap32((uint32_t)(value >> 32u));
 71}
 72//-----------------------------------------------------------------------------
 73//! @brief Return the IEEE-754 binary32 representation of a float.
 74//! @param value Floating-point value; no numeric conversion is performed.
 75//! @return The same bit pattern as an unsigned 32-bit integer.
 76static inline uint32_t CDX_reinterpret_cast_u32(float value)
 77{
 78    uint32_t result;
 79    memcpy(&result, &value, sizeof(result));
 80    return result;
 81}
 82//-----------------------------------------------------------------------------
 83//! @brief Return the IEEE-754 binary64 representation of a double.
 84//! @param value Floating-point value; no numeric conversion is performed.
 85//! @return The same bit pattern as an unsigned 64-bit integer.
 86static inline uint64_t CDX_reinterpret_cast_u64(double value)
 87{
 88    uint64_t result;
 89    memcpy(&result, &value, sizeof(result));
 90    return result;
 91}
 92//-----------------------------------------------------------------------------
 93//! @brief Interpret an unsigned 32-bit integer as IEEE-754 binary32 bits.
 94//! @param value Bit pattern; no numeric conversion is performed.
 95//! @return The float with that bit pattern, including NaNs and infinities.
 96static inline float CDX_reinterpret_cast_f32(uint32_t value)
 97{
 98    float result;
 99    memcpy(&result, &value, sizeof(result));
100    return result;
101}
102//-----------------------------------------------------------------------------
103//! @brief Interpret an unsigned 64-bit integer as IEEE-754 binary64 bits.
104//! @param value Bit pattern; no numeric conversion is performed.
105//! @return The double with that bit pattern, including NaNs and infinities.
106static inline double CDX_reinterpret_cast_f64(uint64_t value)
107{
108    double result;
109    memcpy(&result, &value, sizeof(result));
110    return result;
111}
112//=============================================================================
113// Prototypes
114//=============================================================================
115
116//-----------------------------------------------------------------------------
117//! @brief Sign-extend a raw signal to an 8-bit signed integer.
118//! @param bits Signal width; zero returns zero, widths above 8 are clamped to 8.
119//! @param value Raw signal; bits above the selected width are discarded.
120//! @return Signed value using the selected width's most significant bit as sign.
121int8_t CDX_sign_extend_u8(uint8_t bits, uint8_t value);
122
123//-----------------------------------------------------------------------------
124//! @brief Sign-extend a raw signal to a 16-bit signed integer.
125//! @param bits Signal width; zero returns zero, widths above 16 are clamped to 16.
126//! @param value Raw signal; bits above the selected width are discarded.
127//! @return Signed value using the selected width's most significant bit as sign.
128int16_t CDX_sign_extend_u16(uint8_t bits, uint16_t value);
129
130//-----------------------------------------------------------------------------
131//! @brief Sign-extend a raw signal to a 32-bit signed integer.
132//! @param bits Signal width; zero returns zero, widths above 32 are clamped to 32.
133//! @param value Raw signal; bits above the selected width are discarded.
134//! @return Signed value using the selected width's most significant bit as sign.
135int32_t CDX_sign_extend_u32(uint8_t bits, uint32_t value);
136
137//-----------------------------------------------------------------------------
138//! @brief Sign-extend a raw signal to a 64-bit signed integer.
139//! @param bits Signal width; zero returns zero, widths above 64 are clamped to 64.
140//! @param value Raw signal; bits above the selected width are discarded.
141//! @return Signed value using the selected width's most significant bit as sign.
142int64_t CDX_sign_extend_u64(uint8_t bits, uint64_t value);
143
144//-----------------------------------------------------------------------------
145//! @brief Test whether rounding to the nearest integer gives zero.
146//! @param value Floating-point value to test.
147//! @return Nonzero only for -0.5 < value < 0.5; false for NaN and either boundary.
148//! @note Half-way values are treated as rounding away from zero.
149uint8_t CDX_f32_rounds_to_zero(float value);
150
151//! @}
152#ifdef __cplusplus
153} // extern "C"
154#endif
155
156//=============================================================================
157#endif // CDX_UTILS_H_INCLUDED
158//=============================================================================
159// End of File
160//=============================================================================