From d12d44412cdefb5d4c6e16ae6cac1a7e5c5b396b Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 11:59:51 +0200 Subject: [PATCH 01/10] Clarify the operator relationship of ordinary and fixed-point numbers --- man/rgbasm.5 | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index a3b5c9511..1441693c0 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -381,11 +381,6 @@ to it followed by the number of fractional bits, such as .Ql 12.34q8 . .Pp Since fixed-point values are still just integers, you can use them in normal integer expressions. -Some integer operators like -.Sq + -and -.Sq - -don't care whether the operands are integers or fixed-point. You can easily truncate a fixed-point number into an integer by shifting it right by the number of fractional bits. It follows that you can convert an integer to a fixed-point number by shifting it left that same amount. .Pp @@ -418,6 +413,23 @@ delim $$ delim off .EN .Pp +Operators not in the list above, such as +.Sq + +and +.Sq - , +function correctly with fixed-point operands as well (but +.Em both +operands must be fixed-point: use +.Ql 1.0 + 2.0 , +not +.Ql 1.0 + 2 ; +and use +.Ql MUL(1.0, 2.0) +or +.Ql 1.0 * 2 , +not +.Ql MUL(1.0, 2) ) . +.Pp All of these fixed-point functions can take an optional final argument, which is the precision to use. For example, .Ql MUL(6.0q8, 7.0q8, 8) From a3c0a546c6803f2f4fc4ca75e34eccc19987d91a Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:27:04 +0200 Subject: [PATCH 02/10] Attempt to clarify description of fixed-point numbers --- man/rgbasm.5 | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 1441693c0..3d2d1b4d5 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -369,16 +369,26 @@ equals $roman clz ( n )$. delim off .EN .Ss Fixed-point expressions -Fixed-point numbers are basically normal (32-bit) integers, which count fractions instead of whole numbers. -They offer better precision than integers but limit the range of values. -By default, the upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths). -The default number of fractional bits can be changed with the +Fixed-point numbers are technically just integers, but conceptually they have a decimal point at a fixed location (hence the name). +This gives them increased precision, at the cost of a smaller range, while remaining far cheaper to manipulate than floating-point numbers (which +.Nm +does not support). +.Pp +The default precision of all fixed-point numbers is 16 bits, meaning the lower 16 bits are used for the fractional part; so they count in 65536ths of 1.0. +This precision can be changed with the .Fl Q -command-line option. -You can also specify a precise fixed-point value by appending a +command-line option, and/or by +.Ic OPT Q +.Pq see Sx Changing options while assembling . +An individual fixed-point literal can have its own precision overridden by appending a .Dq q -to it followed by the number of fractional bits, such as -.Ql 12.34q8 . +followed by the number of fractional bits: for example, +.Ql 1234.5q8 +is equal to $0004d280 +.EQ +delim $$ +.EN +($= 1234.5 * 2 sup 8$). .Pp Since fixed-point values are still just integers, you can use them in normal integer expressions. You can easily truncate a fixed-point number into an integer by shifting it right by the number of fractional bits. @@ -388,9 +398,6 @@ Note that the current number of fractional bits can be computed as .Ic TZCOUNT Ns Pq 1.0 . .Pp The following functions are designed to operate with fixed-point numbers: -.EQ -delim $$ -.EN .Bl -column -offset indent "ATAN2(y, x)" .It Sy Name Ta Sy Operation .It Fn DIV x y Ta Fixed-point division $( x \[di] y ) \[mu] ( 2 ^ precision )$ @@ -417,7 +424,7 @@ Operators not in the list above, such as .Sq + and .Sq - , -function correctly with fixed-point operands as well (but +work correctly with fixed-point operands as well (but .Em both operands must be fixed-point: use .Ql 1.0 + 2.0 , @@ -430,7 +437,7 @@ or not .Ql MUL(1.0, 2) ) . .Pp -All of these fixed-point functions can take an optional final argument, which is the precision to use. +All of these fixed-point functions can take an optional final argument, which is the precision to use for that one operation . For example, .Ql MUL(6.0q8, 7.0q8, 8) will evaluate to From 19bc54abefcbd8e54c58bbe110a3d8ba1075cca6 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:27:17 +0200 Subject: [PATCH 03/10] Note that RGBASM does not check fix-point precisions --- man/rgbasm.5 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 3d2d1b4d5..0a957535d 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -445,6 +445,12 @@ will evaluate to no matter what value is set as the current .Cm Q option. +.Nm +.Em does not check precisions for consistency , +so nonsensical input like +.Ql MUL(4.2q8, 6.9q12, 16) +will produce a nonsensical (but technically correct) result: +.Dq garbage in, garbage out . .Pp The .Ic FMOD From 885b4f14071b60d5f0a71d130c2ff86cbd9d52f8 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:41:49 +0200 Subject: [PATCH 04/10] Fix formatting of trig func list There was a space between the opening parens an `SIN` --- man/rgbasm.5 | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 0a957535d..af30317ca 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -464,11 +464,17 @@ this is the opposite of how the integer modulo operator .Sq % works! .Pp -The trigonometry functions ( -.Ic SIN , -.Ic COS , -.Ic TAN , -etc) are defined in terms of a circle divided into 1.0 "turns" (equal to 2pi radians or 360 degrees). +The trigonometry functions +.Pq Ic SIN , Ic COS , Ic TAN , No etc +are defined in terms of a circle divided into 1.0 +.Dq turns +.EQ +delim $$ +.EN +(equal to $2 pi$ radians, or 360 degrees). +.EQ +delim off +.EN .Pp These functions are useful for automatic generation of various tables. For example: From ce10e69c2f15cebe61ea0bd4cf7390b4c70f8560 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:45:48 +0200 Subject: [PATCH 05/10] Simplify sine table example a bit Use fewer magic constants, and a FOR loop. Also use a max input bound that isn't 1.0, to avoid confusion with the `1.0` that's used to shift the output range. --- man/rgbasm.5 | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index af30317ca..3dac32561 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -479,12 +479,11 @@ delim off These functions are useful for automatic generation of various tables. For example: .Bd -literal -offset indent -; Generate a table of sine values from sin(0.0) to sin(1.0), with -; amplitude scaled from [-1.0, 1.0] to [0.0, 128.0] -DEF turns = 0.0 -REPT 256 - db MUL(64.0, SIN(turns) + 1.0) >> 16 - DEF turns += 1.0 / 256 +; Generate a table of 128 sine values +; from sin(0.0) to sin(0.5) excluded, +; with amplitude scaled from [-1.0, 1.0] to [0.0, 128.0]. +FOR angle, 0.0, 0.5, 0.5 / 128 + db MUL(SIN(angle) + 1.0, 128.0 / 2) >> 16 ENDR .Ed .Ss String expressions From 3ea0be72e022c78d931b2ab19513a7a69d216053 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:47:40 +0200 Subject: [PATCH 06/10] Remove misleading equations describing `DIV`, `MUL`, and `FMOD` They were not equivalent, and besides, it seems more likely that the shifts would confuse newbies while not bringing useful info to experts. --- man/rgbasm.5 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 3dac32561..6e245212b 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -400,9 +400,9 @@ Note that the current number of fractional bits can be computed as The following functions are designed to operate with fixed-point numbers: .Bl -column -offset indent "ATAN2(y, x)" .It Sy Name Ta Sy Operation -.It Fn DIV x y Ta Fixed-point division $( x \[di] y ) \[mu] ( 2 ^ precision )$ -.It Fn MUL x y Ta Fixed-point multiplication $( x \[mu] y ) \[di] ( 2 ^ precision )$ -.It Fn FMOD x y Ta Fixed-point modulo $( x % y ) \[di] ( 2 ^ precision )$ +.It Fn DIV x y Ta Fixed-point division +.It Fn MUL x y Ta Fixed-point multiplication +.It Fn FMOD x y Ta Fixed-point modulo .It Fn POW x y Ta $x$ to the $y$ power .It Fn LOG x y Ta Logarithm of $x$ to the base $y$ .It Fn ROUND x Ta Round $x$ to the nearest integer From b56bd48165c4a7a2f19655f375b78c49f039c335 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Wed, 7 Aug 2024 12:54:44 +0200 Subject: [PATCH 07/10] Use more maths to describe the fixed-point functions This should help, I think? --- man/rgbasm.5 | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 6e245212b..ec2298cf5 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -403,17 +403,21 @@ The following functions are designed to operate with fixed-point numbers: .It Fn DIV x y Ta Fixed-point division .It Fn MUL x y Ta Fixed-point multiplication .It Fn FMOD x y Ta Fixed-point modulo -.It Fn POW x y Ta $x$ to the $y$ power -.It Fn LOG x y Ta Logarithm of $x$ to the base $y$ +.It Fn POW x y Ta $x sup y$ +.It Fn LOG x y Ta $log sub y ( x )$ (such that +.Ic LOG Ns ( Ic POW Ns ( x , y ) , y ) == x) .It Fn ROUND x Ta Round $x$ to the nearest integer -.It Fn CEIL x Ta Round $x$ up to an integer -.It Fn FLOOR x Ta Round $x$ down to an integer +.It Fn CEIL x Ta Round $x$ up to the nearest integer +.It Fn FLOOR x Ta Round $x$ down to the nearest integer .It Fn SIN x Ta Sine of $x$ .It Fn COS x Ta Cosine of $x$ .It Fn TAN x Ta Tangent of $x$ -.It Fn ASIN x Ta Inverse sine of $x$ -.It Fn ACOS x Ta Inverse cosine of $x$ -.It Fn ATAN x Ta Inverse tangent of $x$ +.It Fn ASIN x Ta Inverse sine of $x$ (such that +.Ic ASIN Ns ( Ic SIN Ns ( x ) ) == x) +.It Fn ACOS x Ta Inverse cosine of $x$ (such that +.Ic ACOS Ns ( Ic COS Ns ( x ) ) == x) +.It Fn ATAN x Ta Inverse tangent of $x$ (such that +.Ic ATAN Ns ( Ic TAN Ns ( x ) ) == x) .It Fn ATAN2 y x Ta Angle between $( x , y )$ and $( 1 , 0 )$ .El .EQ From 28615f1faeed0d01ffc939548df840a55e14c06a Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Thu, 8 Aug 2024 10:28:20 +0200 Subject: [PATCH 08/10] Improve wording of fixed-point operator warning --- man/rgbasm.5 | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index ec2298cf5..106b68da7 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -424,24 +424,25 @@ The following functions are designed to operate with fixed-point numbers: delim off .EN .Pp -Operators not in the list above, such as +There are no functions for fixed-point addition and subtraction, because the .Sq + and .Sq - , -work correctly with fixed-point operands as well (but -.Em both -operands must be fixed-point: use -.Ql 1.0 + 2.0 , -not -.Ql 1.0 + 2 ; -and use -.Ql MUL(1.0, 2.0) -or -.Ql 1.0 * 2 , -not -.Ql MUL(1.0, 2) ) . +operators can add and subtract pairs of fixed-point operands. +.Bd -ragged -offset indent +Note that some operators or functions are meaningful when combining integers and fixed-point values. +For example, +.Ql 2.0 * 3 +is equivalent to +.Ql MUL(2.0, 3.0) , +and +.Ql 6.0 / 2 +is equivalent to +.Ql DIV(6.0, 2.0) . +Be careful and think about what the operations mean when doing this sort of thing. +.Ed .Pp -All of these fixed-point functions can take an optional final argument, which is the precision to use for that one operation . +All of these fixed-point functions can take an optional final argument, which is the precision to use for that one operation. For example, .Ql MUL(6.0q8, 7.0q8, 8) will evaluate to From 4d2dcb940a12023a6ebc989a5ae865409892b428 Mon Sep 17 00:00:00 2001 From: Eldred Habert Date: Thu, 8 Aug 2024 18:18:34 +0200 Subject: [PATCH 09/10] Minor style fixups Co-authored-by: Sylvie <35663410+Rangi42@users.noreply.github.com> --- man/rgbasm.5 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 106b68da7..922f977bf 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -380,11 +380,11 @@ This precision can be changed with the command-line option, and/or by .Ic OPT Q .Pq see Sx Changing options while assembling . -An individual fixed-point literal can have its own precision overridden by appending a +An individual fixed-point literal can specify its own precision, overriding the current default, by appending a .Dq q followed by the number of fractional bits: for example, .Ql 1234.5q8 -is equal to $0004d280 +is equal to $0004d2_80 .EQ delim $$ .EN @@ -427,7 +427,7 @@ delim off There are no functions for fixed-point addition and subtraction, because the .Sq + and -.Sq - , +.Sq - operators can add and subtract pairs of fixed-point operands. .Bd -ragged -offset indent Note that some operators or functions are meaningful when combining integers and fixed-point values. From 923bb9499a947dd24000e48325418d4896b286cf Mon Sep 17 00:00:00 2001 From: Eldred Habert Date: Thu, 8 Aug 2024 19:03:25 +0200 Subject: [PATCH 10/10] Remove detailed explanations of some fixed-point funcs Co-authored-by: Sylvie <35663410+Rangi42@users.noreply.github.com> --- man/rgbasm.5 | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 922f977bf..7834e531e 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -404,20 +404,16 @@ The following functions are designed to operate with fixed-point numbers: .It Fn MUL x y Ta Fixed-point multiplication .It Fn FMOD x y Ta Fixed-point modulo .It Fn POW x y Ta $x sup y$ -.It Fn LOG x y Ta $log sub y ( x )$ (such that -.Ic LOG Ns ( Ic POW Ns ( x , y ) , y ) == x) +.It Fn LOG x y Ta Logarithm of $x$ to the base $y$ .It Fn ROUND x Ta Round $x$ to the nearest integer .It Fn CEIL x Ta Round $x$ up to the nearest integer .It Fn FLOOR x Ta Round $x$ down to the nearest integer .It Fn SIN x Ta Sine of $x$ .It Fn COS x Ta Cosine of $x$ .It Fn TAN x Ta Tangent of $x$ -.It Fn ASIN x Ta Inverse sine of $x$ (such that -.Ic ASIN Ns ( Ic SIN Ns ( x ) ) == x) -.It Fn ACOS x Ta Inverse cosine of $x$ (such that -.Ic ACOS Ns ( Ic COS Ns ( x ) ) == x) -.It Fn ATAN x Ta Inverse tangent of $x$ (such that -.Ic ATAN Ns ( Ic TAN Ns ( x ) ) == x) +.It Fn ASIN x Ta Inverse sine of $x$ +.It Fn ACOS x Ta Inverse cosine of $x$ +.It Fn ATAN x Ta Inverse tangent of $x$ .It Fn ATAN2 y x Ta Angle between $( x , y )$ and $( 1 , 0 )$ .El .EQ