Compositor Framework

From Multiverse

Particle Scripts

Syntax  •  Attributes  •  Emitters  •  Affectors

Material Scripts

Techniques  •  Texture Units  •  Passes  •  Vertex and Fragment Programs  •  Calling Vertex and Fragment Programs  •  Copying Materials

Compositor Framework

Compositor Scripts  •  Compositor Techniques  •  Compositor Target Passes  •  Compositor Passes

Shaders

Writing Custom Shaders  •  Built-in Shaders  •  Troubleshooting

Client Scripting

Overview  •  Coordinated Effects  •  Fireball Example  •  Terrain Decals  •  Compositors  •  About Shadows  •  Client Animation System  •  Creating Your Own Animations  •  Scripting Avatar Appearance

Reference

Client Scripting API  •  Client Commands

Contents 1 Introduction 1.1 Sampleworld compositor examples 1.2 Adding a compositor to a world 1.2.1 Enabling a compositor at startup 2 Defining a compositor class 2.1 Registering a compositor class 2.2 Applying a compositor 3 Advanced compositors

Introduction

The compositor framework allows you to apply shader-based filters (compositors) to a scene, to create special effects such as motion blur, heat vision, or high dynamic range lighting. A compositor is defined by a compositor script. Like material and particle scripts, Multiverse compositor scripts are based on OGRE. For detailed information, see:

• Compositor Scripts
• Compositor Techniques
• Compositor Target Passes
• Compositor Passes

For information on the Client scripting API Compositor object, see Compositor.

Sampleworld compositor examples

Sampleworld contains a set of "built-in" compositors and a key binding to demonstrate them. In Sampleworld, press Ctrl-Alt-C to cycle through all the built-in compositors. Pressing this key sequence calls the compositor class defined in Scripts\TestCompositor.py script.

The compositor scripts are defined in \Materials\Examples.compositor:

• BlackAndWhite - displays the scene in black and white rather than color.
• Bloom - "spreads out" light sources by multiplying the screen image (lighten lighter areas and darken darker areas), blurring the image, and drawing it over top of the original image. For a general description of the bloom effect, see Bloom (shader effect).
• Embossed
• Gaussian Blur - blurs an image using a Gaussian function, typically to reduce image noise and reduce detail. The visual effect is a smooth blur resembling that of viewing the image through a translucent screen.
• Glass - makes a "wavy" effect.
• HDR - high dynamic range lighting effect.
• Heat Vision - simulates an infrared vision device that displays thermal emissions rather than visual wavelengths.
• Invert - inverts the image's dark and light areas.
• Laplace
• Motion Blur - blurs any movement.
• Old Movie - simulates an old movie image.
• Old TV - simulates an old TV image.
• Posterize - replaces regions with continuous gradation of tone with several regions of fewer tones, resulting in an abrupt change from one tone to another. This creates an effect similar to that of a simple graphic poster.
• Sharpen Edges
• Tiling

Adding a compositor to a world

To add a compositor to a world:

1. Add the compositor script (with file extension .compositor) to the world's asset repository in the materials directory. For example, Sampleworld had Examples.compositor.
2. Create a Python class that invokes the compositor, and put the Python file in the world's asset repository in the Scripts directory. For example, Sampleworld has TestCompositor.py, that cycles through several different compositors.
3. Import the compositor script in Scripts\Startup.py. For example, Sampleworld has

   import TestCompositor
   

4. Define a way for the user to activate the compositor by calling the World.InvokeEffect() method. For example, Sampleworld defines a key binding (in Bindings.xml) as follows:

    <Binding name="TESTCOMPOSITORS" header="ACTIONS">
     ClientAPI.World.InvokeEffect("TestCompositorEffect", ClientAPI.GetLocalOID(), {})
    </Binding>
   

   <li> To associate the key binding with a key sequence, in bindings.txt add the following:

   ALT-CTRL-C TESTCOMPOSITORS

Enabling a compositor at startup

To automatically add a compositor to at startup, modify you asset repository Scripts\Startup.py to change the WorldInitHandler method, for example:

# This function is an event handler that runs when the world has been initialized.
def WorldInitHandler(sender, args):
    CurrentCompositor = 'Bloom'
    compositor = ClientAPI.Compositor.Compositor(CurrentCompositor)
    compositor.Enabled = True
    ClientAPI.Write('Activating compositor: ' + CurrentCompositor)

Defining a compositor class

To create a compositor script, define a Python class with:

• a class constructor
• an ExecuteEffect() method.

In a future release, you will also be able to define:

• an UpdateEffect() method.
• a CancelEffect() method.

See the example in Sampelworld Scripts\TestCompositor.py.

Registering a compositor class

To use a compositor, you must register it with the World.RegisterEffect() method with a string name of the compositor and the class that implements the compositor.

For example, the following line registers the test compositor:

ClientAPI.World.RegisterEffect("TestCompositorEffect", TestCompositorEffect)

Applying a compositor

To apply a compositor, create a compositor object, and set its Enabled property to True, for example:

  compositorEffect = Compositor.Compositor("BlackAndWhite")
  compositorEffect.Enabled = True

Advanced compositors

Some advanced compositors require additional code to be executed to set up parameters that requires you to set up a custom listener. Sampleworld includes several examples of advanced compositors in the GpuPrograms directory:

• Heat vision
• GaussianBlur
• HDR

For example, the heat vision compositor uses a pass with an identifier. This identifier allows the HeatVisionListener class to identify the passes for which it must add custom parameters. The custom parameters that are set up for use by the shader are depth_modulator and random_fractions.

  compositorEffect = Compositor.Compositor("Heat Vision")
  Compositor.SetupHeatVisionListener(compositorEffect)
  compositorEffect.Enabled = True

Similarly:

• To enable: GaussianBlur, use ClientAPI.Compositor.SetupGaussianListener(compositor)
• To enable SetupHDRListener, use ClientAPI.Compositor.SetupHDRListener(compositor)

NOTE: The three custom listener functions, SetupHeatVisionListener(), SetupGaussianListener(), and SetupHDRListener() are currently part of the Client API Compositor object, but they require the compositor script and program in the Sampleworld asset repository. In the future, they will be moved out of the Client API.