hermes
Class World

java.lang.Object
  extended by java.lang.Thread
      extended by hermes.World
All Implemented Interfaces:
java.lang.Runnable

public class World
extends java.lang.Thread

The World defines a 'game state': it keeps track of all the Beings, Groups, and their interaction. This is done through registration, HObjects and Interactors must be registered with the World in order to be drawn or updated.

The World is a Thread. When start is called, the World will automatically update all registered objects and apply all Interactors between them. This runs on the World's thread, which is separate from the Processing's draw thread. This multithreading can be bypassed by not calling start, and instead calling update within Processing's draw method. By default to update rate is locked to 60Hz. You can change this, or unlock the rate, by calling lockUpdateRate and unlockUpdateRate.

There are two basic ways of working with a World. One is to set up all of your objects and Interactors outside of the World, and register them in Processing's setup. The other is to create a subclass of World, declare many variables inside this class, and override the empty World setup and shutdown methods. This allows for more control as additional computations can be done in the preUpdate and postUpdate methods, called by the thread before and after update, respectively.


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
protected  HCamera _camera
           
protected  PostOffice _postOffice
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
World()
          Constructor that automatically creates PostOffice and HCamera
World(HCamera view)
          Constructor that automatically creates PostOffice
World(int portIn, int portOut)
          Constructor that automatically creates PostOffice and HCamera, and sets up OSC
World(int portIn, int portOut, HCamera view)
          Constructor that automatically creates PostOffice and sets up OSC
World(PostOffice postOffice)
          Constructor that automatically creates HCamera
World(PostOffice postOffice, HCamera view)
          Instantiates the world with a PostOffice to handle I/O and a Camera to handle drawing.
 
Method Summary
 void addToGroup(HObject object, GenericGroup<?,?> group)
          Queues an HObject to be added to a group at the end of the current update.
 void deactivate()
          Tells the world to stop running.
 void delete(HObject object)
          Queues an HObject to be removed from all of the groups it is in at the end of the current update.
 void draw()
           
 PostOffice getPostOffice()
           
 boolean isActive()
          Returns true after start() has been called.
 void lockUpdateRate(int rate)
          Locks the update rate to happen no more than rate times per second.
 void postUpdate()
          Will be executed on each loop after update is called.
 void preUpdate()
          Will be executed on each loop before update is called.
 void register(Being being)
          Shortcut for adding Being w/ update
 void register(Being being, boolean update)
          Registers a being with the world, making it be drawn when it is on camera, its update method will be called by the loop if update is true.
 void register(GenericGroup group)
          register a group to have its update called in the update loop
 void register(GenericGroup A, GenericGroup B, Interactor inter)
          Register an interaction to be handled on the update loop.
 void register(GenericGroup A, GenericGroup B, Interactor inter, Optimizer optimizer)
          Register an interaction to be handled on the update loop.
 void register(GenericGroup A, HObject B, Interactor inter)
          register an interaction between B and all objects in A
 void register(HObject A, GenericGroup B, Interactor inter)
          register an interaction between A and all objects in B
 void register(HObject A, HObject B, Interactor inter)
          Register an interaction between HOjbects A and B.
 void remove(HObject object, GenericGroup<?,?> group)
          Queues an HObject to be removed from a group at the end of the current update.
 void resolveGroupQueues()
          Resolves the add, remove, and delete queues, in that order.
 void run()
          DO NOT CALL THIS METHOD.
 void setup()
          Will be called once when the world is run, before the update loop.
 void shutdown()
          Will be called once the world has finished running.
 void subscribe(KeySubscriber sub, char key)
          Registers a subscription to messages sent by a specific keyboard key.
 void subscribe(KeySubscriber sub, int key)
          Registers a subscription to messages sent by a specific keyboard key.
 void subscribe(MouseSubscriber sub, POCodes.Button button)
          Registers a subscription to messages sent by a specific mouse button.
 void subscribe(MouseSubscriber sub, POCodes.Button button, HShape region)
          A version of registerMouseSubscription that subscribes only to the requested button events that occur in the given region.
 void subscribe(MouseWheelSubscriber sub)
          Registers a subscription to the mouse wheel (one subscription gets you everything).
 void subscribe(OscSubscriber sub, java.lang.String address)
          Registers a subscription to messages received on a specific OSC address.
 void unlockUpdateRate()
          Unlocks the update rate (the rate is set to 60Hz by default).
 void update()
          Executes the update loop.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_postOffice

protected PostOffice _postOffice

_camera

protected HCamera _camera
Constructor Detail

World

public World(PostOffice postOffice,
             HCamera view)
Instantiates the world with a PostOffice to handle I/O and a Camera to handle drawing.

Parameters:
postOffice - the PostOffice that will handle mouse, keyboard and OSC I/O
view - the camera that will be used for drawing

World

public World()
Constructor that automatically creates PostOffice and HCamera


World

public World(HCamera view)
Constructor that automatically creates PostOffice


World

public World(int portIn,
             int portOut)
Constructor that automatically creates PostOffice and HCamera, and sets up OSC


World

public World(int portIn,
             int portOut,
             HCamera view)
Constructor that automatically creates PostOffice and sets up OSC


World

public World(PostOffice postOffice)
Constructor that automatically creates HCamera

Method Detail

isActive

public boolean isActive()
Returns true after start() has been called.

Returns:
whether the world is currently running

deactivate

public void deactivate()
Tells the world to stop running. Use this to terminate the world (not the deprecated stop method).


register

public void register(Being being,
                     boolean update)
Registers a being with the world, making it be drawn when it is on camera, its update method will be called by the loop if update is true.

Parameters:
being - the being to register
update - whether or not to update the being during the update loop

register

public void register(Being being)
Shortcut for adding Being w/ update

Parameters:
being - the being to register

addToGroup

public void addToGroup(HObject object,
                       GenericGroup<?,?> group)
Queues an HObject to be added to a group at the end of the current update.

Parameters:
object - the object to add
group - the group to add the object to

remove

public void remove(HObject object,
                   GenericGroup<?,?> group)
Queues an HObject to be removed from a group at the end of the current update.

Parameters:
object - the object to remove
group - the group to add the object to

delete

public void delete(HObject object)
Queues an HObject to be removed from all of the groups it is in at the end of the current update.

Parameters:
object - the object to delete

resolveGroupQueues

public void resolveGroupQueues()
Resolves the add, remove, and delete queues, in that order.


register

public void register(GenericGroup A,
                     GenericGroup B,
                     Interactor inter)
Register an interaction to be handled on the update loop.

Parameters:
A - the first interacting group
B - the second interacting group
inter - the Interactor that detects and handles this interaction

register

public void register(GenericGroup A,
                     GenericGroup B,
                     Interactor inter,
                     Optimizer optimizer)
Register an interaction to be handled on the update loop.

Parameters:
A - the first interacting group
B - the second interacting group
inter - the Interactor that detects and handles this interaction
optimizer - optimizer to use for the interaction

register

public void register(HObject A,
                     GenericGroup B,
                     Interactor inter)
register an interaction between A and all objects in B

Parameters:
A - an HObjects
B - a group
inter - the Interactor that detects and handles this interaction

register

public void register(GenericGroup A,
                     HObject B,
                     Interactor inter)
register an interaction between B and all objects in A

Parameters:
A - a group
B - a being
inter - the Interactor that detects and handles this interaction

register

public void register(HObject A,
                     HObject B,
                     Interactor inter)
Register an interaction between HOjbects A and B.

Parameters:
A - the first object
B - the second object
inter - the interaction handler upon detection or later

register

public void register(GenericGroup group)
register a group to have its update called in the update loop

Parameters:
group - the group to update

subscribe

public void subscribe(KeySubscriber sub,
                      int key)
Registers a subscription to messages sent by a specific keyboard key.

Parameters:
sub - the KeySubscriber signing up
key - the code of the keyboard key whose messages the subscriber wants (use value from POConstants)

subscribe

public void subscribe(KeySubscriber sub,
                      char key)
Registers a subscription to messages sent by a specific keyboard key.

Parameters:
sub - the KeySubscriber signing up
key - the char of the keyboard key whose messages the subscriber wants

subscribe

public void subscribe(MouseSubscriber sub,
                      POCodes.Button button)
Registers a subscription to messages sent by a specific mouse button.

Buttons are defined by constants in the POConstants class; subscribe with "NO_BUTTON" to receive information about mouse movements when no button is pressed.

Parameters:
sub - the MouseSubscriber signing up
button - the code of the button whose messages the subscriber wants (use value from POContants)

subscribe

public void subscribe(MouseSubscriber sub,
                      POCodes.Button button,
                      HShape region)
A version of registerMouseSubscription that subscribes only to the requested button events that occur in the given region.

Parameters:
sub - the MouseSubscriber signing up
button - the code of the button whose messages the subscriber wants (use value from POContants)
region - the region on screen the subscriber wants to limit its subscription to

subscribe

public void subscribe(MouseWheelSubscriber sub)
Registers a subscription to the mouse wheel (one subscription gets you everything).

Parameters:
sub - the MouseWheelSubscriber signing up

subscribe

public void subscribe(OscSubscriber sub,
                      java.lang.String address)
Registers a subscription to messages received on a specific OSC address.

Parameters:
sub - the OscSubscriber signing up
address - the address whose messages the subscriber wants

run

public void run()
DO NOT CALL THIS METHOD.
This starts the update loop, but this should be done by calling World.start instead, for threading purposes.

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

setup

public void setup()
Will be called once when the world is run, before the update loop.


shutdown

public void shutdown()
Will be called once the world has finished running.


preUpdate

public void preUpdate()
Will be executed on each loop before update is called.


postUpdate

public void postUpdate()
Will be executed on each loop after update is called.


update

public void update()
Executes the update loop. Should only be called manually if start has not been called and threading is not desired.


lockUpdateRate

public void lockUpdateRate(int rate)
Locks the update rate to happen no more than rate times per second. Default value is 60Hz.


unlockUpdateRate

public void unlockUpdateRate()
Unlocks the update rate (the rate is set to 60Hz by default). Being velocities are generally constant regardless of the update rate, BUT if the update can be calculated quickly enough, objects may freeze because the update is faster than the smallest unit of time the computer can record. Use with caution.


draw

public void draw()

getPostOffice

public PostOffice getPostOffice()