Carousel Volume 2 #1/carousel.iso/mactosh/tech/graphics.txt

Text File | 1985-04-15 | 11KB | 286 lines

- -------------------------------------------------------------------------
The Macintosh Standard Graphics Protocol
----------------------------------------
By Scott Watson (CompuServe 73176,61)



The Macintosh Standard Graphics Protocol is an attempt to standardize (or
at least provide a common subset of functions) the rapidly growing desire
to send QuickDraw graphics over a modem.  This protocol has been con-
structed with several essential properties in mind:

1) It must give access to the most frequently used QuickDraw routines.
2) It must have the least amount of overhead necessary to reduce the lag
   between transmission and actual display on the user's terminal.
3) It must be error checked and acknowledged by the recipient to prevent
   a line spike from causing a system crash due to execution of QuickDraw
   routines with erroneously received parameters.
4) It must be easily implemented in any communications program, must not
   be language specific (as long as the QuickDraw routines used are
   accessable through a given language), and it must be small enough to
   be constructed as an unloadable segment for when it's not in use.
5) It must be completely transparent to the user (no confusing "options"
   or necessary commands for the user to become entangled with), and must
   be completely controllable by the host.
6) It must allow transmission of the user's mouse cursor when the mouse
   button is pressed to allow 2-way real time graphics functions.
7) There must be no need to document the protocol in your users' manual.


Acceptance of this standard will ensure that your program will be
compatible with the other programs that have adopted this standard, and
will work with the Lazarus BBS program soon to be released from The
FreeSoft Company.  This program will appear as a local Macintosh appli-
cation (mouse buttons, graphics, animation, dialog boxes, etc.) to the
user of your program once connected.  To foster the acceptance of this
graphics standard, we will distribute the BBS program at low or no cost,
provide a debugging host to those trying to implement this protocol,
and make this standard public domain.

Although it is a public domain protocol, I would feel grateful if you
would make mention of me as the creator of the protocol in your users'
manual should you make mention of it.


Overview
--------
Throughout these specs, we will refer to two different machines, the host
is the computer running a BBS or similar program.  The remote is the
computer running your communications program.  All numbers are given
in decimal.

In a TTY or other textual information mode, the remote should constantly
trap the receipt of an ASCII code 26.  Once this occurs, you need to trap
for the following characters in order: 16,04, and 12.  These are called
the signiture bytes.  When you receive these bytes in that order, you are
to immediately enter the graphics mode and send out a Type 45 packet
(Acknowledge Graphics On).  If you don't receive the above sequence within
three seconds of receiving the ASCII code 26, consider the 26 to be a
fluke and return to your textual processing.

The host should ensure that there has been at least 1 second of silence
on the line before sending the signiture bytes.

What Happens When You Enter The Graphics Mode
---------------------------------------------
There is only one flag you need to keep track of while in the graphics
mode - whether or not the host wants to allow the remote to send Type
49 packets (MouseDown Report).  When you initially enter the graphics
mode, this flag is reset so that MouseDown events are not reported over
the modem.

Updates are not allowed either, so it is imperative that you disable any
menu choices or other actions that would botch the display while in the
graphics mode.  Actually, you are given a great deal of freedom of what
you can do while in the graphics mode, as long as you are capable of
restoring the screen yourself after it's been botched by a Desk Accessory
or other function.

There is a failsafe in case the remote should lose carrier while in the
graphics mode.  Your program should look for the user to type COMMAND-X,
and exit the graphics mode if it is in operation.  It's recommended that
you don't document this, rather, let the host do it immediately upon
receiving the Type 45 packet from the remote.  Since the host can cause
your program to jump back and forth between the graphics and textual
modes, you don't lose any of the capabilities of your software, such as
file transfers, desk accessories, etc. that would otherwise botch the
screen.

Upon entering the graphics mode, you should display a type 1 (modal
dialog or alert appearance) style window using the rectangle:
30,10,330,503.  This window takes up nearly all of the screen below the
menu bar, cannot be moved, removed, or sized through user mouse control.
In other words, it's awfully hard to screw up as long as you pay attention
to the above requirements.  The above rectangle is important as M.S.G.P.
commands are assumed to operate in that area only.

There is an exception to the above.  The command types between 100
and 255 are reserved for your use.  If you have special needs for the
graphics mode, such as setting up a MacPaint-type drawing interface, you
could use one of the special commands to set up the window using different
coordinates, leaving room for tools and other information.  However, when
your program is a remote, it has to have the ability to use the above
coordinates as a default.

Now we've entered the graphics mode, drawn our window, and sent back the
Type 45 packet.  What's next?

Data Flow
---------
Data flow is nothing more than an exchange of packets and acknowledgements,
much like the XMODEM protocol.  However, since this is an interactive
mode, there is no timeouts waiting for the next packet, and packet exchange
is actually in two directions.

A packet is variable length, and is in the following general format:

SOP/LEN/COM/DAT/DAT/DAT/DAT.../CHK

SOP - Start of packet byte (arbitrarily set as ASCII code 3)  The remote
continually looks for an ASCII 3, and can assume any other characters are
line spikes.

LEN - The number of bytes following, not including the checksum.

COM - The packet command type (these are numbered from 1 to 50 and are
explained below.

DAT - The data, which will be used as the parameters for the command.

CHK - The checksum, which is the sum of the LEN, COM and DAT bytes,
logically ANDed with 127.

After receiving a complete packet, the remote should send either an
ACK (ASCII code 6) if the checksum matches, or a NAK (ASCII code 21) if
it doesn't.  You should set a timeout of 3 seconds to receive the full
packet once the SOP has been received, and then automatically NAK the
packet if it never comes through.  You send the ACK after the command is
actually executed, to allow further parameter error checking if desired.

The host will continue to re-send NAKed packets until an ACK is received.

All DAT bytes are assumed to be unsigned (0 - 255).  Integers are sent
with the most significant byte first.  All parameters are sent in the
same order as is documented in the QuickDraw section of Inside Macintosh.
The only exception is the Scroll command, which differs slightly from
the QuickDraw ScrollRect function as documented below.


The Command Types and Their QuickDraw Functions
-----------------------------------------------

1) SetCursor
2) HideCursor
3) ShowCursor
4) ObscureCursor
5) LineTo
6) Line
7) BackPat
8) PenSize
9) PenMode
10) Move
11) PenNormal
12) MoveTo
13) PenPat
14) HidePen
15) ShowPen
16) TextFont
17) TextFace
18) TextMode
19) TextSize
20) DrawChar
21) DrawString
22) FrameRect
23) PaintRect
24) EraseRect
25) InvertRect
26) FillRect
27) FrameOval
28) PaintOval
29) EraseOval
30) InvertOval
31) FillOval
32) FrameRoundRect
33) PaintRoundRect
34) EraseRoundRect
35) InvertRoundRect
36) FillRoundRect
37) FrameArc
38) PaintArc
39) EraseArc
40) InvertArc
41) FillArc
50) InitCursor

Non-QuickDraw Packets
---------------------
42) reserved for future use.
43) MouseEnable (no parameters) - When you receive this packet set the
mouse flag so that any MouseDown event in the graphics window will send
a Type 49 packet.
44) MouseDisable (no parameters) - Reset your mouse flag so that no
MouseDown events are reported to the host.
45) AcknowledgeGraphicsOn (no parameters) - send this as soon as you enter
the graphics mode to let the host know you have responded to the
signiture bytes and are ready for M.S.G.P. commands.
46) reserved for future use.
47) Scroll(therect: Rect; X,Y:INTEGERS) - This is just like the ScrollRect
function in QuickDraw, except that the region handle is not sent.  If the
most significant bytes of X or Y is non-zero, the least significant bytes
are deemed to be negative.
48) Exit Graphics Mode (no parameters) - This is your signal from the host
to return to your TTY or textual mode.
49) MouseReport(X,Y:INTEGERS) - convert the global coordinates of the
MouseDown event in the graphics window to local coordinates.  Remember,
your mouse flag must have been set through a Type 43 command before you
would send this packet type.

Types 100-255: Not currently part of this protocol and reserved for use
with your program communicating with like programs.


A Typical Session
-----------------
The following are the actual bytes SENT by the host and remote.  My
comments are in parentheses.  The numbers are in decimal.

Host: 26,16,4,12
(The host sends the signiture bytes)
Remote: 3,1,45,46
(The remote acknowledges with a Type 45 packet)

Host: 3,5,12,0,25,0,25,67
(The Host sends a MoveTo(25,25) packet (Type 12))
Remote: 6
(The Remote ACKS the packet)

Host 3,3,16,0,0,19
(The Host sends a TextFont(0) packet (Type 16))
Remote: 6

Host: 3,3,19,0,12,34
(The Host sends a TextSize(12) packet)
Remote: 6

Host: 3,7,21,5,72,69,76,76,79,21
(The Host sends a DrawString("\005HELLO") packet. Notice that whenever
parameters would be a pointer for an actual QuickDraw call, the actual
bytes pointed to would be sent in an M.S.G.P. packet.  Remember that a
Pascal string starts out with a byte indicating it's length).
Remote: 6

Host: 3,5,22,0,200,0,200,1,34,1,34,113
(This is a FrameRect(200,200,290,290) packet)
Remote: 21
(Remote's didn't get the right checksum and NAKs it!)

Host: 3,5,22,0,200,0,200,1,34,1,34,113
Remote: 6
(OK, now the remote got it right)

Host: 3,9,13,119,137,143,143,119,152,248,248,51
(This is a PenPat packet with one of the patterns in the Control Panel
Desk Accessory)
Remote: 6

Host: 3,1,43,44
(The host enables the remote's mouse)
Remote: 6

(the remote now presses his mouse button with the cursor pointing at
local coordinates X=24, Y=100)
Remote: 3,5,49,0,24,0,100,50
Host: 6
(The host should always ACK a Type 49 packet as long as the checksum is
correct, even if the mousepress was not in a valid area - just ignore it)


Keyboard
--------
The keyboard is supported at all times for the remote.  The host can
choose to simply ignore keypresses, or deal with them as appropriate.
Control characters are not a part of this protocol, as handshaking is
not relevant with proper host construction, and the COMMAND-X keypress
is withheld for remote use to exit the graphics mode.