# Scalar API Source: https://sh4zam.com/api/scalar/ > Scalar functions and utilities, including faster replacements This API is designed around performing various scalar operations, providing alternatives for routines typically found within ``. Many are drop-in replacements that beat libm on the SH4 by staying in single-precision `float`: no libm call and no promotion to `double`. Unlike the standard C floating-point routines, these routines are often saving cycles by not handling NaN and INF values as well as by not reporting rounding and domain errors back to the user. The `_fsrra` variants use the SH4 `FSRRA` instruction (fast approximate reciprocal square root) and the FIPR helpers run raw dot products through the vector FPU. In C++ every routine is also available as an alias in `namespace shz` with the `shz_` prefix dropped, for example `shz::floorf`. - **C header:** `#include ` - **C++ header:** `#include ` - **Symbols:** 56 ## Suffixes Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/). - `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. - `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ## Comparisons Routines for comparing and classifying floating-point values. | Symbol | Description | | --- | --- | | [`shz_fminf`](https://sh4zam.com/api/scalar/shz_fminf/) | Returns the minimum value of two given floats. | | [`shz_fmaxf`](https://sh4zam.com/api/scalar/shz_fmaxf/) | Returns the maximum value of two given floats. | | [`shz_equalf`](https://sh4zam.com/api/scalar/shz_equalf/) | Checks for equality based on EITHER the absolute tolerance or relative tolerance, using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). | | [`shz_equalf_abs`](https://sh4zam.com/api/scalar/shz_equalf_abs/) | Checks for equality based on the absolute tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). | | [`shz_equalf_rel`](https://sh4zam.com/api/scalar/shz_equalf_rel/) | Checks for equality based on the relative tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). | ## Rounding Routines for rounding and manipulating floats. | Symbol | Description | | --- | --- | | [`shz_floorf`](https://sh4zam.com/api/scalar/shz_floorf/) | Replacement for the \ routine, floorf(). | | [`shz_ceilf`](https://sh4zam.com/api/scalar/shz_ceilf/) | Replacement for the \ routine, ceilf(). | | [`shz_roundf`](https://sh4zam.com/api/scalar/shz_roundf/) | Replacement for the \ routine, roundf(). | | [`shz_truncf`](https://sh4zam.com/api/scalar/shz_truncf/) | Replacement for the \ routine, truncf(). | | [`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/) | Replacement for the \ routine, remainderf(). | | [`shz_fmodf`](https://sh4zam.com/api/scalar/shz_fmodf/) | Replacement for the \ routine, fmodf(). | | [`shz_remquof`](https://sh4zam.com/api/scalar/shz_remquof/) | (Sorta) Replacement for the \ routine, remquof(). | ## Mapping Routines for mapping a number to another range. | Symbol | Description | | --- | --- | | [`shz_clampf`](https://sh4zam.com/api/scalar/shz_clampf/) | Clamps a floating-point value by the given `min` and `max` values. | | [`shz_normalizef`](https://sh4zam.com/api/scalar/shz_normalizef/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f += 1.0f`. | | [`shz_normalizef_fsrra`](https://sh4zam.com/api/scalar/shz_normalizef_fsrra/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f + 1.0f` more quickly, provided `to` - `from` is a positive difference. | | [`shz_remapf`](https://sh4zam.com/api/scalar/shz_remapf/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd`. | | [`shz_remapf_fsrra`](https://sh4zam.com/api/scalar/shz_remapf_fsrra/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd` more quickly, provided the `outputEnd` - `outputStart` is a positive difference. | | [`shz_wrapf`](https://sh4zam.com/api/scalar/shz_wrapf/) | Wraps the given `value` back to be within the range of `min` to `max`. | | [`shz_wrapf_fsrra`](https://sh4zam.com/api/scalar/shz_wrapf_fsrra/) | Wraps the given `value` back to be within the range of `min` to `max` more quickly, provided `max` - `min` is a positive difference. | | [`shz_fractf`](https://sh4zam.com/api/scalar/shz_fractf/) | Returns the fractional part of `x`, equivalent to GLSL `fract()`. | | [`shz_signf`](https://sh4zam.com/api/scalar/shz_signf/) | Returns -1.0f if `x` \< 0, 0.0f if `x` == 0, or 1.0f if `x` > 0. | | [`shz_saturatef`](https://sh4zam.com/api/scalar/shz_saturatef/) | Clamps `x` to the range \[0.0f, 1.0f\]. | ## Miscellaneous Assorted routines implementing other fp operations. | Symbol | Description | | --- | --- | | [`shz_fabsf`](https://sh4zam.com/api/scalar/shz_fabsf/) | Replacement for the \ routine, fabsf(). | | [`shz_copysignf`](https://sh4zam.com/api/scalar/shz_copysignf/) | Replacement for the \ routine, copysignf(). | | [`shz_fmaf`](https://sh4zam.com/api/scalar/shz_fmaf/) | Replacement for the \ routine, fmaf(). | | [`shz_fdimf`](https://sh4zam.com/api/scalar/shz_fdimf/) | Replacement for the \ routine, fdimf(),. | | [`shz_hypotf`](https://sh4zam.com/api/scalar/shz_hypotf/) | Replacement for the \ routine, hypotf(). | | [`shz_cbrtf`](https://sh4zam.com/api/scalar/shz_cbrtf/) | Replacement for the \ routine, cbrtf(). | | [`shz_lerpf`](https://sh4zam.com/api/scalar/shz_lerpf/) | Returns a value that is linearly interpolated between `a` and `b` by the given ratio, `t`. | | [`shz_barycentric_lerpf`](https://sh4zam.com/api/scalar/shz_barycentric_lerpf/) | Returns a value that is barycentrically interpolated between `a`, `b`, and `c` using the given barycentric coordinates, `u` and `v`. | | [`shz_quadratic_roots`](https://sh4zam.com/api/scalar/shz_quadratic_roots/) | Uses the quadratic formula with the given coefficients to solve for the two roots, returning `true` if any real roots exist, and `false` if the roots are only imaginary. | | [`shz_randf`](https://sh4zam.com/api/scalar/shz_randf/) | Returns a random floating-point number between `0.0f` and `1.0f`, using and updating the given seed. | | [`shz_randf_range`](https://sh4zam.com/api/scalar/shz_randf_range/) | Returns a random floating-point number between `min` and `max`, using and updating the given seed. | | [`shz_stepf`](https://sh4zam.com/api/scalar/shz_stepf/) | returns 0.0f if x \< edge, otherwise 1.0f | | [`shz_smoothstepf`](https://sh4zam.com/api/scalar/shz_smoothstepf/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. edge0 must be less than edge1 or result is undefined. | | [`shz_smoothstepf_safe`](https://sh4zam.com/api/scalar/shz_smoothstepf_safe/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges. | ## FSRRA Routines built around fast reciprocal square root instruction. | Symbol | Description | | --- | --- | | [`shz_inv_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_inv_sqrtf_fsrra/) | Calculates 1.0f/sqrtf( `x`), using a fast approximation. | | [`shz_inv_sqrtf`](https://sh4zam.com/api/scalar/shz_inv_sqrtf/) | Calculates 1.0f/sqrtf( `x` ), using a fast approximation, while safely protecting against division-by-zero. | | [`shz_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_sqrtf_fsrra/) | Returns the fast approximate square root of the given value, `x`. | | [`shz_sqrtf`](https://sh4zam.com/api/scalar/shz_sqrtf/) | Returns the fast approximate square root of the given value, `x`, safely returning `0.0f` is `x` == `0.0f`. | | [`shz_invf_fsrra`](https://sh4zam.com/api/scalar/shz_invf_fsrra/) | Takes the inverse of `x` using a very fast approximation, returning a positive result. | | [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/) | Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values. | | [`shz_divf_fsrra`](https://sh4zam.com/api/scalar/shz_divf_fsrra/) | Divides `num` by `denom` using a very fast approximation, which requires `denom` be a positive value. | | [`shz_divf`](https://sh4zam.com/api/scalar/shz_divf/) | Divides `num` by `denom` using a slightly faster approximation, allowing `denom` to be negative. | ## FIPR Routines built around fast 4D dot product. | Symbol | Description | | --- | --- | | [`shz_dot6f`](https://sh4zam.com/api/scalar/shz_dot6f/) | Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation. | | [`shz_dot8f`](https://sh4zam.com/api/scalar/shz_dot8f/) | Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation. | | [`shz_mag_sqr3f`](https://sh4zam.com/api/scalar/shz_mag_sqr3f/) | Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation. | | [`shz_mag_sqr4f`](https://sh4zam.com/api/scalar/shz_mag_sqr4f/) | Takes a 4D vector as 4 floats and calculates its squared magnitude using a fast approximation. | ## Transcendental Fast approximations for non-trig transcendental functions. | Symbol | Description | | --- | --- | | [`shz_pow2f`](https://sh4zam.com/api/scalar/shz_pow2f/) | Fast approximation for raising 2 to a floating-point power. | | [`shz_powf`](https://sh4zam.com/api/scalar/shz_powf/) | Fast approximation for C's powf(). | | [`shz_pow10f`](https://sh4zam.com/api/scalar/shz_pow10f/) | Fast approximation of POSIX's pow10f(). | | [`shz_log2f`](https://sh4zam.com/api/scalar/shz_log2f/) | Fast approximation for C's log2f(). | | [`shz_logf`](https://sh4zam.com/api/scalar/shz_logf/) | Fast approximation for C's logf(). | | [`shz_log10f`](https://sh4zam.com/api/scalar/shz_log10f/) | Fast approximation for C's log10f(). | | [`shz_expf`](https://sh4zam.com/api/scalar/shz_expf/) | Fast approximation for C's expf(). | ## Macros | Symbol | Description | | --- | --- | | [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/) | Floating-point epsilon used with inexact FP-based comparisons. |