- ------------------------------------------------------------------------- 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.