RPIX
                                     ====

                                  Read pixels

Two routines to read pixels off a screen or in a window. The colour
returned can be Native colour (RPIX%) or RGB 24 bit colour (RPIX24).

These functions are only compatible with the Graphic Device Interface
Version 2 (GD2) drivers in the three currently available modes: 16, 32,
and 33. Currently this also means they are only compatible with SMSQ/E
systems.


Usage:
------

        natcol% = RPIX%([#ch; ] xpos%, ypos%)

        Returns the native colour of pixel at xpos%, ypos% relative to
        channel #ch (defaults to #1)


        natcol% = RPIX%([#ch; ] xpos%! ypos%)

        Returns the native colour of pixel at xpos%, ypos% in screen
        coordinates. An optional channel is still required and defaults
        to #1.



        rgbcol = RPIX24([#ch; ] xpos%, ypos%)

        Returns the RGB colour code of pixel at xpos%, ypos% relative to
        channel #ch (defaults to #1)


        rgbcol = RPIX24([#ch; ] xpos%! ypos%)

        Returns the RGB colour code of pixel at xpos%, ypos% in screen
        coordinates. An optional channel is still required and defaults
        to #1.


Examples:
---------

The following code is a simple demonstration. A block is drawn on the
right side of the window with an alternating dot pattern of another
colour. Two sample dots are read and an identical block is drawn on the
left. EXecute the code as an SBASIC job. Mode 16, 32, and 33 only!


100 LRESPR'win4_scr_rpx_RPIX24_BIN'
110 ch = FOPEN("con_216x108a10x20")
120 PAPER#ch; 7: INK#ch; 0: BORDER#ch; 4, 2: CLS#ch
130 :
140 COLOUR_NATIVE
150 RANDOMISE DATE
160 :
170 IF DISP_TYPE = 16 THEN
180  max% = 255: min% = 0
190 ELSE
200  max% = 32767: min% = -32767
210 END IF
220 :
230 FOR i = 0 TO 10
240  nat1% = RND(min% TO max%)
250  nat2% = RND(min% TO max%)
260  BLOCK#ch; 100, 100, 100, 0, nat1%, nat2%, 0
270  Wait 10
280  res1% = RPIX%(#ch; 100, 0)
290  res2% = RPIX%(#ch; 101, 0)
300  BLOCK#ch; 100, 100, 0, 0, res1%, res2%, 0
310  Wait 20
320 END FOR i
330 BEEP 999, 1: Wait 100: QUIT
340 :
350 DEFine PROCedure Wait(t): IF CODE(INKEY$(#ch; t)) = 27: QUIT
360 :


Mag_bas
-------

Mag_bas is a slightly more elabourate program to magnify a portion of the
screen. EXecute it as an SBASIC program. Move the window sprite to a
suitable location and HIT the mouse button to magnify the area. To move the
display window, find a suitable location and DO the mouse button. Press
ESC to quit.

It's included with the toolkit, but you can preview it here

NB! Requires EasyPtr's ptrmen_cde or, with modification, Qptr.


Programming notes:
------------------

RPIX% and RPIX24 share some common code, but can easily be separated. If
all you need is RPIX% then run your Make or linker with RPIX_link. If all
you want is RPIX24, there is not much to be gained by removing RPIX%, so I
leave it to you to sort out.

The bulk of the nat to RGB conversion code is due to the 8 bit, mode 16,
conversion table. I found the tabular conversion necessary, as I was not
satisfied with a purely calculated conversion. Perhaps someone else can to
better?

The code base is designed to run on all GD2 platforms. If you know that a
program in which you intend to use RPIX24 will never run under mode 16, you
could remove the bits pertaining to that mode.

If mode 16 is important and you prefer speed over bulk, you could
reassemble the program with the nat16to64 conversion code (as opposed to
the nat16to64n used here). nat16to64 uses a 3x3 byte conversion table and
takes up all of 768 bytes, but uses fewer instructions to do the job, while
nat16to64n uses a 3x3 nybble conversion table, which takes up half the
space, but is marginally slower. No changes to the code is required: Just
use one or the other file in the link file.


Software status:
----------------

The nat32to64 and nat33to64 conversion routines were packaged by me and are
V0.01, ©W Lenerz, 2004.

The remainder is:

V0.01, pjw, November 13th 2018
V0.02, pjw, June 10th 2019, corrected and packaged.

Conditions of use and disclaimer as per Knoware.no