[doc] readme, copy

1 files changed, 10 insertions, 8 deletions

diff --git a/README.org b/README.org
index d793068..52dbc0f 100644
--- a/README.org
+++ b/README.org
@@ -44,14 +44,11 @@ Then load one of the example files and call its "start" function:
 
 ** Basic Use
   
-   The best introduction is to look at and play with the examples.
-   What follows is a cursory explanation of how pieces are meant to
-   fit together.
-
+   The best introduction to wheelwork comes through looking at and playing with the examples.  IN addition to playing with examples, consider what follows as a suppliment that helps explain how some of the pieces fit together.
 
 *** The Application 
     
-When you want to use Wheelwork, you must make a sublcass of ~application~. The ~application~ is the main container supplied by wheelwork. It is the root of the [[*The Display Tree Protocol: Units and Containers][display tree]], holds references to [[*The Asset Protocol][loaded assets]], and handles [[*Events & Event Handling][events]] from the user.
+When you want to use Wheelwork, you must make a sublcass of ~APPLICATION~. The ~APPLICATION~ is the main container supplied by wheelwork: it is the root of the [[*The Display Tree Protocol: Units and Containers][display tree]], holds references to [[*The Asset Protocol][loaded assets]], and handles [[*Events & Event Handling][events]] from the user.
 
 For example, from the pong example in =examples/08-pong.lisp=, the application class looks like 
 
@@ -64,6 +61,10 @@ For example, from the pong example in =examples/08-pong.lisp=, the application c
 
 This defines a subclass of appliation along with some state needed for the pong game.
     
+**** The Window & Scale & Coordinates
+
+Wheelwork uses SDL2 to create windows and generate events. The application includes a global scale factor that affects how the game interperets coordinates inside the window.  A window, for example, can be 800x600 pixels on your computer monitor, but if the application's scale factor is 2.0, then it will only have a 400x300 logical space of coordinates.  If you add a sprite that is 30x30 pixels big 
+
 **** The Boot Method
 
 It isn't enough to define a subclass, you must also implement a ~ww:boot~ method for your application class. The boot method is called right after the opengl context becomes available. Inside boot, you are expected to do everything necessary to start your game: load assets, create some display units, add them to the scene, and add event handlers.  Here is what the boot method looks like for the pong game.
@@ -96,14 +97,13 @@ It ends by adding a handler to the app called ~press-to-start~, where presumably
 
 The shutdown method is optional and is called right before the application exits. If supplied, it is a good place to do things like: make save files, close network connections, clean up foreign memory resources that are not already managed by the [[*The Asset Protocol][asset protocol]].  
 
-
 *** The Display Tree Protocol: Units and Containers
     
-Objects that render to the screen are organized into a display tree. There are two basic kinds of objects: **units** and **containers**. Units are what you want to display and containers are for controlling when and where you want to display those units. 
+Objects that render to the screen are organized into a display tree. There are two basic kinds of objects: **units** and **containers**. Roughly, units are the things you want to display and containers help to control when and where you to display them. 
 
 Units are added to and removed from containers, and a unit will belong to at most one container at a time. In general, the last thing added to a container will be the last thing rendered - i.e. it will appear to be "on top".  Containers are themselves units, so they too can be added to other containers. Nesting of containers allows you to render a one set of units before or after some other set of units.
 
-The application is itself a container, and is the only unit that does not need to be added to a scene. Nothing no unit will display until it becomes part of the display tree rooted at the application.
+The application is itself a container, and is the only unit that does not need to be added to a scene.  No unit will be displayed until it becomes part of the display tree rooted at the application.
 
 Containers have "bounds", which are screen coordinates for the left, right, top, and bottom of the region inside of which units will be displayed. If a unit moves out of bounds, it will not show up on the screen, and will not receive mouse events. (It may, however, still be focused - and hence receive key events.) The bounds of the application are the visible window itself. Other containers may have custom bounds.
 
@@ -136,6 +136,8 @@ More specifically, you can use the following accessor functions on them:
 
 There are a few convenience functions also defined that use the above functions under-the-hood. I'm not including them here because the API is still stabilizing. 
 
+The =0,0= coordinate is the bottom left corner fo the game window, and the top right corner is =w,h=, the width and height of the screen, respectively. 
+
 The affine units are things like:
 
 + ~bitmap~: display an image that has been loaded from a file asset (currently only png is supported)