[Coco] BASIC09 GPLOAD clarification?

[Willard Goosey]

On Sun, Jun 05, 2011 at 05:51:03PM -0500, CoCo Mongrel wrote:
> I'm a little uncertain about how GPLOAD in GFX2 is supposed to work.  More
> importantly, how does it actually work?  The FM says it's supposed to load a
> Get/Put buffer with data from a disk file.  The parameters listed in the
> documentation (aside from the "GPLOAD" command) are group, buffer, format,
> xdim, ydim, and size.  But nothing is mentioned about a path list, or a
> pointer to a disk buffer, or anything that looks likely to actually get data
> into the G/P buffer.

Most of the calls by GFX2 (and it's C version, CGFX) don't actually do
anything but tell Windint (cowin in NitrOS) (1) to do stuff.  In this
case, GPLOAD gets windint ready to read binary data into a get/put
buffer.  Immediately after issuing a GPLOAD, you need to write the
graphics data to the screen.

A quick, context-less example (page 256, "The Complete Rainbow Guide to
OS-9 Level II Volume 1: A Beginners Guide to Windows")

DIM Buffer:BYTE
[...]
RUN GFX2("gpload",1,2,7,40,19,190)
FOR i:=0 to 189
   READ Buffer
   PUT #1, Buffer
NEXT i

Technically, run GFX2("GPLOAD",<params>) writes the characters (hex) 1B 2B
<params> to the window.   That's all it does.  Windint then expects <size>
bytes of data to be written to that window.

You can do the same thing from the shell with display ("display 1b 2b
...") or from BASIC09 with PUT or PRINT.  GFX2 provides a human-readable
interface.  Much easier to read, understand, and change.

The talk about disk files is misleading.  It comes up because its common
for windint bitmaps to be disk files, and these can be loaded by
merge'ing the file to a window.  MERGE /dd/sys/stdptrs > /w1 for instance. 
These files look like: 1B 2B <gpload params> <data>.

The example above reads its graphics data from B09 DATA statements, but
could just as easily be a disk file.  The ultimate source doesn't matter
to windint.

Windint, you see, is almost completely controlled by escape sequences
like this.  It's a very "clean" design for a graphics system.

>  Also, the example given at the bottom of the page
> (9-98 of the BASIC09 Reference) uses the "DEFBUFF" command rather than
> "GPLOAD".  

Typo.  The Tandy manuals are notoriously full of 'em. :-(  On the same
page, the format code should refer to Table 9.6...

>Am I just misunderstanding the purpose of GPLOAD, or is this
> mal-documented?

At best, the GFX2 manual entry is _very_ poorly phrased.  The Tandy CGFX
manual says it a little better: "Prepares to load a get/put buffer...
the system loads the next bytes written to that path into the specified
get/put buffer."

The docs for Mike Sweets' CGFX7 says "GPLoad will generate the necessary
loading header to preload a get/put buffer. ... A write should directly
follow this call to insure the buffer is not loaded with garbage..."

Sometimes you see or hear of "clip", "clp", or "buff" graphics files. 
These are like merge-able gpload files such as stdfonts, but aren't fully
specified.  They don't have the GPLOAD escape codes, the group number,
or the buffer number.  They start with <type> <x-size> <y-size> <length>
<data>...  To load one of these from the shell you would "display 1b 2b
<group> <buffer> ; merge <file.clp>, or something similar in BASIC09 or
C.

Well, 4 different books later, I hope you understand this a little
better.  I'm no LII graphics master, but I do have a grip on GPLoad. :-)

(1)I don't know if grfint supports get/put buffers or not.  I never used
grfint, certainly never tried to program for it.

Willard
-- 
Willard Goosey  goosey at sdc.org
Socorro, New Mexico, USA
I search my heart and find Cimmeria, land of Darkness and the Night.
  -- R.E. Howard