3.1   Interfaces

The module miru.imiru contains all the interfaces used by miru. An explanation of what interfaces do is outside the scope of this document, but briefly, an interface documents the expected behavior of a component separately from the implementation. Since interfaces are actually code, they can also be used to verify implementation correctness in unit tests, and adapt arbiraty objects to an interface at runtime. Many classes in miru implement interfaces imported from miru.imiru, and in those instances you should peruse the documentation - if it exists ;) - on the interface as opposed to the concrete implementation. For example, miru.environment.Environment implements imiru.IEnvironment:

class Environment(object):
    implements(IEnvironment)

3.2   The Environment Singleton

Behold, the singleton anti-pattern! --Also Sproch Zarahustra

The environment class provides a global singleton which can be used to reference many objects that often need to be queried on a global level. Exposed attributes are documented in IEnvironment and include:

• window: The pyglet.window.Window created for the application
• objects: Objects added to the world
• handle: Mouse or generic device handle
• camera: The current camera used for rendering the 3d scene

The env object also provides a simple interface for adding and removing objects. To add an object:

from miru.environment import env
env.addobj(obj)

To remove and object:

env.delobj(obj)

3.3   Objects and Drawables

from miru.mesh import newObject, Sphere

sphere = newObject(Sphere, radius=0.5)
env.addobj(sphere)

sphere.pos += (0,Y,0)

sphere.angle += (0,0,Z)

env.delobj(sphere)

def loadObj(filename, flip_normals=False, interleave=True):
    from miru.tools import obj
    mesh = _loaded_meshes.get(filename)
    if mesh is not None:
        return Object(mesh)
    parser = obj.ObjParser(filename, flip_normals=flip_normals)
    f,d,data = parser.parse()
    mesh = obj2mesh(f, data, interleave=interleave)
    _loaded_meshes[filename] = mesh
    return Object(mesh)

>>> o = newObject(Sphere, radius=2)
>>> o
<miru.mesh.Object at 89d254c <miru.mesh.Sphere object at 0xb789da6c>>
>>> o.drawable
<miru.mesh.Sphere object at 0xb789da6c>
>>> from miru.imiru import IWorldObject # Adapting to IWorldObject provider
>>> IWorldObject(o) == o.drawable
True

from miru.mesh import Group, Sphere, newObject
s1 = newObject(Sphere)
s2 = newObject(Sphere)
s2.pos = (1,0,0)
s3 = newObject(Sphere)
s3.pos = (2,0,0)
group = Group(s1,s2,s3)
env.addobj(group)

group = Group(s1,s2,s3,compile=True)
env.addobj(group)

head = loadObj('head.obj', compile=False)
hat = loadObj('hat.obj', compile=False)
group = Group(head, hat, compile=True)
env.addobj(group)

3.4   Cameras and Lights

from miru.camera import Camera
camera = Camera(pos=(1,4,5), wireframe=True)
env.cameras['secondary'] = camera

camera.objects = env.camera.objects # link visible objects between cameras
env.camera = env.cameras['secondary']

from miru.camera import LightGroup, PositionalLight
lights = LightGroup([PositionalLight(), PositionalLight((2,3,4))])
env.camera.lights = lights

raceCar = loadObj('racecar.obj')
env.camera.track_target = raceCar

env.camera.track_target = None

env.camera.rotation_mode = Camera.ORBIT_MODE

env.camera.rotation_mode = Camera.ROTATION_MODE

3.4.3   Lighting

The are two classes of lights currently supported by Miru:

• miru.camera.DirectionalLight
• miru.camera.PositionalLight

A directional light acts as a light placed at an inifite distance from the visible object, providing ambient light with a constant from it's origin. A positional light behaves similar to a spot light.

Debugging enabled on positional lights placed in a scene

A positional light with a spot cutoff in the range [0,90] will have a cone-shaped light with an angle given by the cutoff value:

spotlight = camera.PositionalLight(pos=(0,2,0), spot_cutoff=25,
    spot_exponent=10, kq=0.1)
env.camera.lights.append(spotlight)

You can enable debugging on a positional light to see it's location in the scene.

>>> pl = env.camera.lights[0] # assuming the first light is a positional light
>>> pl.debug = 1

from miru import camera
orthoproj = camera.OrthographicProjection()
env.camera.projection = orthoproj

3.5   Tracks

Position and orientation tracks be defined between objects that implement miru.imiru.IPostional [2] .

from miru.track import PosTrack
leg = loadObj('leg.obj')
foot = loadObj('foot.obj')
foot.pos -= (0,2,0)
track = PosTrack(foot, leg) # Set up the Positional Track

>>> tuple(leg.pos)
(0, 0, 0)
>>> tuple(foot.pos)
(0, -2, 0)
>>> leg.pos += (1,2,3)
>>> tuple(leg.pos)
(1, 2, 3)
>>> tuple(foot.pos)
(1, 0, 3)

knee = loadObj('knee.obj')
knee.pos = leg.pos - (0,1,0)
track2 = PosTrack(knee, leg)

3.5.3   Camera Tracks

Tracks, can also be used to make a camera follow an object in the world, which can be very usefule for games. You can define a PosTrack as defined above or even use a custom side-scroller track which will only follow the tracked object as it reaches the screen boundary:

from miru.track import SSCameraTrack
avatar = loadObj('avatar.obj')
SSCameraTrack(env.camera, avatar, env.window)

You can also compose tracks. With a slight modification to the above code example we can make our camera also follow the avatar along the z-axis:

from miru.track import SSCameraTrack
avatar = loadObj('avatar.obj')
SSCameraTrack(env.camera, avatar, env.window)
PosTrack(env.camera, avatar, axes=(0,0,1))

The camera allows the ball to move freely in the scene and then follow it as it reaches the edge of the viewport.

Caution!

Do not be confused by the track_target attribute of miru.camera.Camera. While similar in concept (and in terminology) - track_target does not use a Track. Expect wacky things to occur (for now), if you set track_target on a camera and also set up tracks as described in this section.

>>> from miru.track import gettracks
>>> gettracks(tracked=avatar)
[...]

>>> gettracks(tracker=env.camera)
[...]

>>> track.deactivate()
>>> leg.pos += (123,45,67)
>>> foot.pos
(1,0,3)

>>> from miru.track import deactivate
>>> deactivate(tracked=avatar)
>>> gettracks(tracked=avatar)
[]

>>> deactivate(tracker=env.camera)
>>> gettracks(tracker=env.camera)
[]

3.6   The On Screen Display (OSD)

miru.osd provides an OSD class will renders (by default) after objects in the 3D world are rendered. Objects which need to be rendered on screen and not affected by world transformations or lighting can be added to the OSD. For example, we can take an FPS display provided by pyglet and place this in the OSD:

from pyglet import clock
from pyglet import font
clock_display = clock.ClockDisplay(font=font.load('',18), color=(0.,1.,0.,0.5))
env.osd.addobj(clock_display)

The Python interactive console mentioned above is also OSD for display.

4.1   Effects

miru.effects provides two simple effects which can be added to a scene:

• miru.effects.Reflection
• miru.effects.Fog

Effects are enabled by added them to the effects list on a Camera instance. To enable reflection over a plane:

from miru.mesh import CheckerBoard
from miru import effects

cb = newObject(CheckerBoard, even_color=(0.1,0.0,0.0,0.8), odd_color=(0,0.05,0,0.8))
refl = effects.Reflection(ground=cb, camera=env.camera)

env.camera.effects.append(refl)

Effects can also be combined. The following example demostrates a Reflection effect following by Fog application:

fog = effects.Fog(density=0.075, color=(0.65,0.9,0.75,0.5), equation=effects.Fog.EQ_EXP)
cb = newObject(CheckerBoard, even_color=(0.1,0.0,0.0,0.8), odd_color=(0,0.05,0,0.8))
refl = effects.Reflection(ground=cb, camera=env.camera)
env.camera.effects.extend([refl, fog])

Reflection and Fog are added to a scene to create the effect of objects reflecting over a still body of water.

4.2   Scene Culling

TODO

Hierarchical scene culling with an Octree data structure.

4.3   Render Stages

In the introduction we mentioned that Miru supports render state grouping but we haven't explained yet what that actually means. We've also deferred explanation of what occurs in the render method on an environment. Hopefully this section will explain to you what render stages are, and why they're important in any 3D application.

OpenGL is a state machine, and while it can operate very quickly with modern graphics hardware, tacking on too much state in single render cycle can still be detrimental to performance. A necessary optimization is to sort objects drawn in a scene by their state based on enabled attributes: depth testing, lighting, etc. Enabling and disabling such attributes per object rendered is unacceptable.

The interface miru.imiru.IRenderStage specifies a grouping of objects which should all be rendered in the same driver state. For example, when drawing 3D meshes in a scene, certain key attributes should be applied for each object:

• The Polygon mode must be set according to the desired effect (filled quads and triangles or outlines only)
• Lighting should be enabled
• To avoid the complications of manual z-buffer sorting, depth testing should be enabled

On the other hand, we might want to draw debugging objects as well in the 3D scene with an entirely different set of required attributes. Mixing such objects together with the former in an arbitrary order means we'll have to enable/disable attributes many more times than we need to - that is, optimially once per attribute per frame.

By default, the Environment object is initialized with 4 rendering stages in the following order:

• miru.imiru.IWorldRenderStage (default implementation: miru.camera.Camera)
• miru.imiru.IDebuggingRenderStage (default implementation: miru.camera.DebugView)
• miru.imiru.IBlittableRenderStage (default implementation: miru.camera.BlittableView)
• miru.imiru.IOSDRenderStage (default implementation: miru.osd.OSD)

All four render stages together in harmony.

You are able, however, to set the order as you please, as well as declare (via an interface) and implement new rendering stages to plug into the pipeline. Or, you can override previously declared interfaces with a new implementation. First, let's see how to reorder the render stage pipeline:

>>> from miru.imiru import *
>>> from miru.environment import env
>>> env.setRenderStages(IOSDRenderStage, IWorldRenderStage, IDebuggingRenderStage, IBlittableRenderStage)

Now the OSD appears behind visible objects in the scene!

You can also change the implementation of a render stage by overriding the registered implementation and resetting the render stages on the environment:

>>> from thirdparty import OSD2
>>> osd2 = OSD2()
>>> from miru.components import registerUtility
>>> registerUtility(IOSDRenderStage, osd2, override=True)
>>> env.osd = osd2
>>> env.setRenderStages(IWorldRenderStage, IOSDRenderStage) # Reset with only 2 render stages

We can also query the component providing a render stage on the environment:

>>> env.renderStage(IWorldRenderStage)
<miru.camera.Camera object at 0x87b982c>

Declaring a render stage is also simple - just create a new interface:

from miru.imiru import IRenderStage
from zope.interface import implements

class IFragmentShaderStage(IRenderStage):
    """Render stage for GLSL fragment shader
    """

class FragmentShaderStage:
    implements(IFragmentShaderStage)

    def __init__(self):
        self.objects = []

    def render(self):
        pass # implement me ;)

    def addobj(self, obj):
        self.objects.append(obj)

    def delobj(self, obj):
        self.objects.remove(obj)

Now we'll register the new render stage and set the render stages on our environment as desired:

>>> from miru.components import registerUtility
>>> registerUtility(IFragmentShaderStage, FragmentShaderStage())
>>> env.setRenderStages(IWorldRenderStage, IFragmentShaderStage, IOSDRenderStage)

Drawable objects in miru provide an attribure renderStages which gives a list of render stage interfaces to which the object belongs. This is generally defined first as a class attribute giving new object instances a sensible default. miru.mesh.Mesh, for example, defines renderStages as (imiru.IWorldRenderStage,). There is a simple way to override this if you wish to place an object in a non-default render stage:

from pyglet import image
from miru.mesh import ImageWrapper
from miru.environment import env

img = image.load('poster.png')
imgw = newObject(ImageWrapper, img).inRenderStages(IWorldRenderStage)
env.addobj(imgw)

Instances of ImageWrapper generally belong to the IBlittableRenderStage which disable depth testing and lighting. In the above example we've used the inRenderStages method on Object to declare that the underlying ImageWrapper instance should be drawn in the IWorldRenderStage along with other lit objects.