Read Me

Chapters:
1) Setup - How to get things working
2) Reading the Code - Recommended order of perusal
3) Usage Overview - Quick synopsis of usage.
4) Internals Overview - Quick synopsis of internal behaviours. 

1) Project Setup
   - Currently, the project is only set up for use under Windows using the Visual Studio IDE.
   - More support will hopefully be added later
   - It is likely that, for much of the project, the only "missing support" is the appropriate section in this README.
   
   === Windows with Visual Studio ===
   - Specifically, Windows 7 and VS9.0, although the same instructions will likely work for previous versions.
   A) Boost:  
      - http://www.boost.org/doc/libs/1_41_0/more/getting_started/windows.html
      - http://www.boostpro.com/download
      i)   You need to install boost onto your computer. The simplest method for Windows is to use the BoostPro installer.
      ii)  You need to alter: Project -> Properties -> C/C++ -> General -> Additional Include Directories
           Point it at your "boost\boost_{VERSION #}\" directory 
      iii) You need to alter: Project -> Properties -> Linker -> General -> Additional Library Directories
           Point it at your "boost\boost_{VERSION #}\lib" directory
   
   B) Allegro:
      - http://www.allegro.cc/files/
      i)   You will want the precompiled binaries (under the "Binary" section) -> YOU WANT THE ALLEGRO 4.9.16
      ii)  Unzip and place them in "Microsoft Visual Studio 9.0 -> VC -> lib", "VC -> include", and "VC -> bin"; put in "/allegro"
      iii) Obtain the latest DirectX SDK from Microsoft
      
   c) Possible Problems:
      i) fatal error C1900: Il mismatch between 'P1' version '20080116' and 'P2' version '20070207'
       - Solution: Update your Visual Studio. 
       
   d) Known Errors / Warnings:
       i)  Allegro gives a great deal of "LNK4099 .pdb not found" errors. 4099 is non-suppressable, and means that you can't debug in those libraries.
       ii) There will be a number of 


2) Reading the Code
   - I have tried to keep the code well-documented.
   - Note that -all- todo's, comments about what needs to be changed, etc, are on Sourceforge under Bugs or Feature Requests
   A) Recommended Order:
      - Switchboard.h
      - Paradigms.h
      - Switchboard.cpp
      - inputTree.h & cpp
      - renderTree.h & cpp
      
3) Usage Overview (WIP)

	Components can have access to channels, which are local to the entity in which the component resides.
	To have components (be an entity), you must inherit from Switchboard. 
	Channels are defined by an ID class, a type of data to hold, and a policy for dealing with that data (push, pull, etc).
	  Note this: Channels have a policy for their data, so you can change up how that data gets handled.
    More or less, consider everything mixins; classes that you inherit from to add functionality. 
    
    Entities is-a switchBoard. 
    Entities own 0+ components
    Entities own 0+ channels, that are created on request by components
    Components have 0+ channels
       Channels are how components communicate
    Channels have 1+ connected components
       Channels have a policy that governs how data gets "broadcast" to connected components
   
   - To be an entity (capable of having components), inherit from components::switchboard. Define an init() function; don't add components in the constructor.
   - To be a component, inherit from components::component
   - To use a channel, inherit from accessChannel<...> or createChannel<...>
      - "access" or "create" defines your relationship to the data
      - Template Arguments:
         - ID: A class ID. Irrevelant except for explicit "naming" of the channel, and some policies restrict which ID class can be used.
         - infoType: The type of data to be stored. Data is passed-by-value (copied). 
         - paradigmPolicy: The policy for handling the data. (Push, pull, tell, inform, etc)
            - Regretably, at this time the policy must also be told the infoType
         - Example: accessChannel<foo, int, pull<int> >
      - listen() gets the data, if your access/create + policy gives access
      - talk(infoType) broadcasts data, if your access/create + policy gives access
      - Some policies require a callback function:
          - callOnPush()
          - callOnTell()
          - Example usage: accessChannel<...>::callOnPush() {...}
          
4) Internals Overview: (WIP)

	Switchboard is the factory for all components and channels.
	When you talk(...), the data in the channel gets operator= to the new value.
	  Some policies then trigger callbacks