WPIX
                                      ====

Write or set a pixel at given screen coordinate to a given colour in a window.


Limitations:
------------

GD2 only! At present this means SMSQ/E in modes 16..33.

This version of WPIX doesnt respond to OVER or ALPHA_BLEND! It is also
limited to Native Mode.

When all is said and done, BLOCK/WM_BLOCK are so versatile and efficient
that there really is no need for a separate WPIX command. (See the Demo!)
It is included here anyway for completeness' sake to compliment RPIX.


Usage:
------
        WPIX[#ch,] x%, y%, colour%

where
        #ch is an optional channel number (#1 is default)
        x% / y% are the pixel coordinates within the window channel, and
        colour is the colour code in the native mode

Note: The coordinates given MUST fall within the window's borders or an
Out of Range error will be thrown. Ie the top left pixel is

                                 0, 0

while the bottom rightmost pixel is

window_x_size - border_width * 4 - 1, window_y_size - border_width * 2 - 1


Note: If background refresh is switched on (PE_BGON) and the window is
(partially) burried, the pixel is written into the buffer instead and will
be revealed once the window is uncovered again.

If background refresh is switched off (PE_BGOFF) and the window is
buried, program flow will be suspended until the window is uncovered. This
is normal behaviour (in the unlikely event you didnt know..)


Example:
--------

100 LRESPR 'win4_scr_wpx_WPIX_BIN'
110 ch = FOPEN("con")
120 wx% = 200: REMark X must be even or bad things will happen..
130 wy% = 101: REMark Y can be odd
140 bd% = 1:   REMark Border width
150 WINDOW#ch; wx% + bd% * 4, wy% + bd% * 2, 20, 20
160 BORDER#ch; bd%, 4
170 CLS#ch
180 :
190 FOR x% = 0 TO wx% - 1
200  wpix#ch; x%, 10, -1
210 END FOR x%
220 :
230 FOR y% = 0 TO wy% - 1
240  wpix#ch; 10, y%, -1
250 END FOR y%
260 :
270 PAUSE#ch
280 QUIT


Demo:
-----

Ive included a small test program, wpx_tstpixXX_bas to demonstrate WPIX
in use. It is a programmer's program! No refinements here. Two files
represent the same program: One is for modes 32 and 33, the other is for
mode 16.

Load it into a text editor and alter the parameters to suit your setup:
In particular, youll need to supply a suitable PIC file in the same mode
as your display. The PIC must easily fit within your screen, and for your
sanity's sake, choose a small one if youre running this on a slow platform!
Adjust any paths refered to in the program to suit your setup.

Note: A number of toolkit keywords are used. Either download these,
provide your own, or use SBASIC equivalents.

Save and the EXecute the program.

You can easily alter the program to do the same for (uncompressed)
sprites.

REMark/un-REMark lines to test with BLOCK or WPIX.

Note: In mode 32 (QPC2 & SMSQmulator), the PIC byte order is switched
relative to the display colour code, so you need to alter the byte order,
ie PEEK_W colour, switch byte order, BLOCK 1, 1, x%, y%, c%. I dont know
why things were done this way..


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

V0.02, pjw, 2019 Oct 18

Conditions of use and disclaimer as per Knoware.no