HELP RETINA                                  Jocelyn Paine November 1992


This module defines the data structure that makes up a bug's retina, and
a routine for creating retinal images from Ved buffers. You can load it
by doing
    lib retina;
if using Eden, this will have been done for you.


Introduction
------------

You will usually use a retina when inspecting Bug's vision. The routine
'retina' returns what looks like a 2-D array. You access it by
subscripting:
    retina(3,4) =>
This will give you a character. The origin of a retina is (1,1), and
in the current version of Eden, the X and Y bounds are 5 and 7
respectively.

Printing a whole retina, e.g. by doing
    retina() =>
will show you the whole thing line by line.

If you are just writing your own bug, this is probably all you need to
know. Trying to update the retina from inside a bug is not sensible, and
Eden may prohibit it. However, people writing variants of Eden itself
will need to know about the other routines. They may also be useful if
you want to test visual routines, but without running them from inside a
bug; that is, if you want to build your own retinas to test them on.


General information
-------------------

The module defines a record type 'retina'. You create one by calling
    new_retina( width, height ).

You can also create retinas from inside Ved. There's a Ved command,
'retina', which takes the current buffer and makes it into a 'retina'
datatype.

Although 'retina' is a record, it acts for most purposes like an
array. You access it by subscripting:
    retina(3,4) =>
    `#` -> retina(x,y);
Retinas are mapped onto strings, so you'll get an error if you try to
store anything other than a character in them. In fact, there's
an extra check that this character is printable.

You can enquire about the bounds by calling 'retina_bounds'.

As already mentioned, the print-arrow will automatically print the
contents, line by line. This is implemented by setting the datatype's
class-print to a special display routine.


Exported routines
-----------------

PUBLIC new_retina( width, height ):

Returns a new retina, contents all spaces, of the specified width and
height.


PUBLIC retina_bounds( retina ):

Returns the retina's x and y upper bounds, in the order
xmax ymax.    


PUBLIC retina(x,y): (subscripting)

Returns the (x,y)th element of retina, as a character. The origin is
(1,1).


PUBLIC c -> retina(x,y): (updater via subscripting)

Sets the (x,y)th element of retina to character c. c must be either a
space, or printable.  


PUBLIC ved_retina():

Defines the Ved command 'retina', which copies the contents of the
current buffer into a retina.                   

The command can have the following forms
    retina
    retina name
    retina xmax ymax
    retina name xmax ymax

These commands create a new retina and assign it to valof(name). If name
is omitted, it defaults to "retina".

If xmax and ymax are specified, then they act as the retina's upper
bounds. The retinal coordinate system runs with Y upwards, so the Ved
line ymax becomes retinal line 1: that is, retinal point (1,1)
corresponds to Ved point (1,ymax), and retinal point (1,ymax)
corresponds to Ved point (1,1).

If xmax and ymax are omitted, they default to the rightmost occupied
column, and to the highest-numbered occupied line.
