From 33762e4b0e4b94d15dd9e239bfb07d3c436c9d01 Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 00:49:31 +0200 Subject: [PATCH 1/7] docs: change light theme to use gray header This mimics ZX Spectrum boot BASIC cursor colors --- docs/overrides/stylesheets/extra.css | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/overrides/stylesheets/extra.css b/docs/overrides/stylesheets/extra.css index 1f6140e11..653053b47 100644 --- a/docs/overrides/stylesheets/extra.css +++ b/docs/overrides/stylesheets/extra.css @@ -9,21 +9,29 @@ /* Apply Sinclair Logo font to the main header */ /* Light mode - very light yellow header */ [data-md-color-scheme="default"] .md-header { - background-color: #264eb2; /* Very light yellow background color */ + background-color: #d0d6da; /* Very light yellow background color */ + height: 8em; } [data-md-color-scheme="default"] .md-header__title { - color: #ffde06; + color: #23231c; + padding-left: 2em; } /* Dark mode - dark gray header */ [data-md-color-scheme="slate"] .md-header { background-color: #333333; /* Dark gray background color */ + /*background-image: url('../img/boriel-basic-sinclair.png');*/ + /*background-repeat: no-repeat;*/ + /*background-position: center center;*/ + /*background-size: auto 90%;*/ + height: 8em; } [data-md-color-scheme="slate"] .md-header__title { color: #af0d0d; + padding-left: 2em; } .md-header__title { @@ -40,11 +48,13 @@ background-repeat: no-repeat; background-position: left center; background-size: auto 100%; + height: 100%; } /*!* Make the logo size 100% of the header *!*/ .md-header__button.md-logo { color: #ff000000; + height: 100%; } /* Increase font weight for headings */ @@ -54,11 +64,11 @@ h1, h2, h3, h4, h5, h6 { } /* Target Material theme specific heading classes if any */ -.md-typeset h1, -.md-typeset h2, -.md-typeset h3, -.md-typeset h4, -.md-typeset h5, +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4, +.md-typeset h5, .md-typeset h6 { font-weight: 600; /* Bold */ } From 52cc174b170bb3889635822c7a218da27e931e62 Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 00:56:16 +0200 Subject: [PATCH 2/7] docs: updates types.md page --- docs/types.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/types.md b/docs/types.md index 1e503690b..734d24b0e 100644 --- a/docs/types.md +++ b/docs/types.md @@ -1,6 +1,6 @@ # Types -## Introductions +## Introduction Although ZX BASIC was originally designed with ZX Spectrum in mind, it is a three-stage _retargeable_ compiler. This means it should not be difficult to hack ZX BASIC SDK to compile for other target machines (E.g. Commodore 64) or current machines (PC) or even virtual machines like Java or .NET. Porting ZX BASIC to other Z80 architectures like Amstrad or MSX should be almost straightforward (only the library.asm should need some work to use different ROM routines). @@ -25,14 +25,14 @@ They can be _unsigned_ (their value is always 0 or positive) or _signed_ (can ta ZX Basic integer types sizes are 8, 16 and 32 bits. Unsigned types have the prefix _U_. -| Type name | Size (bytes) | Signed? | Range | Description | -|:-----------|:-----:|:--------:|:------:|:-------------| -| Byte | 1 | yes | -128..127 | 8 bits signed integer | -| UByte| 1 | no | 0..255 | 8 bits unsigned integer | -| Integer | 2 | yes | -32768..32767 | 16 bits signed integer | -| UInteger | 2 | no | 0..65535 | 16 bits unsigned integer | -| Long | 4 | yes | −2,147,483,648 .. +2,147,483,647 | 32 bit signed integer | -| ULong | 4 | yes | 0 .. 4,294,967,295| 32 bit unsigned integer | +| Type name | Size (bytes) | Signed? | Range | Description | +|:----------|:------------:|:-------:|:-----------------------------------------------:|:-------------------------| +| Byte | 1 | yes | -128..127 | 8 bits signed integer | +| UByte | 1 | no | 0..255 | 8 bits unsigned integer | +| Integer | 2 | yes | -32768..32767 | 16 bits signed integer | +| UInteger | 2 | no | 0..65535 | 16 bits unsigned integer | +| Long | 4 | yes | −2,147,483,648 .. +2,147,483,647 | 32 bit signed integer | +| ULong | 4 | yes | 0 .. 4,294,967,295 | 32 bit unsigned integer | ### Decimals @@ -41,7 +41,7 @@ Their sizes are 32 bit for `Fixed` type and 40 bits for `Float` one. #### Fixed 32 bit Fixed Point decimal. First 16 bits are the integer part, whilst remaining 16 contains the decimal one. -Ranges from -32767.9999847 to 32767.9999847 with a precision of 1 / 2^16 (0.000015 approx.). +Ranges from `-32767.9999847` to `32767.9999847` with a precision of 1 / 216 (0.000015 approx.). Fixed points decimal are less precise than Floating ones, but much faster and requires less space (1 byte less). Also, their range is much limited. They're usually used on screen drawing when Floating point is too slow and decimal @@ -50,7 +50,8 @@ calculations are required. #### Float Floating point type is **identical** to the Sinclair BASIC one. It requires 5 bytes (1 byte for exponent, 4 bytes for mantissa). -Read the ZX Spectrum manual or [here](http://www.worldofspectrum.org/ZXBasicManual/zxmanchap24.html). +Read the [Chapter 24 of the ZX Spectrum manual](http://www.worldofspectrum.org/ZXBasicManual/zxmanchap24.html) +for further information. >To store the number in the computer, we use five bytes, as follows: > @@ -75,7 +76,7 @@ At this moment, ZX BASIC is not an OOP Vars are _scalar_ variables. Scalar variables are those which store a single value. Almost all variables are scalars: -``` +```basic REM A simple scalar variable DIM a = 3 ``` @@ -85,7 +86,7 @@ DIM a = 3 Unlike scalars, array variables can hold more than a single value at once. You access a single value within the array container using an integer _index_: -``` +```basic REM An array variable DIM a(1 TO 10) AS UBYTE LET a(3) = 5: REM pick a(3) cell and store the number 5 in it @@ -97,7 +98,7 @@ Unlike the above, [labels](labels.md) are not variables. They refer to memory positions. Line numbers are also treated as labels and they are completely optional: -``` +```basic 10 REM here '10' is a Label 5 REM here '5' is another label, so the number order does not matter REM Line numbers are optional. So this line is ok either. From edf4d74f6cb04b08300da74187023e70bb95bb09 Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 01:21:33 +0200 Subject: [PATCH 3/7] docs: udpate index.md page Fix table of contents by changing the headers of every section. --- docs/index.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index e26e2f867..314799f36 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,5 @@ -# General +## General + * [About](about.md)
About Boriel BASIC SDK @@ -14,18 +15,17 @@ * [Command line options](zxb.md#Command_Line_Options)
Command line options table for the compiler (zxb) -# Download - +## Download Get the latest version of Boriel BASIC from the [archive](archive.md). -# Released programs +## Released programs * [Released programs](released_programs.md)
A list of third-party released programs (mostly games) for the ZX-Spectrum developed with Boriel BASIC. -# Learning Boriel BASIC +## Learning Boriel BASIC -## Language Reference +### Language Reference * [Language syntax](syntax.md)
Language Syntax is very close to the original Sinclair BASIC, but it's expanded and enhanced. @@ -38,7 +38,7 @@ Get the latest version of Boriel BASIC from the [archive](archive.md). * [Standard libraries](library/stdlib.md)
Standard libraries that comes bundled with Boriel BASIC compiler. -## Tutorials +### Tutorials * [Programming tutorials](tutorials.md)
A collection of third-party tutorials about development with Boriel BASIC. @@ -48,31 +48,32 @@ Get the latest version of Boriel BASIC from the [archive](archive.md). * [Sample Games](sample_programs.md#Game Examples)
Some little games examples. -# Help and Support +## Help and Support * [Community Forum](http://www.boriel.com/forum)
Have a question? Need help or comment a report a bug? Go to the [Boriel BASIC forum](http://www.boriel.com/forum) -# External resources +## External resources * Here you are [external resources](external_resources.md): other tools, IDEs, graphic designers and projects related to Boriel BASIC. Have a look! -# External libraries +### External libraries * [Library](library.md)
Library of functions and subroutines you can use in your programs. You might find them really useful. -# Inline assembler +## Inline assembler Embedding inline assembler in your code is pretty easy. There's a [tutorial](tutorials.md) on it. -# Compiler internals +## Compiler internals Only for true hackers: This explains how the compiler does its job, how to expand it, etc. +This is `work in progress`. -# Other Architectures +## Other Architectures Boriel BASIC was designed from the base as a Retargeable Compiler, so it should be not hard to extend it to other architectures. This is `work in progress`. See [other architectures](other_architectures.md) for more info. -# Contributing +## Contributing You can issue a Pull Request to the [GitHub repository](https://github.com/boriel/zxbasic), report bugs in the forum when using the compiler, suggest new features... From 8fde526afd0cc5eb1db873a1917c4edb676f376e Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 17:26:38 +0200 Subject: [PATCH 4/7] docs: add admonitions feature --- docs/overrides/stylesheets/extra.css | 5 +++++ mkdocs.yml | 3 ++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/overrides/stylesheets/extra.css b/docs/overrides/stylesheets/extra.css index 653053b47..2bd239c4c 100644 --- a/docs/overrides/stylesheets/extra.css +++ b/docs/overrides/stylesheets/extra.css @@ -72,3 +72,8 @@ h1, h2, h3, h4, h5, h6 { .md-typeset h6 { font-weight: 600; /* Bold */ } + +.md-typeset .admonition, +.md-typeset details { + font-size: 16px +} diff --git a/mkdocs.yml b/mkdocs.yml index ab4738ee4..2a0a00895 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,7 +9,7 @@ nav: theme: name: material - #logo: img/zxbasic_logo.png + favicon: img/zxbasic_logo.png palette: # Palette toggle for light mode - media: "(prefers-color-scheme: light)" @@ -31,6 +31,7 @@ theme: docs_dir: docs markdown_extensions: + - admonition - pymdownx.highlight: linenums: true anchor_linenums: true From adb54ae1b2975ce09e28fba67937ba87aab42f29 Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 17:26:58 +0200 Subject: [PATCH 5/7] docs: fix fsin.bas.md page --- docs/library/fsin.bas.md | 117 +++++++++++++++++++++------------------ 1 file changed, 62 insertions(+), 55 deletions(-) diff --git a/docs/library/fsin.bas.md b/docs/library/fsin.bas.md index c5bf182a3..aa6c3d27c 100644 --- a/docs/library/fsin.bas.md +++ b/docs/library/fsin.bas.md @@ -2,84 +2,91 @@ ## Introduction +This function implements fast `Fixed` point `sin`, `cos` and `tan` functions. +The ones that uses `Float` type (calling the Sinclair ROM) are much slower as FP Calculations +are expensive. This variant is less precise but more suitable for games, for example. + `fSin` is the basis for the alternatives, since `COS(x)` can be calculated -from `SIN(x)` and `TAN(x)` from `COS(x)` and `SIN(x)`. +from `SIN(x)` and `TAN(x)` as `SIN(x)` / `COS(x)`. + +!!! info "Note" + This library is already bundled with Boriel BASIC.
+ To use it just add `#include ` + at the beginning of your program. The functions should be accurate to about 0.25%, and significantly faster. If you need a lot of trig in your code, and it doesn't need to be pinpoint accuracy, these are good alternatives. -Note that they more or less acknowledge they are less accurate by returning values of type `Fixed` instead of type `Float`. -I did this because it should be fine for the actual accuracy returned, +Note that they more or less acknowledge they are less accurate by returning values of type `Fixed` instead +of type `Float`. +It should be fine for the actual accuracy returned, and `Fixed` numbers process faster and smaller than `Float` ones. -* Note that you need only include `fSin` if you only want Sines, but you need fSin to use `fCos` or `fTan`. +* Note that you need only include `fSin` if you only want Sines, but you need `fSin` to use `fCos` or `fTan`. * Note that these functions use degrees, not radians. ## SINE Function -``` +```vbnet FUNCTION fSin(num as FIXED) as FIXED -DIM quad as byte -DIM est1,dif as uByte - -'This change made now that MOD works with FIXED types. -'This is much faster than the repeated subtraction method for large angles (much > 360) -'while having some tiny rounding errors that should not significantly affect our results. -'Note that the result may be positive or negative still, and for SIN(360) might come out -'fractionally above 360 (which would cause issued) so the below code still is required. - -IF num >= 360 THEN - num = num MOD 360 -ELSEIF num < 0 THEN - num = 360 - ABS(num) MOD 360 -END IF - -IF num>180 then - quad=-1 - num=num-180 -ELSE - quad=1 -END IF - -IF num>90 then num=180-num - -num=num/2 -dif=num : rem Cast to byte loses decimal -num=num-dif : rem so this is just the decimal bit - - -est1=PEEK (@sinetable+dif) -dif=PEEK (@sinetable+dif+1)-est1 : REM this is just the difference to the next up number. - -num=est1+(num*dif): REM base +interpolate to the next value. - -return (num/255)*quad - - -sinetable: -asm -DEFB 000,009,018,027,035,044,053,062 -DEFB 070,079,087,096,104,112,120,127 -DEFB 135,143,150,157,164,171,177,183 -DEFB 190,195,201,206,211,216,221,225 -DEFB 229,233,236,240,243,245,247,249 -DEFB 251,253,254,254,255,255 -end asm + DIM quad as byte + DIM est1,dif as uByte + + 'This change made now that MOD works with FIXED types. + 'This is much faster than the repeated subtraction method for large angles (much > 360) + 'while having some tiny rounding errors that should not significantly affect our results. + 'Note that the result may be positive or negative still, and for SIN(360) might come out + 'fractionally above 360 (which would cause issued) so the below code still is required. + + IF num >= 360 THEN + num = num MOD 360 + ELSEIF num < 0 THEN + num = 360 - ABS(num) MOD 360 + END IF + + IF num > 180 then + quad = -1 + num = num - 180 + ELSE + quad = 1 + END IF + + IF num > 90 THEN num = 180 - num + + num = num / 2 + dif = num : REM Cast to byte loses decimal + num = num - dif : REM so this is just the decimal bit + + est1 = PEEK(@sinetable + dif) + dif = PEEK(@sinetable + dif + 1) - est1 : REM this is just the difference to the next up number. + num = est1 + (num * dif) : REM base + interpolate to the next value. + + Return (num / 255) * quad + + sinetable: + Asm + DEFB 000,009,018,027,035,044,053,062 + DEFB 070,079,087,096,104,112,120,127 + DEFB 135,143,150,157,164,171,177,183 + DEFB 190,195,201,206,211,216,221,225 + DEFB 229,233,236,240,243,245,247,249 + DEFB 251,253,254,254,255,255 + End Asm END FUNCTION ``` ## COSINE Function -``` +```vbnet FUNCTION fCos(num as FIXED) as FIXED - return fSin(90-num) + Return fSin(90 - num) END FUNCTION ``` ## TANGENT Function -``` +```vbnet FUNCTION fTan(num as FIXED) as FIXED - return fSin(num)/fSin(90-num) + Return fSin(num) / fSin(90 - num) END FUNCTION ``` From a4d9345fd7ebb13fcb6309ec66065686bf75ae3a Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 17:40:37 +0200 Subject: [PATCH 6/7] docs: fixes #873 --- docs/cos.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cos.md b/docs/cos.md index f2c2631b4..7a2c34e81 100644 --- a/docs/cos.md +++ b/docs/cos.md @@ -14,7 +14,7 @@ Argument must be a numeric expression in radians units. Returned value type is [ ## Examples -``` +```basic REM Cosine value PRINT "Cosine value of a is "; COS(a) ``` @@ -30,4 +30,4 @@ PRINT "Cosine value of a is "; COS(a) * [SIN](sin.md) and [ASN](asn.md) * [TAN](tan.md) and [ATN](atn.md) * [ACS](acs.md) -* Faster library option for lower accuracy trigonometry for games: [FCOS](fsin.bas.md) +* Faster library option for lower accuracy trigonometry for games: [FCOS](library/fsin.bas.md) From 9e3a422c48736902d82db37ab1fb7cc2f59d1a60 Mon Sep 17 00:00:00 2001 From: Jose Rodriguez Date: Tue, 24 Jun 2025 17:45:47 +0200 Subject: [PATCH 7/7] docs: use rem font size units --- docs/overrides/stylesheets/extra.css | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/overrides/stylesheets/extra.css b/docs/overrides/stylesheets/extra.css index 2bd239c4c..dccafe9bb 100644 --- a/docs/overrides/stylesheets/extra.css +++ b/docs/overrides/stylesheets/extra.css @@ -10,13 +10,13 @@ /* Light mode - very light yellow header */ [data-md-color-scheme="default"] .md-header { background-color: #d0d6da; /* Very light yellow background color */ - height: 8em; + height: 4rem; } [data-md-color-scheme="default"] .md-header__title { color: #23231c; - padding-left: 2em; + padding-left: 2rem; } /* Dark mode - dark gray header */ @@ -26,12 +26,12 @@ /*background-repeat: no-repeat;*/ /*background-position: center center;*/ /*background-size: auto 90%;*/ - height: 8em; + height: 4rem; } [data-md-color-scheme="slate"] .md-header__title { color: #af0d0d; - padding-left: 2em; + padding-left: 2rem; } .md-header__title { @@ -75,5 +75,5 @@ h1, h2, h3, h4, h5, h6 { .md-typeset .admonition, .md-typeset details { - font-size: 16px + font-size: 0.75rem }