_ _ _ ____ _ _ / \ ___ ___(_|_)| _ \(_)_ _____| |___ / _ \ / __|/ __| | || |_) | \ \/ / _ \ / __| / ___ \\__ \ (__| | || __/| |> < __/ \__ \ /_/ \_\___/\___|_|_||_| |_/_/\_\___|_|___/ Version 1.0 Copyright 2015, 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 depends on M100/T102 vs 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: - Model 100/102: clear 256,58000 - Model 200: clear 256,58000 3. Still from BASIC, load the CO: loadm "ASCPIX" 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.