Scalar API

This API is designed around performing various scalar operations, providing alternatives for routines typically found within <math.h>. 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 <sh4zam/shz_scalar.h>
• C++ header: #include <sh4zam/shz_scalar.hpp>
• Symbols: 56

Suffixes

Suffixes used in this module. The full list is in 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	Returns the minimum value of two given floats.
shz_fmaxf	Returns the maximum value of two given floats.
shz_equalf	Checks for equality based on EITHER the absolute tolerance or relative tolerance, using SHZ_FLT_EPSILON.
shz_equalf_abs	Checks for equality based on the absolute tolerance using SHZ_FLT_EPSILON.
shz_equalf_rel	Checks for equality based on the relative tolerance using SHZ_FLT_EPSILON.

Rounding

Routines for rounding and manipulating floats.

Symbol	Description
shz_floorf	Replacement for the <math.h> routine, floorf().
shz_ceilf	Replacement for the <math.h> routine, ceilf().
shz_roundf	Replacement for the <math.h> routine, roundf().
shz_truncf	Replacement for the <math.h> routine, truncf().
shz_remainderf	Replacement for the <math.h> routine, remainderf().
shz_fmodf	Replacement for the <math.h> routine, fmodf().
shz_remquof	(Sorta) Replacement for the <math.h> routine, remquof().

Mapping

Routines for mapping a number to another range.

Symbol	Description
shz_clampf	Clamps a floating-point value by the given min and max values.
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	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	Maps a value within the given range inputStart to inputEnd, to be within the range of outputStart to outputEnd.
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	Wraps the given value back to be within the range of min to max.
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	Returns the fractional part of x, equivalent to GLSL fract().
shz_signf	Returns -1.0f if x < 0, 0.0f if x == 0, or 1.0f if x > 0.
shz_saturatef	Clamps x to the range [0.0f, 1.0f].

Miscellaneous

Assorted routines implementing other fp operations.

Symbol	Description
shz_fabsf	Replacement for the <math.h> routine, fabsf().
shz_copysignf	Replacement for the <math.h> routine, copysignf().
shz_fmaf	Replacement for the <math.h> routine, fmaf().
shz_fdimf	Replacement for the <math.h> routine, fdimf(),.
shz_hypotf	Replacement for the <math.h> routine, hypotf().
shz_cbrtf	Replacement for the <math.h> routine, cbrtf().
shz_lerpf	Returns a value that is linearly interpolated between a and b by the given ratio, t.
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	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	Returns a random floating-point number between 0.0f and 1.0f, using and updating the given seed.
shz_randf_range	Returns a random floating-point number between min and max, using and updating the given seed.
shz_stepf	returns 0.0f if x < edge, otherwise 1.0f
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	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	Calculates 1.0f/sqrtf( x), using a fast approximation.
shz_inv_sqrtf	Calculates 1.0f/sqrtf( x ), using a fast approximation, while safely protecting against division-by-zero.
shz_sqrtf_fsrra	Returns the fast approximate square root of the given value, x.
shz_sqrtf	Returns the fast approximate square root of the given value, x, safely returning 0.0f is x == 0.0f.
shz_invf_fsrra	Takes the inverse of x using a very fast approximation, returning a positive result.
shz_invf	Takes the inverse of x using a slighty faster approximation than doing a full division, safely handling negative values.
shz_divf_fsrra	Divides num by denom using a very fast approximation, which requires denom be a positive value.
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	Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation.
shz_dot8f	Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation.
shz_mag_sqr3f	Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation.
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	Fast approximation for raising 2 to a floating-point power.
shz_powf	Fast approximation for C's powf().
shz_pow10f	Fast approximation of POSIX's pow10f().
shz_log2f	Fast approximation for C's log2f().
shz_logf	Fast approximation for C's logf().
shz_log10f	Fast approximation for C's log10f().
shz_expf	Fast approximation for C's expf().

Macros

Symbol	Description
SHZ_FLT_EPSILON	Floating-point epsilon used with inexact FP-based comparisons.