add graphprint scaling, flipping

Author: braindigitalis

docpages/basic-language-reference/keywords/GRAPHPRINT.md

@@ -1,66 +1,44 @@
 \page GRAPHPRINT GRAPHPRINT Keyword
 
 ```basic
-GRAPHPRINT x, y, printable
+GRAPHPRINT x, y, scale_x, scale_y, printable
 ```
 
 Draws text directly onto the graphics framebuffer at **pixel coordinates**.
 Unlike `PRINT`, `GRAPHPRINT` does not use or update the text cursor. Each call is independent.
 
----
+`x` and `y` are integer **pixel coordinates** measured from the top-left corner of the screen. scale_x and scale_y can be an integer or a real number. If you specify 0 for either dimension, the default scale of 1 will be used.
+`printable` is the same syntax accepted by \ref PRINT "PRINT", a list of values separated by commas or semicolons. * Text is rendered using the current **graphics colour** (`GCOL`) for the foreground.
+The background is always **transparent**, existing pixels are left unchanged. Each call draws at the specified location only, there is no graphics cursor or scrolling.
 
-### Notes
-
-* `(x, y)` are **pixel coordinates** measured from the top-left corner of the screen.
-* `printable` is the same syntax accepted by `PRINT`: a list of values separated by commas or semicolons.
-
-  * **Strings** are rendered literally.
-  * **Numeric values** are converted to their string form.
-  * `;` continues text without spacing.
-  * `,` advances to the next tab stop (multiple of text column width).
-* Text is rendered using the current **graphics colour** (`GCOL`) for the foreground.
-* The background is always **transparent**; existing pixels are left unchanged.
-* The function clips safely against screen edges; partially visible text is drawn correctly.
-* All 8-bit codes `0x00–0xFF` map directly to glyphs, including those redefined with `VDU 23`. No UTF-8 decoding is applied.
-* Each call draws at the specified location only. There is no graphics cursor or scrolling.
-
----
-
-### Errors
-
-* An error occurs if `x` or `y` are not numeric.
-* An error occurs if `printable` is omitted.
-
----
+You can use negative scale values to flip the text. Note that if you flip the scale values, it will render right to left or bottom to top accordingly.
 
 ### Examples
 
-**Draw a label in magenta**
+**Draw a label upside down in magenta**
 
 ```basic
 GCOL &FF00FF
-GRAPHPRINT 100, 40, "SCORE:", SCORE
+GRAPHPRINT 100, 40, 1, -1, "SCORE:", SCORE
 ```
 
-**Overlay transparent HUD text**
+**Overlay transparent HUD text at 5x scale**
 
 ```basic
 GCOL &FFFFFF
-GRAPHPRINT 8, 8, "READY!";
+GRAPHPRINT 8, 8, 5, 5, "READY!";
 ```
 
 **Use a redefined glyph**
 
 ```basic
 VDU 23,65,&3C,&7E,&FF,&E7,&FF,&66,&66,&00
-GRAPHPRINT 120, 100, "AAAAAAAAAAA"
+GRAPHPRINT 120, 100, 10, 10, "AAA"
 ```
 
----
-
 ### See also
 
-* \ref PRINT "PRINT" - text output in the scrolling text grid.
-* \ref GCOL "GCOL" - set graphics colour (0xRetro RocketGGBB).
-* \ref LINE "LINE" - draw lines (used by `VDU 25` in Retro Rocket).
-* \ref VDU "VDU" 23 - redefine character bitmaps used by both `PRINT` and `GRAPHPRINT`.
+* \ref PRINT "PRINT" ·
+* \ref GCOL "GCOL" ·
+* \ref LINE "LINE" ·
+* \ref VDU "VDU 23"

docs/GRAPHPRINT.html

@@ -123,53 +123,28 @@
   <div class="headertitle"><div class="title">GRAPHPRINT Keyword </div></div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><div class="fragment"><div class="line">GRAPHPRINT x, y, printable</div>
+<div class="textblock"><div class="fragment"><div class="line">GRAPHPRINT x, y, scale_x, scale_y, printable</div>
 </div><!-- fragment --><p>Draws text directly onto the graphics framebuffer at <b>pixel coordinates</b>. Unlike <span class="tt">PRINT</span>, <span class="tt">GRAPHPRINT</span> does not use or update the text cursor. Each call is independent.</p>
-<hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-181"></a>
-Notes</h3>
-<ul>
-<li><span class="tt">(x, y)</span> are <b>pixel coordinates</b> measured from the top-left corner of the screen.</li>
-<li><span class="tt">printable</span> is the same syntax accepted by <span class="tt">PRINT</span>: a list of values separated by commas or semicolons.<ul>
-<li><b>Strings</b> are rendered literally.</li>
-<li><b>Numeric values</b> are converted to their string form.</li>
-<li><span class="tt">;</span> continues text without spacing.</li>
-<li><span class="tt">,</span> advances to the next tab stop (multiple of text column width).</li>
-</ul>
-</li>
-<li>Text is rendered using the current <b>graphics colour</b> (<span class="tt">GCOL</span>) for the foreground.</li>
-<li>The background is always <b>transparent</b>; existing pixels are left unchanged.</li>
-<li>The function clips safely against screen edges; partially visible text is drawn correctly.</li>
-<li>All 8-bit codes <span class="tt">0x00–0xFF</span> map directly to glyphs, including those redefined with <span class="tt">VDU 23</span>. No UTF-8 decoding is applied.</li>
-<li>Each call draws at the specified location only. There is no graphics cursor or scrolling.</li>
-</ul>
-<hr  />
-<h3 class="doxsection"><a class="anchor" id="errors-9"></a>
-Errors</h3>
-<ul>
-<li>An error occurs if <span class="tt">x</span> or <span class="tt">y</span> are not numeric.</li>
-<li>An error occurs if <span class="tt">printable</span> is omitted.</li>
-</ul>
-<hr  />
+<p><span class="tt">x</span> and <span class="tt">y</span> are integer <b>pixel coordinates</b> measured from the top-left corner of the screen. scale_x and scale_y can be an integer or a real number. If you specify 0 for either dimension, the default scale of 1 will be used. <span class="tt">printable</span> is the same syntax accepted by <a class="el" href="PRINT.html">PRINT</a>, a list of values separated by commas or semicolons. * Text is rendered using the current <b>graphics colour</b> (<span class="tt">GCOL</span>) for the foreground. The background is always <b>transparent</b>, existing pixels are left unchanged. Each call draws at the specified location only, there is no graphics cursor or scrolling.</p>
+<p>You can use negative scale values to flip the text. Note that if you flip the scale values, it will render right to left or bottom to top accordingly.</p>
 <h3 class="doxsection"><a class="anchor" id="examples-174"></a>
 Examples</h3>
-<p><b>Draw a label in magenta</b></p>
+<p><b>Draw a label upside down in magenta</b></p>
 <div class="fragment"><div class="line">GCOL &amp;FF00FF</div>
-<div class="line">GRAPHPRINT 100, 40, &quot;SCORE:&quot;, SCORE</div>
-</div><!-- fragment --><p><b>Overlay transparent HUD text</b></p>
+<div class="line">GRAPHPRINT 100, 40, 1, -1, &quot;SCORE:&quot;, SCORE</div>
+</div><!-- fragment --><p><b>Overlay transparent HUD text at 5x scale</b></p>
 <div class="fragment"><div class="line">GCOL &amp;FFFFFF</div>
-<div class="line">GRAPHPRINT 8, 8, &quot;READY!&quot;;</div>
+<div class="line">GRAPHPRINT 8, 8, 5, 5, &quot;READY!&quot;;</div>
 </div><!-- fragment --><p><b>Use a redefined glyph</b></p>
 <div class="fragment"><div class="line">VDU 23,65,&amp;3C,&amp;7E,&amp;FF,&amp;E7,&amp;FF,&amp;66,&amp;66,&amp;00</div>
-<div class="line">GRAPHPRINT 120, 100, &quot;AAAAAAAAAAA&quot;</div>
-</div><!-- fragment --><hr  />
-<h3 class="doxsection"><a class="anchor" id="see-also-7"></a>
+<div class="line">GRAPHPRINT 120, 100, 10, 10, &quot;AAA&quot;</div>
+</div><!-- fragment --><h3 class="doxsection"><a class="anchor" id="see-also-7"></a>
 See also</h3>
 <ul>
-<li><a class="el" href="PRINT.html">PRINT</a> - text output in the scrolling text grid.</li>
-<li><a class="el" href="GCOL.html">GCOL</a> - set graphics colour (0xRetro RocketGGBB).</li>
-<li><a class="el" href="LINE.html">LINE</a> - draw lines (used by <span class="tt">VDU 25</span> in Retro Rocket).</li>
-<li><a class="el" href="VDU.html">VDU</a> 23 - redefine character bitmaps used by both <span class="tt">PRINT</span> and <span class="tt">GRAPHPRINT</span>. </li>
+<li><a class="el" href="PRINT.html">PRINT</a> ·</li>
+<li><a class="el" href="GCOL.html">GCOL</a> ·</li>
+<li><a class="el" href="LINE.html">LINE</a> ·</li>
+<li><a class="el" href="VDU.html">VDU 23</a> </li>
 </ul>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->

docs/IF.html

@@ -181,7 +181,7 @@ <h3 class="doxsection"><a class="anchor" id="forms-and-examples"></a>
 <div class="line">    PRINT &quot;A NOT POSITIVE&quot;</div>
 <div class="line">ENDIF</div>
 </div><!-- fragment --><hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-182"></a>
+<h3 class="doxsection"><a class="anchor" id="notes-181"></a>
 Notes</h3>
 <ul>
 <li>In the <b>single-line</b> form, the <span class="tt">THEN</span> and optional <span class="tt">ELSE</span> parts each allow <b>one statement</b>. Use the multi-line form for multiple statements.</li>

docs/INPUT.html

@@ -158,7 +158,7 @@ <h3 class="doxsection"><a class="anchor" id="examples-175"></a>
 <div class="line">UNTIL X &lt;&gt; 0</div>
 <div class="line">PRINT &quot;Thanks: &quot;; X</div>
 </div><!-- fragment --><hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-183"></a>
+<h3 class="doxsection"><a class="anchor" id="notes-182"></a>
 Notes</h3>
 <ul>
 <li>The entered line is stored <b>as-is</b> for string variables (without the trailing newline).</li>

docs/KEYMAP.html

@@ -147,7 +147,7 @@ <h5 class="doxsection"><a class="anchor" id="example-17"></a>
 <div class="fragment"><div class="line">REM Load British English keyboard layout (if installed)</div>
 <div class="line">KEYMAP &quot;en-GB&quot;</div>
 </div><!-- fragment --><hr  />
-<h5 class="doxsection"><a class="anchor" id="notes-184"></a>
+<h5 class="doxsection"><a class="anchor" id="notes-183"></a>
 Notes</h5>
 <ul>
 <li>The setting affects how keyboard input is interpreted by the system. <br  />

docs/LET.html

@@ -146,7 +146,7 @@ <h3 class="doxsection"><a class="anchor" id="examples-176"></a>
 <div class="line">PRINT A(1)</div>
 </div><!-- fragment --><p>Using an expression on the right-hand side </p><div class="fragment"><div class="line">TOTAL = PRICE * QUANTITY</div>
 </div><!-- fragment --><hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-185"></a>
+<h3 class="doxsection"><a class="anchor" id="notes-184"></a>
 Notes</h3>
 <ul>
 <li><span class="tt">LET</span> does not change scope. It is simply an optional keyword for assignment.</li>

docs/LINE.html

@@ -139,7 +139,7 @@ <h3 class="doxsection"><a class="anchor" id="examples-178"></a>
 </div><!-- fragment --><hr  />
 <dl class="section remark"><dt>Remarks</dt><dd>If <a class="el" href="AUTOFLIP.html">AUTOFLIP</a> is <span class="tt">FALSE</span>, draw your frame (including <span class="tt">LINE</span>) and then call <a class="el" href="FLIP.html">FLIP</a> to present it.</dd></dl>
 <hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-186"></a>
+<h3 class="doxsection"><a class="anchor" id="notes-185"></a>
 Notes</h3>
 <ul>
 <li>Coordinates are in <b>screen pixels</b>; <span class="tt">(0,0)</span> is the <b>top-left</b> of the display.</li>

docs/MAPFREE.html

@@ -141,7 +141,7 @@ <h5 class="doxsection"><a class="anchor" id="example-18"></a>
 <div class="fragment"><div class="line">123</div>
 <div class="line">Invalid MAP</div>
 </div><!-- fragment --><hr  />
-<h5 class="doxsection"><a class="anchor" id="notes-187"></a>
+<h5 class="doxsection"><a class="anchor" id="notes-186"></a>
 Notes</h5>
 <ul>
 <li>Frees all memory associated with the MAP:<ul>

docs/MAPSET.html

@@ -165,7 +165,7 @@ <h5 class="doxsection"><a class="anchor" id="examples-180"></a>
 <div class="line"> </div>
 <div class="line">PRINT MAPGETR(M, &quot;value&quot;)</div>
 </div><!-- fragment --><hr  />
-<h5 class="doxsection"><a class="anchor" id="notes-188"></a>
+<h5 class="doxsection"><a class="anchor" id="notes-187"></a>
 Notes</h5>
 <ul>
 <li>Keys are <b>case-sensitive</b></li>

docs/MATCH.html

@@ -216,7 +216,7 @@ <h3 class="doxsection"><a class="anchor" id="not-supported"></a>
 <li>Multiline mode (<span class="tt">^</span> and <span class="tt">$</span> match string boundaries only)</li>
 </ul>
 <hr  />
-<h3 class="doxsection"><a class="anchor" id="notes-189"></a>
+<h3 class="doxsection"><a class="anchor" id="notes-188"></a>
 Notes</h3>
 <ul>
 <li>Matching is <b>case-sensitive</b>. To simulate case-insensitive matching, normalise both strings or use explicit character classes.</li>