Example Usage

One of the simplest possible reasonable component would like something like this:

class Point(OpenGLComponent):
    def draw(self):
        glBegin(GL_POINTS)
        glColor(1,0,0)
        glVertex(0,0,0)
        glEnd()

A more complex component that changes colour in response to messages sent to its "colour" inbox and reacts to mouse clicks by rotationg slightly:

class ChangingColourQuad(OpenGLComponent):
    def setup(self):
        self.colour = (0.5,1.0,0.5)
        self.addInbox("colour")
        self.addListenEvents([pygame.MOUSEBUTTONDOWN])

    def draw(self):
        glBegin(GL_QUADS)
        glColor(*self.colour)
        glVertex(-1, 1, 0)
        glVertex(1, 1, 0)
        glVertex(1, -1, 0)
        glVertex(-1, -1, 0)
        glEnd()

    def handleEvents(self):
        while self.dataReady("events"):
            event = self.recv("events")
            if event.type == pygame.MOUSEBUTTONDOWN and self.identifier in event.hitobjects:
                self.rotation += Vector(0,0,10)
                self.rotation %= 360

    def frame(self):
        while self.dataReady("colour"):
            self.colour = self.recv("colour")
            self.redraw()

How does it work?

OpenGLComponent provides functionality to display and move objects in OpenGL as well as to process events. The component registers at the OpenGL display service, draws its contens to a displaylist and applies its transformations to a Transform object. The display list id and the Transform objects are continuosly transfered to the display service when updated.

For movement several inboxes are provided. The messages sent to these boxes are collected and applied automatically. The inboxes and expected messages are:

• position -- position triples (x,y,z)
• rotation -- rotation triples (x,y,z)
• scaling -- scaling triples (x,y,z)
• rel_position -- relative position triples (x,y,z)
• rel_rotation -- relative rotation triples (x,y,z)
• rel_scaling -- relative scaling triples (x,y,z)

When an OpenGLComponent gets moved, it also provides feedback about its movement. This feedback is sent to the following outboxes:

• position -- position triples (x,y,z)
• rotation -- rotation triples (x,y,z)
• scaling -- scaling triples (x,y,z)

OpenGLComponent is designed to get subclassed by opengl components. Using it as base class has the advantage not having to worry about interaction with the OpenGl display service. To add functionality, the following methods are provided to be overridden:

• setup() -- set up the component
• draw() -- draw content using OpenGL
• handleEvents() -- handle input events ("events" inbox)
• frame() -- called every frame, to add additional functionality

Stubs method are provided, so missing these out does not result in broken code. The methods get called from the main method, the following code shows in which order:

def main(self):
    # create and send display request
    ...
    # setup function from derived objects
    self.setup()
    ...
    # inital apply trasformations
    self.applyTransforms() # generates and sends a Transform object
    # initial draw to display list
    self.redraw() # calls draw and saves it to a displaylist

    ...
    while 1:
        yield 1
        self.applyTransforms()
        self.handleMovement()
        # handle events function from derived objects
        self.handleEvents()
        # frame function from derived objects
        self.frame()

As can be seen here, there is no invocation of draw in the main loop. It is only called once to generate a displaylist which then gets send to the display service. This is the normal situation with static 3D objects. If you want to create a dynamic object, e.g. which changes e.g. its geometry or colour (see second example above), you need to call the redraw() method whenever changes happen.

If you need to override the __init__() method, e.g. to get initialisation parameters, make sure to pass on all keyword arguments to __init__(...) of the superclass, e.g.:

def __init__(self, **argd):
    super(ClassName, self).__init__(**argd)
    # get an initialisation parameter
    myparam = argd.get("myparam", defaultvalue)

The following methods are provided to be used by inherited objects:

• redraw() -- Call draw() and save its actions to a displaylist. Send it as update request to the display service. Don't call this method from within draw()!
• addListenEvents(list of events) -- Request reception of a list of events
• removeListenEvents(list of events) -- Stop reveiving events

The are inteded to simplify component handling. For detailed description see their documentation.

Every OpenGLComponent has its own pygame Clock object. It is used to measure the time between frames. The value gets stored in self.frametime in seconds and can be used by derived components to make movement time- based rather than frame-based. For example to rotate 3 degrees per second you would do something like:

self.rotation.y += 3.0*self.frametime

OpenGLComponent components terminate if a producerFinished or shutdownMicroprocess message is received on their "control" inbox. The received message is also forwarded to the "signal" outbox. Upon termination, this component does not unbind itself from the OpenGLDisplay service and does not free any requested resources.

class OpenGLComponent(Axon.AdaptiveCommsComponent.AdaptiveCommsComponent)

OpenGLComponent(...) -> create a new OpenGL component (not very useful though; it is rather designed to inherit from).

This components implements the interaction with the OpenGLDisplay service that is needed to setup, draw and move an object using OpenGL.

Keyword arguments:

• size -- three dimensional size of component (default=(0,0,0))
• rotation -- rotation of component around (x,y,z) axis (defaul=(0,0,0))
• scaling -- scaling along the (x,y,z) axis (default=(1,1,1))
• position -- three dimensional position (default=(0,0,0))
• name -- name of component (mostly for debugging, default="nameless")

while self.dataReady("events"):
    event = self.recv("events")
    # handle event ...