>
> I am working on updating the ap_doc.do file with AsciiPixel image
> encoding documentation, but it is a bit involved and is taking some time to
> update.
>
Hey Ken, I know you're in the middle of updating the documentation, but I
figured I might as well share the minor changes I made to ap_doc.do. Mainly
I corrected the instructions for the Tandy 200, but I also fixed the mouse
cursor ascii art, and added a section on how to detect if AsciiPixels is
available.
Here's the patch:
--- ap_doc.txt~ 2023-02-13 21:14:40.395371132 -0800+++
ap_doc.txt 2023-02-13 22:22:58.771620379 -0800@@ -5,8 +5,8 @@
/_/ \_\___/\___|_|_||_| |_/_/\_\___|_|___/
- Version 1.0- Copyright 2015, Ken Pettit+
Version 1.0.1+ Copyright 2023, Ken Pettit
All rights reserved.
@@ -19,7 +19,7 @@
The library is distributed as a standard .CO file that can be loaded
to the portable and installed using the LOADM BASIC instruction. Once
installed, the library is accessed by making CALL instructions to
the-base entry address (value depends on M100/T102 vs T200), passing
in +base entry address (value is the same on M100/T102 and T200),
passing in
arguments in the A and HL registers to indicate the desired action.
Services currently provided by AP include:@@ -44,12 +44,21 @@
2. Enter basic and execute the "CLEAR" command to move HIMEM so
there is room to load ASCPIX:
- - Model 100/102: clear 256,58000- - Model 200:
clear 256,58000+ clear 256,58000
3. Still from BASIC, load the CO:
- loadm "ASCPIX"+ - Model 100/102: loadm
"ASCPIX"+ - Model 200: loadm
"ASCPX2"++++DETECTING+=========+ To detect if ASCPIX has been
loaded, use this code:++ A=58000+ IF PEEK(A)=195 AND
PEEK(A)=46 THEN AP=1 ELSE AP=0
CALLING@@ -106,8 +115,8 @@
|\ |\ |\
| \ | \ | \- | \ |. \
|_.'- |__/ \\ \\+ |/^`
|_.' | \+ \\ \\ |__/
Cursor 0 Cursor 1 Cursor 2
Or, see the attached file.
—b9
_ _ _ ____ _ _
/ \ ___ ___(_|_)| _ \(_)_ _____| |___
/ _ \ / __|/ __| | || |_) | \ \/ / _ \ / __|
/ ___ \\__ \ (__| | || __/| |> < __/ \__ \
/_/ \_\___/\___|_|_||_| |_/_/\_\___|_|___/
Version 1.0.1
Copyright 2023, Ken Pettit
All rights reserved.
AsciiPixels (AP) is a graphics library for the TRS-80 Model 100/102
and T200 portable computers. It is a machine language library written in
8085 assmebly for speed. The graphics routines directly access the LCD
driver controller(s) instead of performing ROM accesses for added
performance improvements.
The library is distributed as a standard .CO file that can be loaded
to the portable and installed using the LOADM BASIC instruction. Once
installed, the library is accessed by making CALL instructions to the
base entry address (value is the same on M100/T102 and T200), passing in
arguments in the A and HL registers to indicate the desired action.
Services currently provided by AP include:
- Drawing graphics resources saved as ASCII strings (A$, B$, etc.)
- Drawing graphics from a FILE in the M100/102 catalog (the entire
file will be drawn)
- Drawing named resources stored in a FILE containing multiple
resources
- Drawing and managing a "cursor/pointer" with automatic background
saving and restoring, cursor masking, etc.
Additionally, a BASIC program is provied for converting .DO files
containing the source for one or more icons drawn with '*' and ' '
characters into ASCII strings to be passed to AP.
INSTALLING
==========
1. Copy the ASCPIX.CO file to the portable
2. Enter basic and execute the "CLEAR" command to move HIMEM so
there is room to load ASCPIX:
clear 256,58000
3. Still from BASIC, load the CO:
- Model 100/102: loadm "ASCPIX"
- Model 200: loadm "ASCPX2"
DETECTING
=========
To detect if ASCPIX has been loaded, use this code:
A=58000
IF PEEK(A)=195 AND PEEK(A)=46 THEN AP=1 ELSE AP=0
CALLING
=======
Just in case a new version of AsciiPixels needs to change the base
entry location, programs should assign a variable, perhaps A, equal
to the entry location where all calls will be made. This will also
reduce the amount of typing and code size:
10 A=58000
or
10 DEFINT A
20 A=58000-65536
After defining the call address in a variable, all calls will be
made by calling that base address with the first parameter (A) of the
call indicating the requested operation and the second parameter (HL)
indicating the operation parameter. The operations can either be
loaded into variables for ease in remembering them, or simply entered
as numeric values in the CALL instruction.
CALL A,8,0 : REM Operation 8 initializes the cursor. Parameter
0 indicates the cursor style (0,1,2).
CALL A,2,VARPTR(R$) : REM Draw graphic whose ASCII text is in R$
NOTE: All X,Y coordinates are zero-based.
OPERATIONS
==========
Init Cursor
-----------
OP: CALL A, 8, cursor_number
This function initializes the standard cursor. Initialization
consistst of marking the cursor as "not visible" and setting the
style of cursor to be drawn.
Since the cursor routines save data in the unused LCD controller
RAM, This routine should be called when the BASIC program starts
prior to any other cursor operations. Failure to call this routine
can cause old data saved in the LCD RAM from a previous BASIC RUN
to be improperly drawn if that LCD RAM data indicates the cursor
was currently on-screen (i.e. it will try to "restore" the data
that was under the cursor during the previous BASIC run).
There are three standard cursors included in the ASCPIX file
that can be selected as "cursor_number":
|\ |\ |\
| \ | \ | \
|/^` |_.' | \
\\ \\ |__/
Cursor 0 Cursor 1 Cursor 2
Turn Cursor On
--------------
OP: CALL A, 6, Y*256 + X
This function turns on the selected standard cursor a the
X,Y LCD pixel coordinate specified. As indicated, the Y coordinate
is passed in the upper byte of HL with the X coordinate in the
lower byte. This function marks the cursor as "shown".
Before drawing the cursor, the function will copy the current
LCD screen contents "under" the cursor to the unused LCD controller
RAM area so that it can be restored later when turning the cursor
off. Then it will draw the cursor at the specified location. If
the X,Y coordinates provided cause the pointer to be partialy off
the LCD (to the right or bottom), this will be handled properly.
If this function is called and the cursor is already being
displayed on the LCD, then the cursor to first be removed from the
display by restoring the previous LCD contents from unused LCD
controller RAM area (that was previously saved prior to drawing
the cursor).
Turn Cursor Off
---------------
OP: CALL A, 7
This function hides the selected standard cursor by restoring
the LCD contents from the spare LCD controller RAM area that was
previously saved prior to drawing the cursor. It also marks the
cursor as "hidden".
Set Render X,Y Location
-----------------------
OP: CALL A, 1, Y*256 + X
OP: CALL A, Y+128, X
This function set the X,Y location where the subsequent image
render operation will be performed. As indicated, there are two
calling conventions for passing the X and Y coordinates. The first
invocation was written first when developing the AP library routines,
and the second was added as a performance improvement to avoid
needing a multiply to specify the Y coordinate of every graphic
drawn.
If the X,Y coordinate is selected such that the size of the
subsequent image drawing does not fit on the LCD (i.e. overflows
the right or bottom), then the image will simply be cropped.
Render from string
------------------
OP: CALL A, 2, VALPTR(S$)
This function performs decoding and rendering of the image
whose ASCII source data is stored in the string S$. This is used
when AsciiPixel data is stored directly within the BASIC program
as either DATA statement or through direct variable assignment:
10 CALL A,Y+128,X
15 ...
20 S$="AP3)++'1>:B1#"
30 CALL A,2,VARPTR(S$)
Render from file
----------------
OP: CALL A, 3, VALPTR(S$)
This function performs decoding and rendering of the image
whose ASCII source data is stored in the FILE whose name is
stored in the string S$. The entire contents of the FILE will
be rendered.
10 CALL A,Y+128,X
15 ...
20 S$="IMAGE1.DO"
30 CALL A,3,VARPTR(S$)
Render from resource
--------------------
OP: CALL A, 4, VALPTR(S$)
This function performs decoding and rendering of an image
whose ASCII source data is stored in a resource file. The name
of the resource stored in the string S$, and the filename of
the resource file is specified via the CALL A,5,VARPTR(FN$) OP.
The file must exist in the Model 100/102/200 catalog as a standard
.DO file. The format of resources within the file are:
"Chek" AP3++xX
"Ball" AP300w1*Cb#Z$Z*a2_BSBCbd*w2
"Padl" AP3)7dFZz$%A/#
etc.
Example:
10 F$="RES.DO"
20 CALL A,5,VARPTR(F$) : REM Set resource filename
30 CALL A,Y+128,X
40 R$="Ball"
50 CALL A,4,VARPTR(R$) : REM Render resource "Ball" from RES.DO
Set resource filename
---------------------
OP: CALL A, 5, VALPTR(S$)
This function sets the filename of the resource file from
which CALL A,4,VARPTR(R$) resources will be read. See above
for example.
BUILDING STRINGS
================
In order to use AsciiPixels, one first needs a way to encode the pixel
data into a string that AP can decode and render. Looking at the few
examples in this document, it is clear that encoding by hand is out of
the question. So two methods have been developed (so far) for converting
source images into encoded AsciiPixel strings. Both will be mentioned here,
but only one will be described:
- A Model 100/102/200 BASIC program called MAKEAP.BA
Converts images in a formatted .DO file into AP strings. This
one is described below.
- A Linux C program called pbm2ap
Converts standard pbm (Pixel Bit Map) images (export from GIMP, etc.)
into AP strings. This is a project of its own and is not described
here. It can be used to convert full images into AP strings.
MAKEAP.BA
---------
This is a BASIC program that runs on the Model 100/102/200 and reads
"icon" / image source data from a .DO file and creates a new .DO file
containing the encoded AP string for each image in the file. The file
names of both the input and output files are queried when the program
excutes.
The input file can contain multiple images (i.e. a "resource file"),
and each image will be added to the output file in a format compatible
with the CALL A,4,VARPTR(R$) render resource operation. Images in the
source file can be specified on image per line or multiple images per
line. Each image consists of a name, size specification and image data
drawn using '*' and ' ' characters. Multiple images per line are
separated with ',' and each image or group of images must be terminated
using an '=' sign (or really any character other than '*' or ' ').
An example resource file is provided:
CHECK, NOCHECK, NODOT, DOT
7x7, 7x7, 7x7, 7x7
*******,*******, *** , ***
* *,* *, * * , * *
* *** *,* *,* *,* *** *
* *** *,* *,* *,* *** *
* *** *,* *,* *,* *** *
* *,* *, * * , * *
*******,*******, *** , ***
=
OKBTN
19x9
*************
** **
* **** * * *
* * * * * *
* * * ** *
* * * * * *
* **** * * *
** **
*************
=
OKINV
19x9
*************
*****************
***** * ** *****
***** ** * * ******
***** ** * *******
***** ** * * ******
***** * ** *****
*****************
*************
=
And the resulting output file will look like:
"CHECK" AP3**nC@^Y0[B
"NOCHECK" AP3**nC$&)/[B
"NODOT" AP3**?'(/;34?#
"DOT" AP3**?'XP>:4?#
"OKBTN" AP36,[pSi._5;+8S3=CD7$&R'=h&s#
"OKINV" AP36,[pSua3^m9`m9am9`m3^^tSq#
As indicated, the output resource file can be used directly via
the "Render from resource" operation, or the resulting encoded ASCII
text can simply be copied to a BASIC program, assigned to a variable
and rendered via the "Render from string" operation.
STRING ENCODING FORMAT
======================
Top Secret.
