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//=============================================================================