diff --git a/collects/htdch/graphics/doc.txt b/collects/htdch/graphics/doc.txt new file mode 100644 index 0000000000..467c79c86a --- /dev/null +++ b/collects/htdch/graphics/doc.txt @@ -0,0 +1,278 @@ +This graphics package provides libraries for creating images and modeling in a visual world. + +The package includes the following classes, each to be discussed in their own section: +Posn +Image +PictureFactory +Color +View +Command +CommandSequence +World +GameWorld +--------------------------- + +class Posn: + + +----------+ + | Posn | + +----------+ + | int x | + | int y | + +----------+ + +new Posn(3,4).equals(new Posn(3,4)) == true + +------------------------- + +class Image: + ++---------------------------------------------+ +| Image | ++---------------------------------------------+ ++---------------------------------------------+ +| Posn getPinhole() | +| Image movePinhole(Posn) | +| Image putPinhole(Posn) | +| Image overlay(Image) | +| Image overlayXY(Image, Posn) | +| Image addLine( Posn start, Posn end, Color) | +| boolean inside( Image ) | +| Posn find(Image) | +| int width() | +| int height() | ++---------------------------------------------+ + +An Image is created either by inserting a Special Image into DrScheme or by building an Image using the PictureFactory. + +Headers & Purposes: +//Return the pinhole for this Image, typically its center point +Posn getPinhole() + +//Create an Image like this Image, with its pinhole offset by p from this pinhole +Image movePinhole( Posn p ) + +//Create an Image like this Image, with its pinhole at p +Image putPinhole( Posn p ) + +//Create an Image by placing i over this Image at the pinholes +Image overlay( Image i ) + +//Create an Image by placing i over this Image, centering i's pinhole at p +Image overlayXY( Image i, Posn p) + +//Create an Image by adding a line to this Image +Image addLine(Posn start, Posn end, Color c) + +//Determine whether the Image isInside is inside this Image +boolean inside( Image isInside ) + +//Report the position at which inside is in this Image +Posn find( Image inside ) + +//Report the width of this Image +int width() +//Report the height of this Image +int height() + +------------------------ + +class PictureFactory : + ++-----------------------------------------------+ +| PictureFactory | ++-----------------------------------------------+ ++-----------------------------------------------+ +| Image makeCircle(int, String, Color) | +| Image makeRectangle( int, int, String, Color) | +| Image makeEllipse( int, int, String, Color) | +| Image makeTriangle( int, String, Color) | +| Image makeLine( Posn, Color) | +| Image makeText( String, int, Color) | ++-----------------------------------------------+ + +A PictureFactory is created by calling new PictureFactory(boolean). +If the boolean is true, then the pinhole of created images will be in the center, otherwise the top left. + +Possible values for mode, "solid" "outline" + +Headers & Purposes: +//Create a circle with radius r, color c, in the style of the mode +Image makeCircle( int r, String mode, Color c) + +//Create a rectangle with width, and height, of color c, in the style of mode +Image makeRectangle( int width, int height, String mode, Color c) + +//Create an Ellipse with width and height and color c, in the style of mode +Image makeEllipse( int width, int height, String mode, Color c) + +//Create an equalateral triangle with edge length edge and color c, in the style of mode +Image makeTriangle( int edge, String mode, Color c) + +//Create a line with end position to (start is 0,0) and color c +Image makeLine( Posn to, Color c) + +//Create a text Image with the given text, of height ptSize and color c +Image makeText( String text, int ptSize, Color c) + +Note: PictureWorld at present ignores the boolean argument and always assumes its true. + +----------------------- + +abstract class Color: + + +-------+ + | Color | + +-------+ + +-------+ + / \ + --- + | + ---------------------------------------------------------------------------------------------------------------------- + | | | | | | | | | | + +-------+ +------+ +-------+ +-------+ +--------+ +--------+ +--------+ +-----+ +-------+ +--------+ + | Black | | Blue | | Brown | | Green | | Purple | | Orange | | Purple | | Red | | White | | Yellow | + +-------+ +------+ +-------+ +-------+ +--------+ +--------+ +--------+ +-----+ +-------+ +--------+ + +-------+ +------+ +-------+ +-------+ +--------+ +--------+ +--------+ +-----+ +-------+ +--------+ + +Each variant of Color is a color within the drawing system. Additional colors can be addded by subclassing Color. +The toString method of a subclass of Color should return a string in all lower-case of color to be depicted: +new Brown.toString().equals("brown") + +(Note: Color aught to be an interface) + +------------------------ + +class View: + ++---------------------------------------+ +| View | ++---------------------------------------+ ++---------------------------------------+ +| View display(int, int) | +| View hide() | +| View show() | +| Image draw( Command ) | +| Image drawSequence( CommandSequence ) | ++---------------------------------------+ + +Headers and Purposes: + +//Produces a View with a visible canvas of size x and y +View display( int x, int y) + +//Produces a View without a visible canvas +View hide() + +//Produce a View with a visible canvas (display must have been called) +View show() + +//Issue the drawing command, produce an Image that reflects what the canvas displays. +Image draw( Command c) + +//Issue the drawing commands in the seqence, produce an Image that reflects what the canvas displays after all commands +Image drawSequence( CommandSequence commands ) + +-------------------------- + +class Command: + + +---------+ + | Command | + +---------+ + +---------+ + / \ + --- + | + -------------------------------------------- + | | | + +-------------+ +-----------------+ +---------------+ + | DrawLine | | DrawImage | | DrawRectangle | + +-------------+ +-----------------+ +---------------+ + | Color color | | Image i | | Posn corner | + | Posn start | | Posn leftCorner | | int width | + | Posn end | +-----------------+ | int height | + | int width | | Color c | + +-------------+ | String style | + +---------------+ + +------------------------- + +class CommandSequence: + + +-----------------+ + | CommandSequence |<--------------+ + +-----------------+ | + +-----------------+ | + / \ | + --- | + | | + ----------------------- | + | | | + +----------+ +----------------------+ | + | EmptySeq | | LargerSeq | | + +----------+ +----------------------+ | + +----------+ | Command first | | + | CommandSequence rest |----+ + +----------------------+ + +------------------------ + +abstract class World, abstract class GameWorld extends World + + +---------------------+ + | World |<----------+ + +---------------------+ | + | View display | | + +---------------------+ | + | World onKey(String) | | + | World onTick() | | + | Image draw() | | + | Image erase() | | + +---------------------+ | + / \ | + --- | + | | + - | + | | + +------------------------------+ | + | GameWorld | | + +------------------------------+ | + +------------------------------+ | + | World transition( World) |----+ + | boolean animate(int,int,int) | + +------------------------------+ + +To create games, you should subclass GameWorld, othewise you should await more classes. + +Subclasses of GameWorld do not need to set the World's display. + +Headers & Purposes (from subclassing GameWorld): + + //Produce a World with the effects of receiving the given key press + abstract World onKey( String key ); + + //Produce a World with the effects of one clock tick passing + abstract World onTick(); + + //Issue the commands that represent this world to the display + abstract Image draw(); + + //Issue the commands that will erase portions of the world that should no longer be visible to the display + abstract Image erase(); + + //Produces a World that will animate with a clock tick of rate, in a display of size width x height + boolean animate( int width, int height, int rate ) + + //Produces a world where animation has stopped + World endOfWorld(); + + //Produces a World with the same display but potentially different representations + World transition( World w); + + +Things to know when making a Game: + +animate will call the onTick method every rate miliseconds. +Prior to calling onTick, animate will call erase. +After calling onTick, animate will call draw on the resulting world. \ No newline at end of file