modul8 documentation

TA

BL

E O

F C

ON

TE

NT

S

© Copyright 2005 GarageCUBE, Schmid, Edelstein, SNC – All rights reservedModul8 - Documentation V. 2.0

MAIN PANEL

01Main panel

VERSION 2.5


�

Table of conTenTsInTroducTIon..............................................................................................................8

requirements..........................................................................................................10Installation...............................................................................................................10

authorizing Modul8...............................................................................................10authorizing Modul8 offline.....................................................................................10deauthorizing Modul8...........................................................................................10

The Modul8 Model..................................................................................................11Panels......................................................................................................................12Getting started........................................................................................................13summary.................................................................................................................15

MedIa.............................................................................................................................16overview..................................................................................................................16The Media Panel.....................................................................................................16special Media..........................................................................................................17supported Media....................................................................................................17Images.....................................................................................................................18Movies.....................................................................................................................18Transparency...........................................................................................................18Performance...........................................................................................................18sound Playback......................................................................................................19Memory....................................................................................................................20The dynamic Media................................................................................................20summary.................................................................................................................20

PrevIew........................................................................................................................21overview..................................................................................................................21Grid Mode................................................................................................................21layer Mode.............................................................................................................21Group Inv. Mode......................................................................................................21Group a/b Mode.....................................................................................................21output Mode...........................................................................................................21out Mix Mode..........................................................................................................22summary.................................................................................................................23

sInGle ouTPuT...........................................................................................................24overview..................................................................................................................24full screen Mode....................................................................................................24single Monitor system...........................................................................................24summary.................................................................................................................24

MulTI-ProJecTIon.....................................................................................................25Introduction.............................................................................................................25basic Principles......................................................................................................25Hardware configuration.........................................................................................25

computer.............................................................................................................25

VERSION 2.5

TA

BL

E O

F C

ON

TE

NT

S


MAIN PANEL

01Main panel


�

Graphic cards and the video outputs......................................................................25system configuration.............................................................................................25

warning...............................................................................................................26activating the advanced mode..............................................................................26The advanced output setup...................................................................................27representation area...............................................................................................27Managing the clips.................................................................................................28

creating and deleting clips.....................................................................................28clip selection.......................................................................................................28Position and size of the clip in the representation space............................................28seeing the clips in the preview...............................................................................28clip ratio..............................................................................................................28

routing Table..........................................................................................................28Managing your setup..............................................................................................29annex.......................................................................................................................29Matrox dualHead�Go and TripleHead�go............................................................29

layer.............................................................................................................................32overview..................................................................................................................32Managing layers....................................................................................................32working with a/b layer groups............................................................................33Play..........................................................................................................................34

speed..................................................................................................................34loop Mode...........................................................................................................34scratch................................................................................................................35

Movie options.........................................................................................................35setting movie entry/exit points...............................................................................35sound volume......................................................................................................35

Transition.................................................................................................................36Transform................................................................................................................36

scale...................................................................................................................36rotation...............................................................................................................37

Post-colorize...........................................................................................................37Pixel fX....................................................................................................................38

saturation............................................................................................................38lightness.............................................................................................................38contrast..............................................................................................................38luma key / color key.............................................................................................38noise...................................................................................................................39blur.....................................................................................................................39

animation effects...................................................................................................40animation curves..................................................................................................40auto Move............................................................................................................40auto scale...........................................................................................................40auto color............................................................................................................40auto rotate..........................................................................................................41

The transformers....................................................................................................42

VERSION 2.5

TA

BL

E O

F C

ON

TE

NT

S


MAIN PANEL

01Main panel


�

Matrix..................................................................................................................42Patch...................................................................................................................43Particle emitter.....................................................................................................44

layer local logical record...................................................................................45layer sets................................................................................................................45summary.................................................................................................................46

MasTer.........................................................................................................................47overview..................................................................................................................47speed.......................................................................................................................47scale........................................................................................................................47alpha-channel........................................................................................................47Trace Mode..............................................................................................................47Quick effects...........................................................................................................48background color..................................................................................................48Invert output color.................................................................................................48output add color....................................................................................................48sound level.............................................................................................................48Global logical record............................................................................................48summary.................................................................................................................48

caPTure.......................................................................................................................49overview..................................................................................................................49sound capture........................................................................................................49video capture.........................................................................................................50summary.................................................................................................................50

savInG your ProJecT..............................................................................................51overview..................................................................................................................51Media.......................................................................................................................51Midi and keyboard..................................................................................................51summary.................................................................................................................51

MIdI and keyboard..................................................................................................52overview..................................................................................................................52default configuration.............................................................................................52configuring The keyboard.....................................................................................53configuring Midi.....................................................................................................53contextual Midi / keyboard mapping...................................................................53summary.................................................................................................................54

recordInG and renderInG...................................................................................55overview..................................................................................................................55The logical record................................................................................................55record To disk........................................................................................................56summary.................................................................................................................56

VERSION 2.5

TA

BL

E O

F C

ON

TE

NT

S


MAIN PANEL

01Main panel


�

Modules......................................................................................................................57overview..................................................................................................................57using modules........................................................................................................57downloading and installing new modules...........................................................57Managing your modules .......................................................................................58

sTandard Modules..................................................................................................59layer........................................................................................................................59all / Master.............................................................................................................59Global.......................................................................................................................59bPM (Global)........................................................................................................59rouTer (MasTer) and rouTer (layer)..........................................................60Mask (Global).....................................................................................................61cenTer (layer)....................................................................................................63neTwork (Global).............................................................................................64PreseT (layer).....................................................................................................65PreseT defaulT (layer)....................................................................................66scraTcH (layer)..................................................................................................66slIde sHow (layer)............................................................................................67fIlTer (layer).......................................................................................................69TeXT (layer)..........................................................................................................70TeXT subTITle (layer).......................................................................................71TeXT cHanGe (layer).........................................................................................72TIMe and daTe (layer).......................................................................................72counT down (layer).........................................................................................73MovIe TIMe (layer).............................................................................................73crossfader (MasTer).......................................................................................74sHake (all)...........................................................................................................75randoM croP (layer).......................................................................................75MovIe randoM fraMe (layer)........................................................................76PaInTer (layer)...................................................................................................77PosT colorIZe PIcker (layer).......................................................................79cHroMakey (layer)...........................................................................................80creating modules...................................................................................................81layer contextual Module.......................................................................................81Interacting with Modul8.........................................................................................82using the keywords................................................................................................82The keyword families.............................................................................................83The user-interface builder.....................................................................................84The global attributes..............................................................................................85The controls............................................................................................................85

The slider.............................................................................................................85The knobs............................................................................................................85The buttons..........................................................................................................85The media buttons................................................................................................86The color pickers..................................................................................................86The �d pad...........................................................................................................87

VERSION 2.5

TA

BL

E O

F C

ON

TE

NT

S


MAIN PANEL

01Main panel


�

The draw view......................................................................................................87The captions........................................................................................................87Text and numeric fields..........................................................................................87The text list..........................................................................................................87shapes................................................................................................................87Tools...................................................................................................................88

connecting controls to Modul8 keywords...........................................................88a simple module examples....................................................................................89

a colorize module.................................................................................................89a pad effect module..............................................................................................93

scripting..................................................................................................................96a brief introduction to Python...............................................................................97

conditions...........................................................................................................98Integer.................................................................................................................98floating-point.......................................................................................................99list......................................................................................................................99dictionary............................................................................................................99operators..........................................................................................................100comments.........................................................................................................100Packages...........................................................................................................100

The scripting environment...................................................................................101The Modul8 main functions.................................................................................102The Module functions...........................................................................................102

setvalue/getvalue...............................................................................................102setdefaults / getdefaults.....................................................................................103setattribute / getattribute....................................................................................103getshareddictionary............................................................................................103flushallcontrols..................................................................................................103sendMessageToallInstances................................................................................103showGroup / hideGroup.......................................................................................104

The Modul8 advanced functions.........................................................................104sending midi messages.......................................................................................104hsbTorgb / rgbToHsb..........................................................................................104setfilters / getfiltersdesc....................................................................................104

The script types....................................................................................................105Init()...................................................................................................................105Messageevent(msg,param)..................................................................................105directevent(type,param)......................................................................................106keywordevent(keyword,param)............................................................................106Periodicalevent(elapsed)......................................................................................106Pauseevent(paused)............................................................................................107finish()...............................................................................................................107serialize(outdict)/deserialize(indict)......................................................................107

Module serialization.............................................................................................107The module draw view control............................................................................108sharing your modules online...............................................................................110

VERSION 2.5

TA

BL

E O

F C

ON

TE

NT

S


MAIN PANEL

01Main panel


�

suPPorT, coMMunITy and conTacTs...............................................................112

abouT..........................................................................................................................113

INT

RO

DU

CT

ION

MAIN PANEL

01Main panel


VERSION 2.5

8

InTroducTIon

Welcome to Modul8! Modul8 is a revolutionary MacOS X application designed for real time video mixing and compositing. It has been designed for VJs and live performers.

Unlike.most.of.the.other.video.mixers,.Modul8.really.allows.you.to.create.the.composition.you.want.instead of being stuck with a predefined set of filters. And by composition, we mean both spatial and time-related.composition:.In.Modul8,.you.can.move,.rotate,.scale.your.original.media.just.like.in.a.simple.image.editor.-.but.all.in.real.time.

Modul8 supports almost all quicktime codecs, flash animation and almost all the image formats you can think about. Simply drag and drop your files to the media panel. They are ready to be mixed. Modul8 works in full resolution, no scale down is done. The output resolution can be in pal, ntsc, svga, xga or higher. The same is true for your movies: not a single pixel is lost. Modul8 renders your media as you have compressed.it,.i.e..with.the.maximum.available.quality.and.highest.possible.resolution.

To reach this kind of performance, we push your hardware and the OS to the limit: The full rendering is done through the GPU of your graphic card; each pixel modifier has been altivec optimized and the whole.architecture.of.the.software.is.fully.multi-threaded..Everything.has.been.done.to.lower.the.latency.as.much.as.possible.at.every.levels.of.the.application..For.example,.the.movie.swapping.and.looping.are.pre-buffered.to.avoid.latency.

Modul8. is.able. to.manage.up. to.10.different. layers.each.one.having. its.own.settings.and.media..Layers.can.be.re-ordered.at.any.time.with.a.simple.drag.and.drop..Layers.can.also.be.grouped.in.two.compositions A/B allowing you to work on an animation while you are projecting another one. Full per pixel.transparency.is.computed.between.the.layers.allowing.you.to.obtain.an.incredible.high.quality.mix.of images. Because we know how important the transparency is in compositing, Modul8 is able to read full alpha channels from the media. We also offer five different luma-key functions for media that do not support.an.alpha.channel.

Modul8.works.in.full.32.bits.colors,.three.channels.for.red,.green.and.blue,.plus.the.alpha.channel..At any time, you can modulate the channels (both color and transparency) of your media without slowing down your composition. Altivec optimized filters allow you to change the contrast, the saturation, the brightness in both positive and negative forms. And of course standard filtering like ultra fast blur and noise filters are also directly integrated in the main user interface.

Since. the.V2.0,.Modul8. includes.an.advanced.transformer.mechanism.that.allows.the.creation.of.advanced.three-dimensional.objects.from.your.2D.media:.a.new.matrix.mechanism.for.tiling.your.video.source. that. supports.3D.extrusion;.an.advanced. real. time.patch.system. that. lets. you.create.complex.dynamic. 3D. shapes. by. combining. primitive,. displacement. mapping,. sound. waves;. and. a. 3D. particle.engine.designed.for.real.time.manipulation.

Modul8 supports a preview panel that can be used at the same time than the final output. This panel lets you see the output and much more: you can display hidden layers or group to prepare the final composition before it is sent to the displayed output (just like with DJ tables). This preview panel can also be.used.to.move.your.layers.in.space.with.a.simple.mouse.drag.

Modul8 supports direct keyboard and full midi connectivity. The whole user-interface can be configured to react to midi and/or to keyboard. Modul8 automatically detects and links your external midi controller to the user-interface. All you have to do is move your external fader, or your button, and Modul8 will.interpret.the.midi.message.and.link.it.to.the.button.you.have.selected..You.don’t.have.to.know.about.midi.messages..Modul8.is.also.able.to.react.directly.to.sound.input:.simply.plug.a.microphone.to.your.machine.and.link.the.sound.input.to.the.desired.effect.

Modul8 is also fully extensible with the module system introduced in the V2.0. An advanced user-interface builder let you create your own windows and controls such as buttons, text fields and much

INT

RO

DU

CT

ION

MAIN PANEL

01Main panel

VERSION 2.5


�

more.with.a.simple.drag.and.drop...You.can.map.your.controls.to.Modul8.functionalities.with.a.simple.configuration panel. And for those who want to go further, it is fully scriptable. An integrated environment allows.you.write.Python.scripts.straight.from.the.inside.of.the.application.without.even.having.to.stop.your.animation. An online module library allows Modul8 users to share their modules. This flexible architecture opens Modul8 to full customization, perfect for advanced installation and performances.

This documentation is a complete reference of Modul8. You will find a description of all the components of.the.application..

OV

ER

VIE

W

MAIN PANEL

01Main panel


VERSION 2.5

10

requirements

On the software side, Modul8 2.5 requires the MacOS version 10.4 (Tiger) or higher (10.3.9 users can still use Modul8 2.0.3) and quicktime version 7.1.3 or higher to run.

On the hardware side, a G4 processor or higher is required. Because Modul8 uses the GPU of your video card for the rendering, having a good video card is also critical. An ATI Radeon or an NVidia Geforce card with at least 32Mbytes of Vram is a minimal configuration to obtain acceptable performances; a 64Mbytes.video.card.is.highly.recommended.

Multiprojection requires a Mac tower with PCI-Express and several graphic cards (depending of the number of output required). The maximum number of outputs today is eight (four dual-output graphic cards). Typically seven outputs, plus one reserved for the user-interface.

It is also possible to use a device such as the Matrox DualHead or TripleHead to create multi-projection with Modul8 and the PowerBook. However only linear side-by-side projections are supported with this configuration.

Installation

To install Modul8 you simply have to drag the Modul8 folder to your application folder. Before using Modul8 an online registration is required. The standard Modul8 license allows you to install Modul8 on two machines simultaneously (different users on the same machines are not counted as different machines).

authorizing Modul8

To authorize Modul8 on a machine, simply launch the application. If you have an Internet connection, the procedure is pretty straightforward. Simply fill the form and enter your serial number. Modul8 will connect to a server to validate your machine. Once it is done, you don’t need Internet anymore to use Modul8. You can always have at least two machines authorized at the same time (and more if you have a site license). If you need to install a third machine, you have to deauthorize Modul8 on one of the other machines (see the “Deauthorizing Modul8” chapter).

authorizing Modul8 offline

Modul8 supports also an offline authorization process for those who need to install Modul8 on a machine.that.is.not.able.to.connect.to.the.Internet..Please.use.it.only.when.you.really.need.it,.because.it.is.a much more complicated process. To authorize offline, start Modul8 and select “Offline authorize”. Then fill the form. Modul8 will give you a challenge code. You need to keep a copy of this code (there is an option to save it as a text file). Then go to the specified URL on another machine and enter the challenge code.

A validation code will be returned. Restart Modul8 and enter the validation code to finish the authorization process. It is also possible to deauthorize a machine offline. See the next chapter.

deauthorizing Modul8

You need to deauthorize a computer when you need to install Modul8 on a new machine and you already have used the maximum number of registration authorized by your license. It is also important to deauthorize Modul8 if you sell or replace your machine.

To deauthorize a computer, simply select “Deauthorize” in the Modul8 menu. If your computer is connected to the Internet you only have to click on “Deauthorize”. Modul8 will connect to a server to remove.the.registration.of.your.machine..

It is also possible to deauthorize Modul8 offline. In this mode, Modul8 gives you a code that is saved to a text file. Then you need to use a machine that has Internet support to access the deauthorization URL and enter the code previously returned. It is important that you do this last step, because the deauthorization

OV

ER

VIE

W

MAIN PANEL

01Main panel


VERSION 2.5

11

process is not finished as long as the server has not unregistered your machine.

The Modul8 Model

Modul8 is based on a layer paradigm. Basically you create your composition by adding and removing layers. Each layer displays a media (a movie, an image, etc.) and applies spatial and time modifiers to the original media. All the layers are mixed together in order to generate the final image composition.

A layer is an infinite 3D space where the original media can be moved, scaled and rotated. In other words, the media can be moved along the axis of a layer and will not necessary fill the screen.

The selected layer is the one that you are currently editing. When a layer is selected, all its attributes are.displayed. in. the.user-interface..When.you.switch. to.another. layer. the.user-interface. is.updated. to.reflect the new layer attributes.

Layers can be used just as a flat list or they can be divided in two groups A/B. In the group mode, you have two compositions that can be edited individually. A cross-fader allows you to move smoothly from one group to another. This is pretty useful when you want to display a composition while you are editing another.one.

A composition of layers can be stored into layer sets. Only the selected layer set is rendered. These sets.can.be.used.to.jump.quickly.from.one.composition.to.another..Unlike.the.layer.stack,.each.layer.set.is completely independent from the others (you cannot visually mix two layer sets). A layer set is really a way.to.preset.or.to.store.a.full.composition.

A set of master controllers allows you to modify global attributes that are applied to the composition after.the.layers.have.been.mixed.

Finally, the last key entity is the media. A media represents a visual source that can be linked to a layer and finally rendered. Modul8 supports several kind of visual sources, like Flash 5 animation, QuickTime movie, simple image or video live stream. The medias are stored in an internal media bank that is manipulated through the media panel. A media can be imported to the media bank simply by dragging its file to the media panel.

Here is a simplified representation of the Modul8 rendering pipeline:

MEDIAS

Media linked to layers Apply effects andmix layers

Master effects

MovieImageMovieMovie...

LAYERS FINAL OUTPUT

MASTER

Layer 01Layer 02Layer 03Layer 04...

OV

ER

VIE

W

MAIN PANEL

01Main panel


VERSION 2.5

1�

Panels

The Modul8 user interface is divided into four panels:

01.The main panel: This is where you manage the layers and the master controllers.

0�.The output panel: This is where the final rendering is displayed. By default it is a resizable and moveable panel..It.can.also.be.redirected.to.a.full.screen.view.on.the.main.screen.or.on.a.secondary.screen.

0�.The preview panel: This panel is a preview of your composition. It can be used to move the active layer along the x/y axis and to preview your composition in several different ways.

0�.The media panel: This where you add and manage your media (movies, pictures, etc.).

01Main panel

0�output

0�Preview

0�Media

VERSION 2.5

OV

ER

VIE

W

MAIN PANEL

01Main panel


1�

Getting started

There are many different ways to work with Modul8. Typically, the first step is to prepare your media. It is a critical step because the size and the type of compression of the media have a great impact on the quality and the performance of Modul8. See the “Media” section for more information about media preparation.

Once your media are ready you can import them in Modul8. It is pretty straightforward to get your media in the application. Basically, you drag and drop them to the media panel. You can have up to 80 media stored in the media bank. The media panel is divided in five sections of four by four media slots. There is also a special section for predefined or internal media (like the video capture).

When.you.add.a.new.media,.Modul8.automatically.chooses.a.memory.strategy.for.you.in.order.to.obtain.the.best.possible.performance..If.your.media.is.small.enough,.it.will.be.entirely.stored.decompressed.in.memory..If.this.is.not.possible,.the.media.is.stored.compressed.in.memory..If.the.media.is.still.too.big,.it will be simply streamed from the file.

.Once the media have been imported you are ready to mix them. Modul8 is layer oriented. A media is

always.represented.through.a.layer.

1 The initial first layerAt the beginning, only one layer is present..You.can.see.it. in.the.layer.list.at.the.left.of.the.main.panel.

1

VERSION 2.5

OV

ER

VIE

W

MAIN PANEL

01Main panel


1�In.order.to.get.a.layer.to.display.a.media.you.have.to.link.them.together..Simply.selecting.a.layer.and.clicking.on.a.media.in.the.media.panel.does.this..You.can.also.use.midi.or.keyboard.shortcuts.to.manage.this operation. By default, the keys 1 to 9 (please note that is it not the keypad keys) are assigned to the first nine media. See the “Midi and Keyboard” section for more information regarding input configuration.

As soon as a media has been linked to a layer, it is displayed in the final output panel (unless the layer is hidden). The media is also automatically played in loop mode.

Changing the attributes of the layer is reflected in the final composition. For example, if you modify the Z knob in the rotation section, you can see your media rotating in real time. This is true of all the others Modul8 controllers. Every change updates immediately the final composition in real-time.

Some.layer.attributes.should.be.activated.before.they.are.applied.to.the.composition..For.example,.the “saturation” is not applied to the media before you enable it using its title button. However, the controls of the filters are not disabled even if the zone is deactivated. It allows you to prepare the filter before it affects the composition. This is also true of all the sections that have a title that can be activated (contrast, luma-key, auto move, etc.).

You won’t find a X/Y control in the layer attribute section. This is because you can directly move your layer.using.the.preview.window..Simply.click.on.the.grid.and.move.the.mouse.to.drag.your.layer.along.the.X/Y axis.

all the attributes of the selected layer are represented at the right of the layer list.

For. instance,. if. you. examine. the. rotation.section.of.the.transform.area,.you.will.see.three knobs: X, Y and Z. These controllers represent. the.current. rotation.angle.of. the.selected. layer.. When. you. select. another.layer, these knobs are updated to reflect the angle of the newly selected layer. This is.true.for.all.the.layer.attributes.displayed.beside.the.layer.list.

OV

ER

VIE

W

MAIN PANEL

01Main panel

VERSION 2.5


1�

The preview panel can also be used to see the full final output (it is pretty useful when your do a projection that you cannot see) or simply the current layer. The “output” mode allows you to see the full mix. The interesting feature of the “mix” mode is that it displays the layer in the preview panel even if it is hidden, allowing you to prepare a layer before it is sent to the final output. When you are working in A/B group mode, you can also see a specific group or simply the group that is not displayed in the output display using the “group inv” tab. This is the mode that you use when you want to work on a composition while you are displaying another one (See “Working with A/B layer groups” chapter).

.Finally you can use the master controllers to apply global modifiers to your composition. These

controllers are not layer related. They are applied to all the layers and/or after all the layers have been mixed.

For example, you can use the “speed” slider to change the movie time rate of all your playing movies instead.of.modifying.the.layers.one.by.one.

summary

In.this.chapter,.we.saw:.

• The minimum requirements to run Modul8• The different panels and their rules• A quick introduction to the different components of Modul8

The next chapters will examine in details all the functionalities of Modul8.

Simply click and drag your mouse in this zone to move your.layer.

ME

DIA

MAIN PANEL

01Main panel

VERSION 2.5


1�

MedIaoverview

In Modul8, any visual source that can be represented by a layer is considered as a media. This includes movies, Flash animations, simple images, text and video capture. Some media are files while some others may be dynamic media (for instance the live video capture or the text).For the user, all the media are managed the same way. For example, you can use all the filters or the geometric transformation on a movie, a video capture or a Flash animation. Only the initialization is a bit different if the media is a file or an internal dynamic media. A media file has to be dragged to one of the five media banks while internal media are displayed in a special bank.

The Media Panel

The media panel is made of a five different banks plus a special bank for internal dynamic media.You.can.click.on. the.1-5.numbers. to.change.the.current.bank..Each.bank.has.a.4x4.grid.designed.to.receive.media..

To add media, you simply drag it to one of the empty box. You cannot drag a media to an already occupied box. You have to remove it first by entering the edit mode and then using the “del” button. Once it.has.been.removed.you.can.drag.a.new.media.to.the.empty.area.

You can also use the “Import Media...” function in the “File” menu to import your media using a standard dialog box. In this case the media are simply added to empty zones in the media panel.

When you click on a media it is automatically linked to the selected layer. This can be avoided by clicking on the “I” button. In “info” mode you can select and work in the media panel without affecting the. current. layer.. It. is. pretty. useful. if. you. need. to. rework. your. media. without. modifying. the. playing.composition.

In this mode you can access information about your media such as the codec, fps, duration, etc.The info.button.can.be.used.to.get.info.about.a.media.and.edit.some.of.its.attributes.

The info mode enables also several new functions to arrange your media. First of all, in this mode

1 A loaded media�.The current media.bank�.Enter.the.edit.mode.to.get.info.about.your.medias.and.edit.them

1

��

ME

DIA

MAIN PANEL

01Main panel

VERSION 2.5


1�

you.can.drag.and.drop.your.media.to.re-arrange.your.set..It.allows.you.to.change.the.order.of.the.media.and to move a media from one set to another. You will find functions to delete a media, reveal its file in the finder or force it to be preloaded in memory.

Several.media.options.can.be.set:

Bilinear Filter: By default Modul8 filter your media to smooth the pixel when the resolution of the screen.is.higher.than.your.media..If.you.want.to.see.un-smoothed,.squared.pixel.when.you.scale.your.media,.you.should.turn.off.this.option.

Lossless Quality: This allows you to choose if you want your media to be rendered in lossless quality. In this mode, the media is not transformed and rendered exactly as it was compressed (you will see a big difference with interlaced media such as DV).

Memory storage: There are three different strategies for Modul8 to access your media: Not compressed in memory, compressed in memory or streamed from the disk. The first option allows the faster playback but.it.uses.a.lot.of.memory,.while.the.last.one.uses.nearly.no.memory.at.all,.but.requires.heavy.disk.access..Modul8 automatically try to find the best possible storage when you import a media, however you can change.it.manually.from.here.

special Media

If you look at the media panel, after bank number eight you will see a special tab. This is where you can access the bank of internal media. This place contains three special media slots, one for entering the text mode (see the “Text” chapter), one for activating the video capture (see the “Capture” chapter), one to.display.color.bars.that.can.be.useful.to.set.up.a.projector.or.a.video.monitor.and.the.last.one.which.represents dynamic canvases (like for live painter) These special media can be used just like any other standard media that have been imported to Modul8. They can be linked to a layer, mixed, etc.

supported Media

Besides the internal media (like video capture), Modul8 supports several different media file formats. Currently, they can be divided in two categories: image (no time line) and movie (a time line).

ME

DIA

MAIN PANEL

01Main panel

VERSION 2.5


18

Images

Modul8 supports most of the image formats (png, bmp, pdf, psd, gif,etc.) However Modul8 does not support CMYK color format (you have to convert CMYK images to RGB before importing them). When an image format is composed of several pages (like in a pdf) only the first one is displayed. Complex multi-layered images (like PSD images) may require a pre-render and a merge of the layers before Modul8 is able.to.display.them.correctly..

The alpha-channel when available is used directly in Modul8 (see the “Transparency” chapter).Images are always stored in memory, so the file format does not affect the rendering performance.

Movies

Modul8.uses.Quicktime.to.import.movies,.so.Modul8.can.read.most.of.the.Quicktime.codecs..Flash.5 animation can also be read but you have to be very careful of the boundary size of your animation if you want.to.obtain.good.performances..

Even. if. Modul8. can. read. most. of. the. Quicktime. supported. formats,. you. will. obtain. completely.different.performances.depending.of.the.codec.that.has.been.used.for.compressing.your.media..See.the.“Performance” chapter for more information.

Transparency

Modul8.supports.a. full.per.pixel.8.bits.channel. for. transparency.. It.allows.you.to.create.very.high.quality.transparency.effects..

For.images.you.have.several.image.formats.that.supports.per.pixel.transparency..We.highly.recommend.that you use the “PNG” or the “PSD” format to store your image with transparency.

Regarding movies, there is one codec included with Quicktime that supports per-pixel transparency: the “Animation” codec. Unfortunately, this codec is very time consuming and is therefore not very efficient for real-time playback. A solution is to create small loops that can be stored entirely decompressed in memory, this way the decompression is not necessary and you will have very efficient per-pixel and per-frame.transparency.

Of course, Modul8 is able also to generate on-the-fly transparency using luma-key or the layer mixer too (see the “Layer” chapter) for media that do not support transparency.

Performance

If.you.have.some.experience.with.real.time.video,.you.know.that.using.the.correct.codec.for.video.compression is critical in order to obtain good performance. This is especially true with Modul8. Even if most.of.the.codecs.are.supported,.you.will.see.huge.differences.in.performance.if.you.re-compress.your.media.with.the.appropriate.codec.

The best codec for Modul8 today is the Photo-JPEG codec.If your movie is in black and white you should use the “Graphic” codec.

For per-pixel transparency you can use the “Animation” codec. It is a time consuming codec, but if your media can be stored decompressed in memory (in other words, if it is a short loop) you will be able to use.it.at.no.speed.cost.and.enjoy.a.per-pixel.alpha.for.each.frame.of.your.movie.

For.long.movies,.you.may.also.use.the.DV.codec.especially.since.the.V2.5.where.the.performances.have.been.a.lot.improved.

ME

DIA

MAIN PANEL

01Main panel

VERSION 2.5


1�

sound Playback

Modul8 fully supports video sound. By default sound output is disabled in the master panel. To turn it on, you simply have to change the sound level using the “out” knob.

You can also change the sound volume for every layer individually using the play option (in the “opt” tab at the top-left of the layer settings).

Sound.is.correctly.managed.also.by.the.cross-fader..It.means.that.when.you.cross-fade.from.a.group.to.another,.the.sound.will.also.be.cross-faded..

Changing.the.transparency.of.a.layer.lowers.the.sound.volume.of.the.layer.

If.you.don’t.need.sound.at.all,.you.can.turn.it.off.in.the.preferences..In.this.mode,.sounds.is.completely.ignored.and.it.will.improve.the.performance.of.Modul8.

ME

DIA

MAIN PANEL

01Main panel

VERSION 2.5


�0

Memory

By default, Modul8 tries to entirely store a media in memory if it takes less than 30 Mbytes (this limit can be changed in the preferences). If the media fits uncompressed in memory it is entirely loaded and stored decompressed (please note that this mode is not used if a movie has a sound channel). It is the best.case,.because.it.takes.no.CPU.time.and.no.disk.access.to.play.the.movie..However.it.works.only.with pretty short (or small) loops (unless you have a huge amount of memory). If the media does not fit decompressed in memory, Modul8 tries to store the media compressed in memory. This way the media can.be.played.without.disk.access..If.the.compressed.media.is.still.bigger.than.the.30.Mbytes.limitation,.the.media.is.streamed.from.the.disk.

This is the automatic mechanism. However you can change the memory mode by hand by using the “info” button of the media panel. In the media info zone, there are three checkboxes that allow you to change the memory mode directly. The panel will also show you an estimation of how much memory is required for each different mode. This is very useful to prevent an out of physical memory situation that would.cause.a.dramatic.slow.down.of.Modul8.

Of course the best case is when a media can fit entirely decompressed in memory. You will reach incredibly.good.performance,.but.you.will.suffer.a.huge.memory.cost..Most.of.the.time,.you.will.have.your.media.compressed.in.memory;.this.is.a.middle-path.where.your.media.still.takes.CPU.time.for.compression.but.on.the.other.hand.does.not.require.disk.access.and.stays.pretty.small.in.memory.

Please.note.also.that.not.all.the.media.linked.to.the.media.panel.will.stay.all.the.time.in.memory..If.you.don’t.use.a.media.for.a.long.time.and.your.physical.memory.starts.to.be.low,.it.will.be.removed.from.memory. Next time you use it, an asynchronous mechanism will reload it, causing a short delay the first time.you.use.it.

It.is.possible.to.know.the.memory.state.of.a.media.by.checking.the.media.panel..When.a.media.is.not.in.memory,.a.red.icon.is.displayed.on.its.preview..When.the.media.is.loading,.an.orange.icon.is.displayed..When.no.icon.is.displayed,.it.means.that.the.media.is.loaded.and.ready.to.be.played.

The dynamic Media

Modul8.also.supports.several.other.media.types.such.as.real.time.video.capture,.text.or.live.painting..These medias (with the exception of the video capture) are typically accessed through modules. Please see.the.corresponding.chapters.for.more.information.

summary

In this chapter you learned about media management in Modul8. The following points have been covered:

• How the media panel works and how to import media files.• There are internal media (like video capture) and external media (movies, images...)•. Modul8.supports.most.of.the.image.and.movie.formats.• Full per-pixel transparency is supported for movies and images as long as the media format (or codec) supports it.• The best codec to obtain good performance is the “PHOTO-JPEG” and the “Graphic” for black . and.white.movies.•. Modul8.supports.three.memory.modes:.decompressed.in.memory,.compressed.in.memory,.. streamed from the media file.

PR

EV

IEW

MAIN PANEL

01Main panel

VERSION 2.5


PrevIewoverview

The preview panel is an area where you can see, prepare and move along the X/Y axis a selected layer. The preview panel can also be very useful to see your composition when you are doing a projection that you cannot see. This panel can work in four different modes that will be covered in the next chapters. Whatever.the.current.mode.is,.you.can.always.move.your.layer.by.clicking.in.the.panel.and.dragging.the.mouse..It.is.a.very.intuitive.way.to.move.the.selected.layer.in.2D.space..

Grid Mode

The grid mode is the default mode. It simply displays a grid and a target that can be used to see where is the center of your layer proportionally to the size of the output composition. This is a minimal mode that consumes nearly no CPU time. The Grid Mode has also a very useful “center” button that can be.used.to.re-center.the.selected.layer..Please.note.that.in.every.mode,.you.can.also.double.click.in.the.composition.to.re-center.the.layer.

layer Mode

The layer mode displays only the selected layer. It is a pretty useful mode when you have a complex multi-layered composition and it becomes difficult to identify the modifiers you are applying to the current layer..

Group Inv. Mode

This mode is useful when you work with A/B layer group. In this case your layers are divided in two groups A/B, with only one being displayed at the same time. This allows you to prepare a composition while you are displaying another one. The “Group Inv.” mode basically displays the composition that is not displayed in the final output. For example, if you are displaying the group A in the final output, it is the group B that is displayed in the preview. When you cross-fade from one group to another the “Group Inv.” mode also inverses the two displayed compositions. This is the mode you should use when working with the A/B layer groups.

Group a/b Mode

These two modes simply display either the layer group A or the group B.

output Mode

The output displays a full copy of the final output view. It allows you to see quickly exactly how your composition looks and is very useful when the final output is a projection that cannot be seen from where the.video.mixing.is.done..

�1

PR

EV

IEW

MAIN PANEL

01Main panel

VERSION 2.5


��

out Mix Mode

The mix mode is similar to the output mode with one difference: the selected layer is displayed in the preview panel even if it is hidden in the final composition. The mix mode has been designed to allow the preparation of a layer before it is sent to the final composition. You simply hide a layer by using its checkbox in the layer list. Then you can work on it in the preview panel and when it is ready simply re-enable.it.

The layer is hidden in the final output preview

In mix mode, the layer is displayed even if it is hidden

PR

EV

IEW

MAIN PANEL

01Main panel

VERSION 2.5


��

summary

This chapter allowed you to learn how to use the preview panel. The following points have been covered:

• The preview panel can be used to view part of or the full output composition.• It can be used to move the selected layer along the X/Y axis.• A mix-mode allows you to prepare a layer before it is sent to the final composition.• How to preview the A/B layer groups

VERSION 2.5

OU

TP

UT

VIE

W

MAIN PANEL

01Main panel


��

sInGle ouTPuToverview

The output view is where the final composition is displayed. By default it is rendered to a resizable and moveable panel. However, you can enter a full screen mode where it entirely covers the screen. This is typically.the.mode.that.you.will.use.if.you.have.a.second.screen.or.when.you.connect.a.projector.to.your.computer.

full screen Mode

To enter the full screen mode, go to the “Output” menu and select full screen. If your computer supports.more.than.one.video.output,. the. full.screen.view. is.placed.on.the.second.screen,. if.not,. it. is.placed on the main screen over the user-interface (see the “Single Monitor System” chapter).

You can exit the full screen mode by going to the “Output” menu and selecting “Windowed” or by pressing the keyboard shortcut COMMAND-T.

single Monitor system

Modul8. supports. computers. with. only. one. video. output.. However. in. full. screen. mode. the. user-interface.is.entirely.covered..

In this case, the only way to exit the full screen mode is to press coMMand-T.

Mixing without the user-interface requires that you use a midi table or keyboard shortcuts. Actually it is pretty easy to configure Modul8 (see the “Midi and Keyboard” chapter) to get it working without visual feedback.

summary

This chapter allowed you to learn how to manage a full screen context:

•. You.can.at.any.time.switch.from.full.screen.to.windowed.output.•. When.more.than.one.video.output.is.available,.the.second.one.is.used.for.full.screen.•. If.only.one.video.output.is.available,.the.full.screen.mode.will.cover.the.interface..In.this.case... you.should.use.the.midi.or.the.keyboard.to.pilot.Modul8.• When the user-interface is covered by a full screen context, use COMMAND-ESCAPE to go back to “Windowed” mode.

VERSION 2.5

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel


��

MulTI-ProJecTIonIntroduction

The advanced projection mode is a technic that let you output several video streams from one single computer..It.is.possible.to.have.up.to.eight.outputs.simultaneously.with.a.computer.as.long.as.the.computer.has.several.video.cards.installed.The outputs can be used by video projectors, monitors or any other devices which support the output video format of your graphic cards. These multiple outputs can represent together one single image like a video.wall.or.a.completely.independent.set.of.multiple.compositions.

basic Principles

The main composition of Modul8 can be segmented into rectangular cuts named “clip”. Each clip can be directed to one or more video outputs simultaneously. The number of clip, their size or position can be modified in real time by the user.

Any thinkable placement in space is possible, even crossings or multiple scales of the clip.

Hardware configuration

computerOnly the computers which supports PCI-Express video cards let you fully use the multi-output features of Modul8. At the time this documentation was written, It means the last PowerMac G5 generation or the Intel.Mac.Pro.Nevertheless there is an alternative to use multiple VGA output on other kind of machines like portables. This solution is described in the annex.

Graphic cards and the video outputsIt is critical that you use graphic card with 3D acceleration. These cards usually have two DVI video outputs, which.means.up.to.eight.outputs.on.one.single.machine,.typically.seven.for.the.projectors.and.one.for.the.Modul8.user-interface..If.you.don’t.need.the.user-interface,.you.can.even.use.the.eight.outputs.

For the formats that are different than DVI, Apple proposes DVI adaptors to video (composite and s-video) and DVI to VGA adaptors.

Notes:In order to obtain the best performances, it is advised to install the same video cards. Also note that some video.cards.support.only.video.composite.and.s-video.on.one.of.their.two.DVI.outputs.

system configuration

In. order. to. use. the. advanced. projection. mode. you. have. to. configure. your. computer. in. the. system.preferences. Be sure to quit Modul8 and to check that all your devices are connected to the video cards. Open the System Preferences panel in the Application folder of Mac OS X.

Click on the “Arrangement” tab at the top of the window and deselect “Mirror Displays” if it is activated.Then go to the “Display Tab” and select “Gather Window”. In each window you should set the resolution, the colors and the refresh rate. Try to use exactly the same settings for all displays in order to have the best.possible.performances.

Notes:If.the.number.of.windows.does.not.correspond.to.the.number.of.connected.screens.or.projectors,.you.should click on “Detect Displays” in the Display tab.The ‘Show Monitor’ option in the menu bar let you change and visualize your screens and resolution in the

VERSION 2.5

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel


��

menu bar of the Mac OS X.

warningTo avoid stability problem in advanced mode, you must quit Modul8 each time you change the number of.outputs.or.the.system.preferences..It.means.that.each.time.you.connect.or.deconnect.a.device,.you.change.the.output.resolution.or.refresh.rate,.etc..you.must.quit.Modul8.and.restart.it.when.it.is.finished.

Apple advises to turn on your computer and all the connected devices before changing the connections. If.you.do.that,.be.sure.to.turn.on.the.screens.and.the.projectors.before.the.computer.

For. the.best.performances. it. is. critical. that.each.projectors.and.screens.use. the.same. resolution.and.refresh.rate.

activating the advanced mode

o.activate.the.advanced.mode:

1) Open the advanced output setup window from the ‘output’ menu

2) Select the Advanced Output Enabled checkbox

VERSION 2.5

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel


��

The advanced output setup

1

3 4 13

12106 7 8

11

9

2

5

(1,�) representation.area.for editing the clipsEach.clip.can.be.represented.and.modified.in.this.area.

(�,�,�,�,�,8,�,10,11) attributes and configurationTo edit and to configure the different elements and parameters available in the advanced mode.

(1�) routing TableCan.be.used.to.route.the.clips.to.the.video.outputs.

(1�) gestion des configurationsCan.be.used.to.load.and.save.pre-defined.configuration.

representation area

This zone (1) is a representation of your composition space (like you see it in the output or in the preview) where you can see the clips. A dark blue rectangle represents your preview window boundaries. The proportion.of.the.preview.can.be.changed.in.the.preferences.of.Modul8.in.the.preview.tab.Each.clip.is.represented.by.a.rectangle,.where.the.orange.clip.represents.the.selected.one.The representation is a virtual space : you can move the view (just like a camera) by clicking on the background.and.moving.the.mouse.while.maintaining.the.button.pressed..You.can.re-center.or.change.

VERSION 2.5

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel


�8

the representation scale by using the ‘Center’ button or the pop-up menu (�)

Managing the clips

creating and deleting clips

To create or delete a clip, simply select the plus and minus button (�)Note. The delete button will erase only the last added clip whatever is the current selection.

clip selection

After you did create several clips, use the pop up menu (8) to select a clip.

You can also simply click on a clip in the representation area (1)

Note : the orange clip is the selected one, the parameters (�,�,�) are always relative to this one.

Position and size of the clip in the representation spaceAfter you have selected a clip you can change its position and size in the space. This can be done by

selecting and dragging with the mouse. For more precision you can also use the numerical fields (�) and

activate the magnetize function (�)

Notes : The spatial coordinates are based on the view center which is at (0,0)These coordinates are defined on an arbitrary scale which is the same one used in the Modul8 composition.This virtual scale is relative to the working space and the pixel size is defined by the resolution of the video outputs. For a 4/3 ratio the virtual scale is fixed to -320 to 320 for the width and -240 to 240 for the height.

seeing the clips in the previewIt is possible to see the clips over your composition in the preview window. To do this, select the ‘show’

option (10). You can also use the ‘show all’ or ‘hide all’ (10) function to show or hide all the clips.

In order to improve the visibility you can change the clip color (�).

Notes : In the Modul8 preview window, the clips are displayed in every mode but the ‘OUT’ mode, which displays.the.final.composition.as.it.appears.in.the.video.outputs.

clip ratioThe ratio represents the proportion of the clip.Usually.you.will.use.a.ratio.that.corresponds.to.the.ratio.of.your.video.outputs.The 4/3 is the most common ration today.

You can change the clip ration in the pop up menu (8).

routing Table

The routing table (1�) can be used to link your clips to specific video outputs. Basically each output corresponds to one of the graphic card output. The selected clip will be displayed in full screen to the corresponding output. The output number correspond to the screen number as it appears in the system preferences. The main output is usually the screen which contains the menu bar where the Modul8 user interface.is.displayed..You.can..send.the.same.clip.to.several.outputs.or.one.clip.to.each.outputs.depending.of.your.requirements.

As long as you are not in full screen mode, you can see all the outputs as floating windows on the main

screen. It is useful to prepare your configuration. Use the “Show Info” (11) option to see in each output windows.its.corresponding.screen.number.

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel

VERSION 2.5


��

Managing your setup

You can import or export your setup (1�) to a file in order to use them in different contexts. A setup can be changed.in.real.time.during.a.performance..Simply.save.a.set.of.setups.and.when.you.need.to.change.one,.use the “Import Setup button” to load it. The new setup will be automatically displayed in your outputs.

annex

Matrox dualHead�Go and TripleHead�go

t is possible to do multiple projection with Modul8 using one of these Matrox devices. Basically these devices double or triple the size your desktop and then split it in several outputs. This is pretty useful when you.want.to.do.multiple.projection.without.a.MacPro.or.a.G5.PCi-Express.tower..However.the.advanced.setup.mechanism.of.Modul8.cannot.be.used.with.this.mode,.because.Modul8.will.see.only.one.output.

The key to have a projection at the correct size, is to change the preview ratio in the preferences (Preview tab) in order to adapt it to the very wide display resolution. For a dualHead2Go you should select the 8/3 ratio and for the TripleHead2go the 4/1 ratio.

Schema 01: 5 projectors VGA connected +.1.preview

P1

preview

P2 P3 P4 P5

G5

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel

VERSION 2.5


�0

Schema 02: 5 projectors VGA connected +.1.preview

Schema 03: 5 projectors (3 VGA + 4 video) +.1.preview

P1

preview

P3

G5

P2

P5

P4

preview

P1 P2 P3

G5

TV2TV1 TV3 TV4

MU

LT

I P

RO

JE

CT

ION

MAIN PANEL

01Main panel

VERSION 2.5


�1

Schema 04: 7 projectors VGA connected + 1 preview

preview

P7

G5

P6

P5 P4

P3

P2

P1

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

layeroverview

They layer is a key paradigm in Modul8. Basically, when you create a composition you always work with layers. A media is always represented through a layer and all the modifiers you will apply to the media are.achieved.through.a.layer.

Modul8.supports.ten.layers.that.can.be.mixed.together..Layers.at.the.top.of.the.list.are.at.the.top.of.the composition (in other words, they are stacked starting from the last one to the first one).Each.layer.represents.one.single.media..When.you.select.a.media.it.is.automatically.linked.to.the.selected.layer..You.change.the.selection.of.the.layer.simply.by.clicking.on.it.All the controls at the right of the layer list reflect the current state of the selected layer; they are updated each.time.you.select.another.layer.

Managing layers

Managing.layers.is.pretty.easy..You.can.add,.remove.or.duplicate.layers.using.the.buttons.at.the.top.of the layer list or by using the corresponding items in the “Edit” menu. When you add or duplicate a layer, it.is.inserted.at.the.current.selected.layer.position.

The layer stack

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

You can change the order of the layers by clicking in an empty zone of the layer box and dragging it in the layer list. The composition is immediately updated when the layer is dropped.

Each layer can be turned on/off by using the checkbox directly linked to it in the layer list. A slider also allows you also to change the global transparency of a layer. At the bottom, a caption displays the media.currently.linked.to.the.layer.

working with a/b layer groups

While. it. is.possible. to.work.with. the. ten. layers.as.one.composition,.Modul8. is.able. to.divide. the.ten layers in two groups of five layers. In this mode, you have two simultaneous compositions called respectively the group A and the group B. The main utility of this mode is its ability to display one group in the final output view while you are working on another composition in the preview window.

By default, the layer stack is just one continuous composition made of ten layers. To divide the layer stack in two groups A/B you simply enable the cross-fader by turning on one or more A/B transition option.

change the layer order with a simple mouse drag

1 �

��

1 Turn layer on / off� Transparency� linked media� selected media as an orange border

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

In the current version of Modul8 there are two transition effects to cross-fade between the groups A/B:

Fading: The layers disappear using transparencyScaling:.Each.layer.is.reduced.until.it.disappear.entirelyThese two modes can also be combined.

Typically you turn on a cross-fading mode for the two groups A/B. The most common usage is to use the fading mode on both A/B and then use the “Group Inv.” mode in the preview window to see the inverse of the final output.

It.is.also.possible.to.turn.on.a.cross-fading.mode.for.only.one.group..In.this.case,.using.the.cross-fader.will.have.an.effect.only.on.the.selected.group.

Play

The “play” section is for all the animated media that have a predefined time line (typically movies). For images,.texts.or.video.capture,.this.section.does.nothing..It.includes.function.to.alter.the.playback.speed,.the.loop.mode,.etc.

speed

The speed slider allows you to change the playback speed of the media linked to the layer. You can.use.the.reset.button.to.set.it.back.to.its.default.speed..Depending.of.the.codec,.using.a.time.speed.different.than.the.default.one.may.require.more.CPU.time.

loop Mode

By default, movies are automatically played in loop mode. However you can change the loop mode using the.three.icons:

Simple.loop.mode:.Movie.is.restarted.when.the.end.is.reached

� ��

�

1

1 Time speed� loop mode� scratch and set entry point� second scratch knob and marker� Play direction

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

Ping-pong:.Play.direction.is.reversed.each.time.the.end.or.the.start.of.the.movie.is.reachedPlay.once:.Movie.is.stopped.when.the.end.is.reached..You.can.restart.it.by.clicking.on.it.in.the.media.panel.You can also change the play direction by using the arrows bellow the loop mode icons (see the next chapters).

scratch

Beside the loop mode icons you can see three different controllers. The arrow can be used to quickly change.the.direction.of.a.playing.movie.

The two knobs can be used to scratch your movie. In other words, these knobs are directly linked to the time line of your movie, so when you turn it you directly jump to a specific position in the movie. The first and the second knobs are identical with one small difference. The first one also marks the default entry point of the movie. Each time the media is restarted by clicking in the media zone, it is restarted at the position of the first scratch knob.

These knobs can also be used as two markers. When you click on them the movie directly jump where.the.knob.is.currently.positioned.

By linking midi controllers to these two knobs combined with the reverse direction function, you can easily.reproduce.the.scratch.sensation.from.the.audio.world,.but.with.images.instead.of.sound.

Movie options

Just beside the “Play” section is the movie options tab (“Opt.”). This section gives you two more options.to.control.your.movie:

setting movie entry/exit points

This control allows you to select a section of the layer. Only the selected area will be played and looped. This is a double slider where you simply move the entry and the exit point of the movie. The current.position.of.the.movie.is.immediately.moved.to.be.in.the.selection.if.required..Please.note.that.it.is.a.layer.option.and.that.changing.the.attached.media.won’t.change.the.selection.

sound volume

This knob allows you to specify the sound volume for this layer.

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

Transition

Beside the movie section, there is a “Transition” tab that allows you to access the media transition options. A transition is an effect that is applied when a media is changed in a layer. By default, when a new.media.is. linked.to.a.layer,. it. is. immediately.replaced.by.the.new.one.in.the.composition..However.sometimes.you.may.want.to.have.a.smoother.transition.between.the.media.changes.

The only transition effect available now is the cross fading. When enabled, the two medias are cross-faded until the old one becomes entirely transparent. The transition duration can be modified using the “transition time” knob.

Transition effects can be applied to any media from any kind of media. For instance you can use it on text.or.on.a.video.with.a.patch.transformer.allowing.the.achievement.of.complex.effects.very.easily.

Transform

The transform section can be used to scale and rotate a layer by hand. See also the “FX” chapter for automatic.scale.and.rotation.

scale

The main slider of the scale area simply does a proportional scale of your media. Clicking on “reset” will reset the media to its default screen. Non-uniform scaling is achieved by using the “+x”, “+y”, “+z” sliders. The z coordinates are useful for 3D objects like patch or matrix.The small buttons above the scale sliders can be used to multiply the effect of the scaling allowing you to set.very.high.scale.values.

The normalize option is useful when you want the size of your media to be normalized to the size of the screen whatever is their original pixel size. By default, Modul8 respects the original size of the media.

1 Proportional scale� scale multipliers� non proportional scale� rotation

��

�

1

�

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

When this option is selected, the original size is ignored, and the full screen size becomes the default size. Please note that you can continue to scale your media even with the normalize mode enabled.

rotation

You.can.rotate.a.layer.not.only.on.a.plane.but.also.spatially..In.Modul8.the.Z-axis.goes.inside.the.screen. So for a simple 2D rotate you simply use the Z knob. By using the X and Y knob you can also perform perspective rotation on the X-axis and Y-axis. If you click on the small zones around the rotation knob, you can jump directly to a predefined angle. For instance, clicking below the Z rotation knob will rotate.immediately.the.layer.to.180.degrees.You can use the “reset” button to reset all the angles to zero.

Post-colorize

The post colorize section allows you to modify the color channels after all the effects have been applied. Post-colorization has no CPU costs because the filtering is entirely done through the GPU, so they.are.very.fast.

These filters are called “Post-colorize” because they are applied at the very end of the filter/transformer chain. It means also that effects that are based on the pixel color (like the patch transformer displacement mapping) won’t be affected by the result of the post colorize function. Post-colorize really changes the color.after.all.the.other.effects.have.been.applied.

Basically there are two post-colorize functions:

• The “minus” sliders allow you to modulate each color channel independently from zero to the . original.pixel.color.of.the.media..In.other.words,.this.function.removes.color.from.the.original.. medias. If your media is entirely blue and you set the blue channel to zero it will become black. Also in the same situation if you change the red channel it won’t have any effect on the media, because the red is already at zero.

• The “plus” sliders allow you to increment the value of each color channel independently. If you set all the sliders to the maximum value, the media will become white. This is an additive mode; . it.will.never.remove.light.from.the.original.source.

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


�8

Pixel fX

The pixel FX section represents a chain of predefined pixel level effects that modifies the content of the medias. These effects are cumulated from the left to the right.

saturation

This is a pixel filter that modifies the saturation of the media. You can turn it on by clicking on the title bar of the effect. The knob allows you to change the intensity of the saturation. By default, it is a moderated saturation, however you can use the boost button to create over-saturation effects. The “inverse” button can be used to reverse the saturation function allowing you to inverse the color of your source. Saturation is a time consuming filter, so turn it off by clicking on the title of the saturation section when.it.is.not.required.anymore.

lightness

This pixel filer modifies the brightness of the media. It supports two different modes:

• Graduation: This is an additive/subtractive linear brightness.•. Glow:.Increments.the.brightness.using.a.factorial.value.

contrast

This filter allows you to change the contrast of your media. You can turn it on by clicking on the title bar of the effect. The knob is used to change the intensity of the contrast. By default, it is a moderated contrast, however you can use the boost button to create over-contrasted effects. The “inverse” button can.be.used.to.reverse.the.contrast.function.allowing.you.to.inverse.the.color.of.your.source..Contrast.is.a time consuming filter, so turn it off by clicking on the title of the contrast section when it is not required anymore.

luma key / color key

This filter can be used to generate per-pixel transparency dynamically. You can turn it on by clicking on.the.title.bar.of.the.effect..

It.is.pretty.useful.for.media.that.do.not.have.transparency.information.or.when.you.want.to.change.the.transparency.dynamically.

Modul8 supports two luma-keys and three different color keys. The luma key tries to generate transparency.based.on.the.luminosity.of.the.source.while.the.color.keys.are.based.on.the.intensity.of.a.color.channel.

The possible keys are:

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

• Luma key: the darker the pixel, the more transparent it gets. Black is 100% transparent while white is 100% opaque.• Luma key inv. This is the inverse of the standard luma key. The darker the pixel, the more opaque it gets. Black is 100% opaque while white is 100% transparent• R: the redder the pixel, the more it gets transparent•. G:.the.greener.the.pixel,.the.more.it.gets.transparent• B: the bluer the pixel, the more it gets transparent

By default, when a luma key is enabled, the original alpha of the media is not applied anymore. If you want to combine the alpha of the source with the result of the luma you have to set the “Preserve alpha” check.box.

While the luma-key filter is less time consuming than the saturation and the contrast filter, it still can slow.down.the.composition..You.should.turn.it.off.when.it.is.not.required.by.clicking.on.the.title.bar.of.the.effect.

While the luma-key filter is less time consuming than the saturation and the contrast filter, it still can slow.down.the.composition..You.should.turn.it.off.when.it.is.not.required.anymore.by.clicking.on.the.title.bar.of.the.effect.

noise

The noise filter can be used to generate pixel level random noise in the media. First you can choose to apply colored or monochromatic noise using the “colored” option. In color mode, the noise filter generates different.values.for.each.color.channels.while.in.monochromatic.mode.it.generates.one.random.value.and.applies.it.to.all.the.color.channels.

Then you can choose to apply the noise to the RGB channels, the alpha channel or both. When you apply it on the alpha-channel it modifies the transparency of the source.

blur

The blur filter supports two different real-time blur effects. The “Fast X” is a very fast horizontal blur that has very low CPU requirements. The “Box” blur is a more sophisticated blur that is slower than the “Fast X” blur though. These blurs effects are not proportionally slower to the amount of blur you set. So incrementing.the.amount.of.blur.does.not.slow.down.the.effect.

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


�0

animation effects

The “Animation FX” section contains a set of effects that are entirely achieved through the GPU of your.graphic.card..In.other.words,.they.are.fast.and.do.not.use.a.lot.of.CPU.time..Most.of.these.effects.are.geometrical effects that do not modify the content of the media. They simply transform the whole layer. Some.of.these.effects.can.also.be.controlled.in.several.ways.going.from.sound.input.intensity.to.sinusoidal.curves.and.more.

animation curves

It is possible to apply a motion curve to most of the animation effects (auto-move, auto-scale and auto-rotate).

Possible.functions.are:

• Sound-In: It is based on the intensity of the input sound. You can use it to synchronize the . motion.with.a.sound.entry.

•. In:.Increment.the.position.of.the.layer.on.the.selected.axis.• Out: Decrement the position of the layer on the selected axis.•. Linear:.Increment.and.decrement.the.position.of.the.layer.on.the.selected.axis.linearly..• Smooth: Apply a sinus function to the position of the layer on the selected axis.• Random: Randomly change the position of the layer on the selected axis.• Cut: Apply a square curve to the motion.

auto Move

The auto-move section is used to program an automated motion of the layer along the X/Y axis. To enable it, simply select the title of the function. The pop-up menu allows you to change the function that is.applied.to.the.layer.position..

.You can choose the axis of the auto-motion by selecting one of the arrow icons: left/right, top/bottom

or both. All the functions have a size and a speed slider that can be used to modify the amplitude and the speed of the effect. A “strob” slider can also be used to obtain a stroboscopic motion.

auto scale

The auto-scale section can be used to program an animated uniform scale of the layer. To enable it, simply select the title of the function. The pop-up menu allows you to change the function that is applied to.the.layer.scale..

All the functions have a size and a speed slider that can be changed to modify the amplitude and the speed of the effect. A “strob” slider can also be used to obtain a stroboscopic motion.

auto color

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


�1

The auto-color section is used to apply an automated color modulate/additive function on every color channel independently (including the alpha-channel for transparency). To enable it, simply select the title of the function. The pop-up menu allows you to change the function that is applied to the layer color modulate..

When you select “+”, it is the color additive that is animated. If you select “-“, it is the color modulate (that is only subtractive). You can select the two modes simultaneously.

Basically, the auto-color sets the color channel from 0 to 100 percent in modulate mode and to 100 percent.to.200.percent.for.the.additive.mode..You.can.change.the.speed.of.the.auto-color.function.by.using the four sliders: Red, Green, Blue and Alpha-Channel (transparency). The higher the slider, the faster the channel is modified. If you set a slider to zero, the color channel won’t be modified anymore and it will stay.as.it.is.

auto rotate

The auto-rotate section can be used to program an automated rotation of the layer on the axis X, Y and.Z..Each.axis.has.a.different.slider.that.can.be.used.to.change.the.speed.of.the.rotation.on.the.selected.axis. The small button beside the slider can be used to change the direction of the rotation.

At the bottom of the auto-rotate section is a “strob” button that can be used to lower smoothness of the.rotation.

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

The transformers

The transformer section allows you to transform the initial geometry of the object in a more complicated shape. Typically a media is rendered on a surface that can be rotated, scaled, moved. However by default this surface is always flat, unique and as similar as possible as what was the original media. The transformer.section.can.be.used.to.reshape.this.surface..Current.version.of.Modul8.supports.three.kinds.of.transformers:.the.matrix,.the.patch.and.the.particle.engine.

Matrix

The matrix transformer allows you to tile your layer in a grid of up to ten by ten. It is also possible to tile.your.media.in.the.Z.direction.allowing.three-dimensional.tiling.and.even.extruding.the.tile.on.the.Z-axis.for.generating.cubicle.tiles.

To enable the matrix, simply select the title of the matrix section.If.you.want.to.increment.or.decrement.the.tiling.on.one.single.axis.you.can.use.the.arrow.buttons.beside.the X/Y/Z axis or directly click on the number button and drag the mouse up and down until the required number.is.reached.

The “space” slider allows you to change the space between the tiles. There are also three checkboxes that allow.you.to.alter.the.way.the.grid.is.represented:

• Flip: Allow you to create a pattern that flips the image on even and/or uneven columns and rows.• Resize: When set the grid is resized proportionally to the original media size. Otherwise, the grid is created without modifying the original size of the media.

When you increments the tiling on the Z-axis you should use the “deep space” option to set an amount.of.space.between.the.tiled.media.

The extrusion slider can be used to extrude each tile on the z axis allowing the creation of 3D dimensional.cubicle.tiles

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

Patch

The patch transformer renders your media on a grid of polygons where each vertex can be modified independently. You can choose the base shape of the patch using the small icons under the shape title: flat, x-cylinder, y-cylinder, sphere. All the effects that you apply to the patch are relative to its base shape.

You can also choose the fill mode using the small icons above the “fill mode” title: wire frame, points, filled.

Another important component of the patch transformer is the amount of surface subdivision. This subdivision can be set using the “Div X/Y” parameter. Of course higher these values are, slower is the rendering time of the patch. On the other hand higher subdivision means smoother surfaces.

When working in wire frame or point mode, you can use the “thickness” to change the size of the line or.the.points.

The next section of the patch user-interface contains functions to modify the height of the vertices of the patch. This is where can really shape your patch the way you want.

One of the most powerful functions of the patch deformer is its displacement mapping functionalities. Basically displacement mapping reads the lightness of the source media and maps it to the patch vertex height..For.instance,.if.you.have.a.black.and.white.source.image,.all.the.areas.where.the.pixels.are.black.will. stay. at. the. same. level,. while. all. the. white. areas. will. be. extruded. by. the. amount. of. displacement.mapping. Please note that it is not a simple 2D effect. The extrusion will generate a true 3D shape that can be rotated, scaled, etc. This powerful function allows you to create complex 3D animation with simple 2D.videos..It.is.also.interesting.to.note.that.the.displacement.mapping.is.applied.after.all.the.pixel.effects.have.been.computed..It.means.that.you.can.also.modify.the.shape.of.the.patch.using.a.blur.or.a.noise.pixel filter.

The displacement mapping is able to work on the RGB channel and/or the alpha channel. For example, you.may.want.that.the.displacement.mapping.to.be.relative.to.the.transparency.of.the.object.but.not.to.the.color content. In this case, you can choose the alpha option and deselect the RGB checkbox.A noise function can also be used to generate height noise on the patch vertices. You simply use the knob to.set.the.amount.of.noise.you.want.

For.those.who.work.with.sound.input,.it.is.possible.to.map.directly.the.sample.capture.curve.to.the.patch.allowing.a.direct.representation.of.the.sound.motion.on.the.3D.object..You.can.also.use.the.delay.option,.so.the.sound.curve.is.scrolled.over.the.patch.over.time..Please.note.that.these.sound.effects.cannot.be.recorded.by.the.logical.record.function..If.you.want.to.generate.a.movie.with.a.patch.representation.of.the.sound.capture,.you.need.to.use.the.direct.to.disk.record.function.

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

Particle emitter

Modul8 supports real time 3D particle emitters. This emitter is implemented as a transformer allowing any media to be rendered by the particle engine. The particle emitter can be moved, scaled, rotated, etc. using the standard layer functions. In this case all the particles are transformed simultaneously (even the ones that already have been created). This is because the layer contains the whole particle emitter, so modifying the layer modifies the whole particle system.

By default, particles always face the viewer. When you rotate the layer it rotates the gravity point of every particle, but they always stay in front of the viewer (their surface is not rotated). It is possible using the.module.mechanism.to.have.a.greater.control.over.the.particle.system,.see.the.module.chapter. for.more.information.

The particle emitter is controlled using several parameters. Here is a description of all the controls:

• Life: This is the life duration of the newly created particles.• Part. Sec.: This is the number of particles par second that are generated.• Size: The size of the newly created particles.• Speed: This is the motion speed of the newly created particles.• Radius: This is the radius of the sphere that represents the emitter. If you set the radius to zero, all the particles are generated at the exact layer position in space. When you set a non-zero radius, particles are generated randomly inside the sphere that is defined by the layer position . and.the.emitter.radius..• Apert.X/Y: This is the cutoff angle of the particle emitter. The emitter works a bit like spot light: It generates particles in a line, a cone or a sphere depending of the size of aperture angle. If you set both values to zero, all particles will have the same direction and will follow a line. If you . set.both.values.to.the.maximum.value,.each.particle.can.have.any.direction.so.they.will.produce.. a sphere. By manipulating these two angles you can shape the flood of particles.•. Gravity:.You.can.apply.a.gravity.factor.to.the.particle.emitter.using.this.function.• Transparency In/Out: The particle system is able to interpolate the transparency of the particle during their lifetime. You can use these options to apply a fade in/out effect on the particles.• Size In/Out: Works like the transparency In/Out function but with the particle size instead of the . transparency.

VERSION 2.5

LA

YE

R

MAIN PANEL

01Main panel


��

layer local logical record

Beside the global logical record that is described in the chapter “Recording and Rendering” each layer.is.able.to.record.and.playback.the.users.action..We.call.a.logical.record,.a.record.that.is.not.based.on the brute force of compressing the frame to the disk, but simply recording the user actions. The layer local logical record controls are situated just below the layer area. Just like for the global record you can find the following controls (from the left to the right):

•. Clear:.erase.the.current.record•. Play:.playback.the.last.record•. Stop:.stop.the.playback.or.the.recording• Record: start recording new actions.

Unlike.the.global.record,.only.the.actions.in.the.selected.layers.are.recorded..It.means.also.that.all.the.other actions (liker master controls changes) are ignored. It is really a per layer record.

Another difference with the global logical record is that the local record is a cumulative record. And this is where this functionality becomes really powerful: As long as you don’t reset the record, old actions are.not.erased.but.merged.with.the.new.ones.and.when.you.restart.a.new.record.you.can.see.the.playback.of.the.already.recorded.actions.while.you.add.new.actions.

For instance, you can record a mouse drag of the layer, stop it and restart a new record (without clicking on the clear function). The last record will play back as a loop. Now if you modify the noise filter, the modifications will be merged with the mouse drag previously recorded. After that, you can modify another.state.of.the.layer.and.it.will.be.also.added.to.the.current.record,.and.so.on..

The logical record works a bit like a looper allowing you create short loops of actions that can grow up.in.complexity.when.you.add.new.actions.over.the.old.ones.

layer sets

The list of the layers that appears in the main user-interface panel is stored in a layer set. There are eight different layer sets that can be used in the application. Only one layer set is active at any time. You can.change.the.current.layer.set.simply.by.clicking.on.one.of.the.layer.set.buttons.at.the.top.of.the.Modul8.main.panel.

Please note that only the layer settings are stored in a set. The current state of the master controller is.not.stored.in.the.active.layer.set.

You can at any time jump from one set to another. The composition of the new set is immediately displayed and the user-interface is updated to reflect the state of the set.

Layer sets are pretty useful to store a composition that you like and want to re-use later. They can also.be.used.to.prepare.several.compositions.in.a.document.and.quickly.jump.from.one.to.another.

When working in A/B layer group mode, the layer sets are also divided in two groups. The layer sets

LA

YE

R

MAIN PANEL

01Main panel

VERSION 2.5


��

at the top of the layer stack are used to store the layer of the group A, while the layer sets at the bottom of the layer stack are used to store the layers of the group B.

summary

This chapter described the notion of layer, its central role in Modul8 and the effects that are directly related to.it:

• A Modul8 composition is the result of the rendering of the layer stack.•. Each.layer.represents.a.media.• A layer has a set of attributes that allows you to modify and animate the original media.• The attributes of the layer include pixel level filters to modify the media content and a set of . effects.to.animate.and.transform.the.media.• Transformers can be applied to modify the shape of the media surface.•. It.is.possible.to.use.a.layer.local.recording.mechanism.that.supports.cumulative... .

. action.recording.•. Layers.are.grouped.in.layer.sets.that.can.be.used.to.quickly.jump.from.one.composition.to..

. another.

MA

ST

ER

MAIN PANEL

01Main panel

VERSION 2.5


��

MasTeroverview

The master section can be used to apply attributes that will modify the whole composition. In other words, the master controls are applied to all the layers and have no influence on the current selected layer. Please.note.that.the.master.attributes.are.not.stored.in.the.layer.set..If.you.change.the.current.layer.set,.the.master.attributes.are.immediately.applied.to.the.new.set.

speed

The speed slider can be used to change the frame rate of the current project. It acts as a multiplier that slows down or accelerates the animation of the scene. The master speed changes proportionally the time.rate.of.all.the.movies.and.all.the.effects.in.all.the.layers.

scale

The scale slider is a global size multiplier. It works like the master speed but instead of being applied on the frame rate, it is applied to the size value of all the layers.

alpha-channel

This slider is a global transparency multiplier. It allows you to increment the transparency of all the layers.of.the.scene.

Trace Mode

In.trace.mode,.each.layer.becomes.a.painting.brush.that.draws.its.media.over.the.background..You.can use this mode to fill the composition with traces of the animated media. The trace mode also allows you.to.generate.motion.blur.effects.

The level of trace defines how long the trace will stay in the composition before it disappears. When the.maximum.level.is.set,.it.is.never.cleared.and.the.background.becomes.a.painting.canvas.

� � �

1 1 1

�

��

�

1 set global speed, scale and transparency using these sliders.� set global color modifiers using these rGb sliders.� Quick effects.� Trace mode.� set the sound input and output level� set the global record

MA

ST

ER

MAIN PANEL

01Main panel

VERSION 2.5


�8

Quick effects

There are three buttons that can be used to quickly apply a global modifier to your composition. These effects are applied as long as you press the button and are removed when you release it.

•. Invert:.Invert.the.colors.of.the.composition•. Flash:.Flash.the.composition• Still: Pause all time lines (animation)

background color

These RGB sliders can be used to modify the color of the background. This color always appears behind.all.the.layers.

Invert output color

These RGB sliders can be used to invert each color channel of the final composition independently. If you.set.the.three.sliders.to.the.maximum.value.the.colors.of.the.composition.if.entirely.inverted.

output add color

You can use these RGB sliders to add color to the final composition. For example, if your composition if.entirely.red.and.you.set.the.green.slider.to.the.maximum.value,.the.color.becomes.yellow..If.you.set.the.three.sliders.to.the.maximum.values,.the.composition.becomes.white.

sound level

You.can.set.two.sound.levels:.one.for.the.sound.input.and.one.for.the.sound.output.

The sound input level is used to set the sound capture. It can be useful when your signal is too weak or.too.strong..Please.note.that.it.does.not.replace.the.sound.input.level.in.the.system.preference..You.still.may.have.to.change.this.setting.if.your.sound.saturates.or.is.not.strong.enough.

The sound output level controls the sound level of all the playing layers. The individual sound level of every layer is always relative to the master sound level. When it is set to zero, no sound is played.

Global logical record

You.can.access.the.global.logical.record.from.the.master.panel,.including.all.the.main.functions:.clear,.playback, stop, recording. See the “Recording and rendering” chapter for further informations.

summary

This chapter described the use of the “Master” controllers of Modul8. The important points are:

• The master controllers are applied to the whole composition independently of the currently . selected.layer.• The master values are not stored in the layer sets.• The master controllers can be used to apply global time, spatial and color modifiers to the . composition.

CA

PT

UR

E

MAIN PANEL

01Main panel

VERSION 2.5


��

caPTureoverview

Modul8 supports both audio and video live capture. Audio capture can be used to synchronize effects with.the.sound.intensity,.while.video.capture.can.be.linked.to.a.layer.for.real-time.representation.just.like.any.media.

sound capture

Using sound capture is pretty straightforward. Simply select the sound capture flag in the effects that you want to be synchronized with the intensity of the sound input.

At this time, Modul8 simply does pure sound intensity analysis of the captured sample and applies it to.the.required.effect.

You can also use the sound input level slider in the “master” panel to control the level of the captured sound.intensity.

Modul8.uses.the.default.sound.capture.devices.as.it.has.been.set.in.the.system.preferences.

1

1 select sound in

CA

PT

UR

E

MAIN PANEL

01Main panel

VERSION 2.5


video capture

Video.capture.is.used.to.display.images.coming.from.an.external.camera.or.any.video.source.that.can digitized in real time by your machine. Typically, you will use a DV camera or a web-cam connected to the computer via Firewire. To enable video capture, simply go to the special section in the media panel that is labeled with an asterisk (*), and select video capture to get the current layer displaying the image coming.from.the.video.source.

Video capture can be used just like any other media. You can apply all the filters, the effects, etc.

Video.capture.is.CPU.time.consuming.because.of.the.time.required.for.frame.decompression,.so.you.may experience a slow down of the application depending on your configuration.

You.can.change.the.quality.of.the.video.capture.in.the.preferences..However,.you.should.be.careful.with.this.setting.because.the.higher.the.quality,.the.higher.the.CPU.gets.hit...In.other.words,.only.use.high.quality.video.capture.when.you.really.need.it.

summary

In this chapter you learned how audio and video capture works. The main points are:

•. Sound.capture.can.be.linked.to.several.real.time.effects.• The effects use the sound intensity of the captured samples.• The sound input level can be changed in the master controllers.•. Video.capture.is.started.in.the.media.panel.• All the effects and the modifiers can be applied to video capture once it has been linked to a

. layer.• Video capture quality can be modified in the preferences.• The higher the quality, the higher the CPU gets hit, thereby slowing down the application.

�0

1

�

1 use the special media bank.� select video

capture

SA

VIN

G Y

OU

R P

RO

JE

CT

MAIN PANEL

01Main panel

VERSION 2.5


�1

savInG your ProJecToverview

Modul8 is able to save your current project to a file so you can reuse it later. Simply go to the file menu and select “save as” to save your project. To open it, use the “open” function in the file menu. When a.document.is.open,.its.name.is.displayed.in.the.title.bar.of.the.main.Modul8.panel..When.a.document.has.been created, you can save your modifications simply by using “save” in the file menu (or COMMAND-S).The file extension of a Modul8 document is “.md8”.

Media

Modul8 does not save the media with the document. Only the structure of the composition is stored. It.means.that.if.you.want.to.move.your.composition.to.another.machine.you.have.to.move.the.media.with.it..For.the.same.reason,.if.you.delete.a.media.that.is.used.by.Modul8,.it.won’t.be.reopen.the.next.time.you.load.your.project.

Modul8.saves.the.absolute.paths.of.the.media. in.the.document..However. if. the.media.cannot.be.found, the application tries to find them relatively to the document file. It means that you can easily rearrange.your.media. like.you.want. in.sub-directories.as. long.as. the.Modul8.document. is. in.a.parent.directory.

A simple way to organize a project is to put it in a directory with the Modul8 document at the top of the hierarchy and the media in one or more sub-directories. This way you can easily move the project with its.media.on.your.hard.disk.or.to.another.machine..

If.you.have.several.projects.that.share.the.same.media,.simply.save.all.your.documents.to.a.parent.directory.of.the.media’s.directory.Of course, if you never move your media you don’t even have to worry about that.

Midi and keyboard

The midi and keyboard configuration is always saved in a document. However when you open it, the default global configuration is used instead of the saved one. This is because most of the people don’t want to have a configuration that is relative to the project but simply want to set it once and always use the.same.one.

However, if you need a special configuration for a specific project, you may want to configure the midi and keyboard and link it in the document. This is especially true with contextual midi (see the “Midi and keyboard” chapter). To use the configuration saved in the document instead of the default one, open the application preferences in the Modul8 menu and go to “Key/Midi mapping”. Change the radio button from “Use Default Configuration” to “Use Document Configuration”. After you do that, Modul8 will use the configuration saved in the document. You can jump at any time from one configuration to the other, even after.the.document.has.been.opened.

summary

In this chapter, you learned how to save and reopen your projects. The important points are:

• The media are not saved in the document.•. Modul8.can.retrieve.a.moved.media.as.long.as.the.media.is.in.the.same.directory.or.in.a.sub-.

. directory.of.the.document.• It is possible to have one midi/keyboard configuration by document instead of the default one by

setting the “Use Document Configuration” option in the application preferences.

MID

I A

ND

KE

YB

OA

RD

MAIN PANEL

01Main panel

VERSION 2.5


��

MIdI and keyboardoverview

Modul8 supports a very intuitive procedure to configure the midi and the keyboard. Basically, you simply link any midi controller or key to almost any of the user-interface controllers. A live mechanism allows.Modul8.to.automatically.detect.a.moved.midi.controller.or.a.pressed.key.and.link.it.to.the.selected.user-interface.

default configuration

When you open Molul8 or when you reset it using “New” in the file menu a default configuration is set. The default configuration has already several keyboard shortcuts but no midi mapping.

The following keyboard shortcuts are defined by default:

•. F1-F6. . . . Change.the.media.bank• 1-9 (not on the keypad!) Set the corresponding media in the first nine media banks.• Top/bottom arrows Change the current layer• Left/right arrows Change the value of the current slider/knob

To see the default configuration, go to the “Options” menu and select “Edit Key Map”. This will display.all.the.controls.in.blue.with.their.associated.keyboard.shortcut:

The “Save Map As Defaults” can be used to set the default configuration for the current shortcuts. The default configuration is reset each time you open Modul8 or use the “New” function in the “File” menu. The default configuration is also used, when you open a document unless you set the “Use Document Configuration” options in the preferences (see “Saving Your Project”).

MID

I A

ND

KE

YB

OA

RD

MAIN PANEL

01Main panel

VERSION 2.5


��

To reset Modul8 to the initial default configuration, use the “Reset All Maps To Factory Settings” in the “Mapping” menu.

configuring The keyboard

Configuring the keyboard is pretty easy. All you have to do is select the “Edit Key Map” item in the “Mapping” menu. In this mode all the controllers that supports midi mapping are displayed in blue.

To associate a key, simply select a control and press the key. The caption of the key appears over the.control..When.you.go.back.to.the.normal.play.mode,.pressing.the.key.will.have.the.same.effect.as.clicking on the control. Please note that key shortcuts (unlike midi) due to their on/off nature have no effect on sliders or knobs. A same key can be associated only to one controller at the any time. You cannot associate.the.same.key.to.two.different.controllers.

To unlink a key from a controller, simply select the controller and press backspace.

Please. note. that. Modul8. uses. low. level. key. information. to. identify. the. keyboard,. for. this. reason.Modul8.makes.a.difference.between.a.number.in.the.main.keyboard.and.a.number.in.the.keypad..

You can clear the key map using the “Clear Map” function in the “Mapping” menu.

To exit the keyboard configuration mode, simply reselect the “Edit Key Map” item in the “Mapping” menu.

configuring Midi

Configuring midi is pretty similar to keyboard configuration. First of all you select the “Edit Midi Map” item in the “Mapping” menu. All the user-interface controls that can be linked to midi are displayed in green.

To map the midi to the user-interface, simply select a user-interface controller in green and send a midi.message.to.the.computer..For.instance,.if.you.have.a.midi.table,.you.can.select.the.required.slider.in.the.user-interface.and.move.the.slider.on.the.midi.table;.Modul8.will.identify.the.midi.message.sent.by.your.table.and.link.it.to.the.controller.

To unlink a midi message from a controller, simply select it and press backspace. If you want to clear the entire midi configuration, use the “Clear Map” function in the “Mapping” menu. To exit the midi configuration mode, reselect the “Edit Midi Map” item in the “Mapping” menu.

contextual Midi / keyboard mapping

Modul8.supports.several.levels.of.contextual.mapping..When.you.are.editing.your.maps,.three.buttons.are displayed at the top of the main Modul8 panel: focus, position, layerset+position. By default you are working.in.the.focus.mode..It.means.that.midi.or.keyboard.mapping.is.directly.associated.to.the.user-interface controls independently to the current layer or the current layer set. Now suppose that you want to control.the.scale.value.of.the.first.layer.with.a.slider.of.a.midi.table.and.the.scale.value.of.the.second.layer.with.a.different.slider.of.the.same.midi.table..In.standard.midi.mode.this.is.not.possible,.because.the.midi.message.is.directly.associated.to.the.scale.slider.independently.of.the.current.layer.

The contextual modes have been designed to resolve this kind of issue. Basically, the midi message or.key. is.associated.to.a.user-interface.element. in. its.current.context..For.example,. if.you.associate.a.midi.message.to.the.scale.value.of.the.first.layer,.the.midi.message.will.modify.only.the.scale.value.of.this.specific.layer,.even.if.it.is.not.the.current.selected.layer.

In. this. the. position. mode,. you. can. associate. different. midi. messages. or. keys. for. each. layer.independently..

MID

I A

ND

KE

YB

OA

RD

MAIN PANEL

01Main panel

VERSION 2.5


��

When. you. set. the. layerset+position. mode,. you. can. also. associate. different. midi. messages. for.each. layer. set. independently.. In. other. words,. each. layer. set. can. have. a. different. midi. and. keyboard.configuration.

This is also true for the media panel. Each media bank represents a different context. So you can link your.midi.messages.directly.to.the.media.number.4.of.the.bank.number.2.

summary

In.this.chapter.you.learned.how.to.configure.the.keyboard.and.the.midi.to.control.Modul8.The following points have been covered:

• Modul8 has a default midi/keyboard configuration that can be changed•. Midi.message.and.keyboard.shortcuts.can.be.associated.to.almost.all.user-interface.controls.•. Modul8.is.able.to.automatically.detect.midi.messages.and.keyboard.presses,.and.links.them.to..

. user-interface.controllers.•. Special.modes.can.be.used.for.layer.contextual.mapping.

RE

CO

RD

ING

AN

D R

EN

DE

RIN

G

MAIN PANEL

01Main panel

VERSION 2.5


��

recordInG and renderInGoverview

Modul8 offers two different strategies for recording and rendering your animation. The first one, which.also.the.most.straightforward,.simply.captures.the.frames.of.the.animation,.compresses.them.using.a specified codec and save them to a movie file. It is the “Record To Disk” functionalities.

The second way is to use the global logical record mode. The “logical record” records all the changes that occurred in a composition (instead of capturing the frame). Then you can render your record to a movie later. The logical record is much more efficient than the “Record To Disk” mode. It is a lot faster and uses nearly no memory allowing you to record hours of composition without using disk space. Also, because.the.rendering.is.not.done.during.the.live.composition,.it.is.possible.to.use.it.to.render.movies.at.very high resolutions. For these reasons, most of the time it is much better to use the “Logical Record” mode. The only limitation of the “Logical Record” is when you need to record dynamic media coming from the outside of Modul8 like video capture or sound input. The logical record does not record data coming from.the.outside.of.the.application.. It.means.that. if.you.need.to.capture.effects.that.are.relative.to.the.sound input or compositions that contain video input you’ll have to use the “Record To Disk” function.

The logical record

This mode can be used to record all the changes you did to a composition and render them later to a movie..It.is.important.to.understand.that.your.composition.is.not.rendered.immediately..When.you.use.this.record mode, only high-level changes are recorded (like changing the contrast level or moving a layer). It means.that.this.record.mode.is.very.light.in.term.of.memory.usage.and.CPU.cost..For.this.reason,.it.is.the.preferred.mode.to.record.and.render.movies.

Because it is a logical record, the resolution and the codec of the movie are not specified at record time.but.at.render.time..It.is.very.handful.because.it.allows.you.to.record.a.movie.and.render.later.at.very.high.resolution.and.experiment.various.codec.renders.without.having.to.restart.a.record.

The record data is saved in your document project. If you need to save several different records, simply.saves.your.document.under.different.names..

You start a logical record from the master panel. At the right bottom of the master area, you will find several.buttons:

• Erase: The cross icon can be used to erase the current record.•. Play:.Play.the.current.record•. Stop:.Stop.playing.the.current.record.• Record: Start a new record. If a record already exists, the new one is added at the end of the old

. one.

The slider above the logical record buttons can be used to move the current position inside the current.logical.record.

Once a logical record has been done, you can render it to a Quicktime movie. Simply go to the “Record” menu and select “Render Logical Record”. A dialog box allows you to set several different options.for.the.rendering..

First.of.all.you.can.choose.a.codec.using.the.pop-up.button.

Then you can set the resolution of the movie. Modul8 works only in 4/3 format, so the height of the movie is always proportional to the width. To specify the resolution you change only the width.

You.can.also.specify.the.frame.rate.of.your.movie..Higher.is.the.frame.rate,.smoother.is.the.animation.but.bigger.is.the.movie.

RE

CO

RD

ING

AN

D R

EN

DE

RIN

G

MAIN PANEL

01Main panel

VERSION 2.5


��

You don’t have to render the full logical record. The start and end times allow you to specify the time range.that.you.want.to.render.

Two sliders allow you to set the level of compression you want. Higher is the value better is the quality but.bigger.will.be.the.movie.file.

Before starting the render, you have to select the output file. You write the path by hand in the text field.or.simply.select.the.button.beside.the.text.box.to.specify.a.name.and.a.path.for.the.file.

Then simply select “render” and the movie will be rendered to a standard Quicktime file that can be used.in.any.other.application.

record To disk

Unlike.the.logical.record,.this.mode.directly.records.the.animation.to.a.movie.file.while.the.composition.is playing. This mode is much slower and is difficult to use for recording live events. You should use it only when.you.need.to.record.compositions.that.are.based.on.live.input.such.as.sound.capture.or.live.video.capture..

To start a record to disk, you simply select “Record To Disk” in the “Record” menu. A dialog box allows.you.to.set.several.different.options.for.the.capture.to.disk..

First.of.all.you.can.choose.a.codec.using.the.pop-up.button.

Then you can set the resolution of the movie. Modul8 works only in 4/3 format, so the height of the movie is always proportional to the width. To specify the resolution you change only the width. Please note that it will change the size of your output window, in order to capture it at the correct size.

You.can.also.specify.the.frame.rate.of.your.movie..Higher.is.the.frame.rate,.smoother.is.the.animation.but.bigger.is.the.movie.

Two sliders allow you to set the level of compression you want. Higher is the value better is the quality but.bigger.will.be.the.movie.file.

Before starting the render, you have to select the output file. You write the path by hand in the text field.or.simply.select.the.button.beside.the.text.box.to.specify.a.name.and.a.path.for.the.file.

Then simply select “Record” and the record to disk will begin. Once started, everything you do is added.to.the.movie.file.at.the.frame.rate.you.specified.in.the.dialog.box..When.you.want.to.stop.the.record,.simply go to the render menu and select “Stop Record To Disk”.

summary

In this chapter you learned how to record and render Modul8 compositions. The following points have.been.covered:

•. Modul8.has.two.different.record.modes:.logical.and.direct.to.disk• Both these modes allow you to render movie in size using different codecs and frame rates.• The logical record is the preferred mode unless you need to capture composition that uses live

input (sound capture or live video).

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

Modulesoverview.

The module architecture is one of the new exciting features of Modul8 introduced with the V2.0 and greatly extended since the V2.5. Basically, modules are small extensions that add new functionalities and new user-interface paradigms to Modul8. They are saved as small external files that can be shared between users on the GarageCUBE online library.

The real power of this architecture is in its full integration into Modul8. You don’t even need to be a programmer or special tools to create modules. They can be created directly from the inside of the application without even having to stop the playing animation. Actually you can even create modules while you.are.performing.

using modules

Using modules is pretty easy. You can access the modules from the “Module” menu. When you select the “Show” sub menu, the list of all the available modules is displayed.

Beside each module name a small icon shows the state of the module: when an orange arrow is displayed, it means the module is currently running. Modules are active only when they are running. As long.as.they.are.stopped,.they.won’t.do.anything.

To display a module simply select it in the module list. If the module is not already running, you can launch it by clicking on the blue arrow at the right/top of the module window. Once launched, the controls become active and the arrow icon becomes an orange “pause” icon. You can pause at any time the module.by.clicking.on.this.icon..

If you want to reinitialize completely a module you can select the “Restart” option in the “Module” window..In.this.case,.the.module.is.restarted.as.if.it.was.launched.from.the.first.time..

You can also stop and reset all the modules using the “Stop All” function in the “Module” menu.

You can close or minimize a module using the two buttons at the left of the window. Please note that closing.the.window.of.the.module.does.not.stop.it.

Modules.can.do.many.different.things,.so.the.usage.of.a.module.depends.a.lot.of.how.it.has.been.designed.and.for.what.purpose.

downloading and installing new modules

Modules are simple files saved in a folder called “Modules” beside the application. You can install a module simply by copying it to the “Modules” folder. The module will be available the next time you launch the.application.

GarageCUBE maintains also an online library of modules that can be browsed directly from the inside of Modul8. You can open the browser by selecting “Online Library” in the “Modules” menu.

At the right of the window is your current installed modules list. The left of the window allows you to access the online libraries of modules. There are currently two libraries that can be selected using the tabs:.

The GarageCUBE library: This is the official library of modules made by GarageCUBE. You can only download.module.from.this.library.

The public library: This is a 100% public library. Any user can upload and share its modules in this

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�8

library.

To get information about a module simply select it. A description of the module will appear at the bottom.of.the.window.

Because there can be many modules in these libraries, the browser is able to sort the list by name, author,.etc..Simply.click.on.the.column.title.to.resort.the.library..You.can.also.use.the.search.filter.to.display.only.the.modules.that.include.the.passed.keyword.

Once you have found an interesting module you can install it simply by selecting it and clicking on the “Install” button. The module is downloaded and added to your local library. The module is also ready to.be.used;.you.simply.have.to.start.it.

Once a module has been downloaded it is not immediately saved. It allows you to test modules without installing them. To save the new modules, simply use the “Save All Changes” function in the “Module” menu. If you downloaded some new modules and you quit Modul8, the application will ask you if.you.want.to.save.them.

The public library can also be used to share the modules you created. See “Sharing your module online” for more information.

Managing your modules

Because modules are simple external files, it is pretty easy to manage your module list. You can delete modules simply by dragging the files in the “Modules” folder to the trashcan.

Now the module editor includes also functions to add, remove or rename modules. You can open the editor by selecting the “Editor” item in the “Modules” menu.

Once open, you will see at the right of the window, your module list. At the bottom of the window, there.are.functions.to.add,.delete.or.duplicate.a.module..You.can.also.rename.a.module.by.double.clicking.on.its.name.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

sTandard Modules

This chapter describes the standard modules designed by the GarageCube team. Some of them are included.within.the.Modul8.application.while.some.should.be.downloaded.from.the.online.library..Please.not.that.this.is.not.an.exhaustive.list.

The modules can be divided into three main categories:

layer

These are modules that are layer related where all the parameters are dynamic. The displayed.content..shows.the.current.active.layer..It.also.means.that.deleting.a.layer.also.deletes.the.parameters.in.the.module.that.are.related.to.this.specific.layer.

all / Master

These modules work on a set of layers (or all layers) or on the parameters of the masters situated at the.bottom.of.the.main.Modul8.user.

Global

These are modules which give functionalities that cannot be included in the two previous categories. For.instance,.it.can.be.a.network.or.module.some.function.that.are.not.layer.related.

bPM (Global)

This module generates a time repetitive beat (BPM is for beat per minute) that can be reused by other modules like the module filter or the bpm router. It is very useful to synchronize effects or an automate tasks.based.on.music.tempo.

4

53

1

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�0

You can set the speed of the BPM directly with the pre-defined button (1),.by.entering.a.numerical.value.or.by.using.a.knob.that.can.be.easily.linked.to.midi.

You can also defining the speed of the BPM manually using the “TAP” button (�). This is a very intuitive way to synchronize your animation to the tempo of the music.

Also to synchronize the beat precisely to the rhythm you can press the “Synch” button, the “<” and the “>” button which allows you to move the beat lightly forward or backward.

It is also possible to synchronize the BPM using a midi clock*(�)..

A light sllows you to see the current tempo (�).

* You need a specific hardware or software, which sends midi clock messages to use this feature.

Note : Settings are not saved for this module.

rouTer (MasTer) and rouTer (layer)

These modules are very powerful tools to automate several parameters* of Modul8 using the current BPM.

1

98

4

A B2

53

6

7

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�1

To automate a control, use the “pick” button (1).and.then.select.it.in.the.main.user.interface.of.Modul8..

The name of the control will appear in the space under the “pick” button (�)..You.can.unlink.the.control.by selecting the name and then click on “remove”.

To active the routing, select the control you added (�) and then select the “play” button (�). Now you

can.change.the.curve.(�), the quantization (�),.the.start.and.end.points.(�).and.the.phase.to.generate.

offsets.(�).

The preference button (8) (exists only in the master version) allows you to define if you want your parameters to be saved in your project document or in the module itself (so your parameters will always be active when you open Modul8).

* For the layer version, it should be a layer parameter, while for the master it should be a master parameter. This is the only difference between the two modules: one has been designed to work with the active layer while.the.other.will.have.only.parameters.which.are.not.updated.when.the.active.layer.is.changed.

Note: In the layer version, the settings are automatically stored in your document when you save your project.

Warning: These modules are based on the BPM module, they work only if it is active.

Mask (Global)

This module works on an independent layer, which is in front of all the standard Modul8 layers and let you create.a.global.mask.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

1

5

7

8

9

10

3

2 4

6

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

This new layer allows several new possibilities (1):

Showing a layer only on your final output whilst still being able to see your composition in its original form in the preview. This can be very useful when you want to mask some areas of your image when your screen.does.not.have.a.standard.shape,.like.a.rounded.screen.for.example..It.is.also.very.useful.if.you.want.to.add.a.texture.over.the.composition.

Showing a layer only on the preview but not in the final output. This can be useful if you want to place marks.to.help.you.placing.elements.in.space.

Showing a layer in front of both the preview and the final output.

The module is made of the following parameters:

(1) Activating the mask in both the output and the preview

(�).Changing.the.transparency

(�).Changing.the.blending.mode.

(�) Changer the media speed (if it is a movie)

(�).Connect.the.speed.to.the.master.speed.in.order.to.have.a.speed.relative.to.it.

(+) The other parameters are divided in four areas which can be selected using tabs.

(�).Choosing.the.media

(�) Defining the position in space with the possibility of entering numerical values.

(8) Changing the post-colorize

(�) Changing the size of the media, where 1 means full screen. You can use bigger value using the numerical field.

(10) Changing the size in a differentiated way.

Note : The settings are saved in a Modul8 document.

cenTer (layer)

This module let you change the center of your layer. It is pretty useful when you want to do un-centered.rotation.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

The cross represents your layer. You can change its center simply by moving it.

Note : The settings are saved in Modul8 documents.

neTwork (Global)

This module allows two or more modul8 to be interconnected through an ethernet or wi-fi network. Basically each Modul8 will receive or/and send all the commands made by the users. It means that each Modul8.can.be.at.the.same.time.a.client.and.a.server..You.can.decide.what.parameters.are.sent.or.not.to.other.machines.

To use the network module you should have all your machines connected to the same local network. You.should.verify.that.they.are.connected.to.the.same.sub-network.using.the.information.in.the.module.

(�).

If it is not the case you should change your system preferences and restart the module (in the Modules menu «Restart»).

Then choose if your module should send, receive or both (1). You don’t need to target a specific computer,.all.the.actions.are.sent.over.the.network.

You can activate the reception filter (�),. which. allows. you. to. receive. only. some. keywords.. For.instance,.if.you.want.to.receive.only.the.master.actions..

Tip: If you are using a wi-fi network be sure to avoid using cryptography (WAP), which slows down a lot.data.transfer.

Note : Settings of this module are not saved.

1

2

3

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

PreseT (layer)

This module can be used to memorize and restore the parameters of your layers. It works as a bank of.predefined.settings.

a – Normal mode (by default) :

Simply.press.on.a.preset.button.(1)The new settings are directly apply to the selected layer.

b.–.Edit.mode:

To activate this mode, press on the edit button (�).

With.the.snapshot.buttons.(�).you.can.capture.the.parameters.of.the.currently.selected.layer..You.can.

give a name to the capture using the text field at the left (�).

With the snapshot parameters, you can filter what parameters should be captured. In this case only the chosen.parameters.are.applied,.without.modifying.the.other.settings.of.the.layer.

You.can.save.the.preferences.of.the.modules.in.your.global.settings.using.the.save.button.(�).The “reset all” button (�) erases all the setting and the “revert to saved” (�).let.you.revert.to.the.last.saved.settings.

1A B

4

6

3

2 5

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

Please.note.that.only.the.parameters.of.the.main.Modul8.interface.can.be.saved.using.this.module..Some parameters of other modules like the filters module can’t be captured with this module.

Note : The settings of the module are not saved in the document.

PreseT defaulT (layer)

Like the “Preset” module this module let you memorize the settings of a layer. However this time for using.them.as.default.values.when.a.new.layer.is.created.

If the module is activated, the memorized parameters are applied each time a new layer is created.

Capture.and.save.the.parameters.of.the.selected.layer..Clear.the.saved.parametersAn option which allows to use the same media set by default that the one of the last selected layer when a.new.layer.is.created.

Note : The parameters are automatically saved in the preferences of the module.

scraTcH (layer)

This module adds some functionalities useful for scratching and changing time position in a movie in a.more.precise.and.effective.way.than.the.main.Modul8.interface.

3

21

1

4

5

6

3

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

This module works only on one layer at the same time whatever you choose in the layer selection (1).

To scratch, you can use two different knobs (�):Absolute: The position of the beginning and the ending is relative to the beginning of the movie, just like in.the.Modul8.interface.Relative: It is an endless knob which let you forward and backward in the movie. In this mode, the speed

is defined by the “r.speed” buttons (�).

You can memorize up to three entry points in order to jump directly to a position using the knobs and the

“go” buttons (�).

You can forward or backward for one or five frames in your movies using the “frame position” buttons

(�).

Also you can change the playback speed and the stopping speed of your movie gradually using the

“movie speed” buttons (�).

Note : The settings of this module are saved in Modul8 documents.

Tip : If you need to control several layers simultaneously from this module you should duplicate the whole module.from.the.interface.builder.

slIde sHow (layer)

With.this.module.you.can.create.a.slideshow.for.each.layer.of.your.composition.This module always displays the parameters related to the selected layer.

1

3

5

2

6

4

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�8

Automated mode : Simply launch the slideshow using the play button (1).

Manual mode: Go forward and backward using the “previous/next” buttons (�).

You can choose the start and last media of the slideshow using the “from” and “to” fields (�). These

numbers represents the media* contained in your media set. The “get” button (�).let.you.get.the.currently.selected.media.

You.can.set.the.duration.between.each.media.change.using.the.knob.(�)..You.can.also.change.the.scale.

with the “1,10,30” buttons (�).

The “wait movie” button is useful when you want the movie to be entirely played before jumping to the next.one.

You can also activate a fade in/out transition (�).and.set.the.direction.of.the.slideshow,.including.a.random.mode.

Note : The settings of the module are saved in your Modul8 project.

* To know the number of a specific media, you can use the “info” button, at the left/op of the media win-dow. The number will appear at the left top under “media id”.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

fIlTer (layer)

This very powerful module allows the usage of several filters both internal (Modul8 filters) or external (CoreImage and FreeFrame*). This is a per-layer module, which means that each layer maintains its own filter.list.and.that.the.parameters.displayed.represent.the.selected.layer.

You.can.apply.up.to.four.different.filters.to.each.layer.using.the.tab.at.the.top.of.the.window.(1).Each one of these filters can be activated or deactivated quickly using the “Enable” button just above

(�).Selecting.and.applying.filters.:

You can use four different banks of favorite to organize your preferred filters (�). By selecting all, you can see.all.the.available.filters.

When.you.select.one.of.the.filter. in.the.list.(�),.the.filter.parameters.are.displayed.at.the.center.of.the.

window.(�)

1

5

4 6

8

73

9

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�0

Animation :All the parameters can be animated, either using a predefined speed relative to the master, either by linking them to the BPM.

Once you have selected a filter, choose one of the parameters that you want to animate in the list at the left

(�) and them click on “Animate” to activate it. You can choose the curve, the start and the beginning and

also invert the phase. Then, you can change the speed or base the animation on the module BPM (8).

Favorite.edition:

Select.the.edit.button.(�) to display the complete list of the filter. Then select one of the four favorites you

want.to.edit.(�).

Using the “add” button you can add the selected filter to the favorites and with “remove” remove it.

Select “Edit” to go back to the normal mode.

To add new freeframes in Modul8, copy your files to the Plug-Ins folder beside the Modul8 application. Then restart Modul8. Be sure that your FreeFrame plug-ins are compatible with your configuration. PowerPC only or Intel only filters work only on the same hardware. Only Universal filters work everywhere.

Warning: Because the FreeFrames filters are coming from different developers, they can compromise the.stability.of.Modul8..GarageCube.cannot.guarantee.the.stability.of.the.application.when.you.installed.these.plug-ins..

Notes : The settings of this module are saved into the document when the project is saved. The favorites are.saved.in.the.global.preferences.

TeXT (layer)

This module can be used to write and manipulate texts.

1 3

5

6

4

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�1

Each.layer.can.display.a.text.and.all.the.regular.effects.can.be.applied.to.the.text.just.like.for.any.other.media.

When.you.write.or.paste.some.text.in.the.text.field.(1),.the.text.is.automatically.applied.to.your.layer..You.

can.choose.the.font.by.selecting.its.name.(�),.or.in.the.favorites.list,.or.in.the.global.font.list.(�).

You.can.modify.the.resolution.in.pixels.of.your.text.using.the.corresponding.knob.(�).and.or.course.the.size of the representation using the standard layer parameters (scale.)

A shortcut let you also change the typeface using the standard, italic, light and bold buttons (�)*

Editing.the.favorites:

To add to the favorite, select the “ALL” tab (�) and then select a font and finally use the “Add To Favorites” button. You can remove it from favorites by selecting “Favorites” and using the “Remove From Favorite” button.

* As long as the typeface exists for this font.

Note: The settings of this module are saved in Modul8 documents.

TeXT subTITle (layer)

This module is able to store five different texts and get them displayed as subtitles in the layers.This module works with the text module.

You can launch the sub-titling with the “Play” button (1).Once you have chosen one of the five stored texts (�).you.can.edit.it.directly.in.the.text.field.

Use.the.knob.to.change.the.scrolling.speed.(�).

All the other settings regarding the text can be changed in the text module itself.

Note : The parameters (1),(�),(�).are.different.for.each.layer,.while.the.associated.texts.are.common.to.all.the.layers.

The settings of this module are saved in Modul8 documents.

1

2 3

4

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

TeXT cHanGe (layer)

This module can be used to change automatically the text of one or several layers using a word list.A colon must separate the words.

You can launch the animation using the “PLAY” button (1).You.can.modify.the.list.directly.in.the.text.field.(�).You.can.change.the.display.speed.(�).The random mode (�).can.be.used.to.change.the.display.order.randomly.The fade mode generates a cross fading during text transition.

All the other settings regarding text can be done in the Text module itself.


TIMe and daTe (layer)

A simple module which displays the time and date in a a layer.

(1) Select the display mode (24h, 12h, etc.)

(�).Select.run.to.display.the.time

All the other settings regarding text can be done in the Text module itself.Note: The settings of this module are saved in Modul8 documents.

1

4

3 2

1

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

counT down (layer)

A simple module that displays a time count down in a layer.

(1).Launch.the.count.down

(�) Reset the count down

(�).Change.the.duration

(�).Display.a.text.when.the.count.down.is.finished

All the other settings regarding text can be done in the Text module itself.

MovIe TIMe (layer)

This module can be used to change the time position or the time speed of a movie relatively to the sound.input..

You can activate or deactivate the module for every layer with the ON button (1).Time position (�).The movie jumps to the end when the sound is very strong and to the beginning when it is very weak.

1

3

4

2

1

2

3

4

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

The “AMP” button can be used to modify the amplitude of the effect.

Speed.(�)The speed of the movie is accelerated when the sound is strong, or decelerated when the sound is weaker.The “AMP” button can be used to modify the amplitude of the effect.

Random (�)Change.the.position.in.the.movie.randomly.The FREQ button can be used to adjust the speed of these changes.

Note: The module use the sound input of your computer, don’t forget to configure it in your system. Also be.sure. to.set. the. input.sound. level. inside.Modul8,.which. is.deactivated.by.default..You.can. find. this.setting.at.the.right-bottom.of.the.main.user.interface.

The settings of this module are saved in Modul8 documents.

crossfader (MasTer)

A simple module, which can be used to automate the transition between the group A and the group B when the cross-fader is activated.

(1) Setting the speed of the transition in seconds. Set zero for cut.

(�) Press A and B to go from one group or another

Note : settings are not saved.

1

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

sHake (all)

A simple module that shakes all your layers.

You.can.set.a.continuous.shake.or.a.push.shake.(1).Choose.the.level.and.the.speed.of.the.vibration.(�).Select the group, which should receive the effect (A for top layers and B for bottom layers) (�).

You can also select the vibration axis: vertical, horizontal and along the Z-axis.

Note: With a very low speed and a very high level this module can be user to generate aleatory motion.


randoM croP (layer)

A simple module, which animates the cropping.

Activate or deactivate the module per layer.Select the axis (x vertical, y horizontal)

(�) Choose.the.speed

13

4

2

1

2

3

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

MovIe randoM fraMe (layer)

A simple module that changes the time position randomly in your movies.

Activate or deactivate the module per layer.

(�).Choose.the.speed.with.the.knob,.change.the.speed.with.the.1,2,3.button.

1

2

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

PaInTer (layer)

The painter can be used to draw to a layer and even create simple stop motion animation.

1

5 2 3 7

846

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�8

Draw:

Choose the size of your brush (�),.its.color.(�).and.the.type.(�).Then you can draw to the canvas (1).and.result.is.automatically.sent.to.the.selected.layer.

To erase select “erase” (�), then you can select the using the picker (the color box beside the color

selection)(�).You can draw to up to 10 different layers (these are internal painter layers) that you can select in the layer

list.(�).To erase your image you can erase all or only one layer (�).

Animation:

You.can.store.your.picture.in.order.to.create.an.animation..Each.time.you.click.on.add.(8).a.new.image.is.added to the animation (the image is added at the end).

With.the.speed.knob.(8).you.can.play.back.and.choose.the.speed.of.the.animation.in.your.layer.

With.the.pos.knob.(8).you.can.move.inside.the.animation.linked.to.the.Modul8.layer..You.can.erase.an.

image of your animation using the “rem” button (8)..You.can.also.erase.the.whole.animation.using.the.reset.button.

Warning.:. It. is.not.possible.to.add.an. image.at. the.middle.of.your.animation.or.rework.your.animation.yet.

Note : Your drawings and animations are saved in the Modul8 document.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

PosT colorIZe PIcker (layer)

The post colorize picker is a module which let you work on the post colorization of your layer with more.advanced.representation.than.with.the.standard.Modul8.interface.

(1).Choose.if.you.want.to.work.on.modulation.or.on.additive.You.can.change.the.red,.green.blue.just.like.in.Modul8.You.can.also.work.on.the.color.using.the.tint,.saturation.or.luminosity.You.can.also.modify.the.color.by.clicking.directly.on.the.color.gradientsIf.you.click.on.the.color.box,.you.can.access.the.system.color.picker.

(�) Reset all your parameters.

1 6

5

2

3

4

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


80

cHroMakey (layer)

This module can be used to generate a color key that will be transparent in your media. It can be used for.instance.to.extract.a.character.filmed.in.a.blue.box.

(1) Activate the key using the ON/OFF button

(�,�,�) Tools to define the color.

(�).Display.the.color.key..You.can.click.on.it.to.access.more.advanced.functions.including.a.picker.

(�).You.can.use.this.to.set.the.key.tolerance.

(�) This can be used to blur the transparency layer (alpha channel).

(8) These tools can be used to adapt the alpha value in order to increase the quality of the transparency border.

1

5

2

3

4

6

7

8

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


81

creating modules

While using the modules from the other users is cool, creating your own modules is very exciting. A module.allows.you.to.manipulate.keywords.that.represent.functionalities.of.Modul8..It.works.a.bit.like.a.client/server relationship where Modul8 is the server and the module the client. The client gets and sets values that are managed by the server. Then the server sends events to let know the client that something has.been.changed.on.his.side.

What.can.be.done.with.modules?

•. Manipulate.the.current.Modul8.controls.using.different.user-interface.paradigms.• Adding new animation effects that are based on the layer position, scale, rotation and the

. existing.filters.• Automate and animate any functionality of Modul8.• Shortcut the current Modul8 layer paradigm (manipulating several layers as if it was one).• Generating dynamic content (like the painter module)

What.cannot.be.done.with.the.current.implementation?

• Manipulating a media at the pixel level (adding low level filters).• Adding more objects that it is permitted by the current user interface (ten layers for instance).

While.it.is.not.a.requirement,.all.modules.should.have.a.user-interface..Modul8.includes.an.interface.builder that is very easy to use. Advanced modules can also use scripting to implement new functionalities. Nevertheless, it is possible for simple module to connect directly their controls to Modul8 functionalities without.even.having.to.write.a.line.of.script..It.allows.you.to.create.new.user-interface.paradigms.without.having.to.learn.scripting.

Modules creation is done through the module editor that can be open from the “Modules” menu.

The module editor is divided in two main areas: at the right is the list of installed modules. At the left is.the.module.editor.

You can edit a module simply by selecting it in the module list. To add a new module simply use the add.button.below.the.module.list.

Please note that the changes are not saved until you select “Save All Changes” in the “Modules” menu..If.you.modified.some.modules.and.you.quit.Modul8,.the.application.will.ask.you.if.you.want.to.save.them.

layer contextual Module

Since.the.V2.5,.Modul8.offers.two.kinds.of.module:

Master.moduleLayer.contextual.module

When you create a module, by default it is always a master module. It means that the module (unless some behaviors are scripted by hand) ignores the state of the layers. For instance, if you change the current layer, it will not affect the content of the module. Now suppose that you want to create a module, which. lets. the.user.sets.different.options. for.each. layer,. reflecting.different.behaviors..For. instance,.an.auto-rotate.module.should.allows.the.user.to.specify.if.he.or.she.wants.it.to.run.for.a.specific.layer.and.at.what.speed..In.this.case,.you.will.create.a.layer.contextual.module..In.this.mode,.the.module.contains.an internal copy (or instance) of itself for each layer. The user-interface is automatically updated when the current.layer.is.changed.in.order.to.reflect.the.state.of.module.for.the.active.layer.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

Creating a layer contextual module does not require anything special. All you have to do is to set the “Layer Contextual” flag in the module attributes. Modul8 automatically takes care of everything.

Interacting with Modul8

As written before the module architecture follows a client/server metaphor where the module is the client.and.the.Modul8.application.the.server..Whatever.you.plan.to.do,.from.simple.user-interface.mapping.to.scripting,.it.always.follows.the.same.schema.

The communication is done through simply keywords each one representing functionalities or internal data of Modul8. For instance the keyword that is linked the additive post-colorize red value is “ctrl_layer_color_additiveR”. Suppose that you want to do a module that changes the red value of the additive color, all you have to do is to send a new value to Modul8 with the “ctrl_layer_color_additiveR” keyword. Because this keyword corresponds directly to a control of the user-interface, once changed the main.user-interface.is.automatically.updated.to.reflect.the.new.value.

This is the easier way to interact with Modul8: modifying the controls of the main user-interface. Modul8 supports also “direct” keywords that have no representation in the main user-interface. These keywords.can.be.used.to.access.special.features.of.Modul8.or.to.add.effects.that.do.not.modify.the.main.user-interface..For.instance,.if.you.want.to.do.an.auto-rotate.effect,.you.can.simply.animate.the.rotation.knob.of.the.main.user-interface..Unfortunately.if.you.do.it.this.way.the.user.won’t.be.able.to.use.the.knob.anymore, because it will change all the time. Also suppose now that you have two modules that use the rotation of the layer to create a motion effect. They will try to use the same knob, causing a conflict that will.result.with.only.one.module.working.correctly..

Direct.keywords.resolve.this.problem.by.being.module.local..In.other.words,.each.module.keeps.a.copy.of.its.direct.keywords.and.then.merges.them.together.before.they.are.applied.to.the.final.composition.

For instance we saw before the post colorize red additive keyword: “ctrl_layer_color_additiveR” the corresponding keyword for the direct mode is “direct_layer_color_additiveR”. It works exactly the same.with.two.main.differences:.first.it.does.not.modify.the.main.user-interface;.then,.if.several.modules.manipulate.the.color.additive.of.a.layer,.the.module.mechanism.will.correctly.merges.the.result.of.all.the.changes..

For.this.reason,.most.of.the.time.it.is.better.to.use.direct.keywords.when.possible.

using the keywords

As we saw in the precedent chapter, the keywords are grouped in two main families: the direct keywords.and.the.control.keywords.

The direct keywords modify directly a parameter of Modul8 and they resolve automatically the conflicts of several modules accessing the same keyword. The direct keywords always begin with the “direct” name.

The control keywords modify a control of the main user-interface of Modul8. Once the control is modified it updates automatically the composition to reflect its new value. The control keywords always begin with the “ctrl” name.

The name structure of the keywords follows a hierarchical structure. For instance the “direct_layer_alpha” keyword that allows you to change the transparency of a layer is made of three components:

direct:.It.is.a.direct.keywordlayer: It is layer relative (by opposition of a master controller)alpha:.Its.functionality,.changing.the.alpha.channel.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

The bottom line is that keywords can be represented as a hierarchy. For instance, all the keywords that are direct and layer relative begin with “direct_layer”.

There are many keywords in Modul8 and many more will come in future versions. A simple way to see what keywords are available is to open the keyword browser from the “Modules” menu.

The browser automatically represents the hierarchical structure of the keywords. So for instance if you click on “direct” you can see all the direct keywords and so on. When you select a keyword you can see its description at the bottom of the window. The browser can also be used to insert keyword in a script or.in.user-interface.builder.

Of course, to each keyword corresponds a value. The value type (if it is a floating point number, an integer or a text) depends of the keyword type. Now most of the controls work with floating point numbers going from 0.0 to 1.0. For example, if you want to change the transparency of a layer to 50% you can pass 0.5 to the “direct_layer_alpha” keyword. If you pass 0.0, the layer becomes 100% transparent, and for 1.0 it.becomes.entirely.opaque.

There are two ways to modify a keyword:By using the interface builder and connecting your control directly to a keyword.By using scripts.

Most.of.the.keyword’s.value.can.be.modified.or.read..However.some.are.read.only.or.write.only..See.the.next.chapter.to.know.how.to.set.or.get.the.value.of.a.keyword.

The keyword families

Keywords are grouped in families. As described in the two precedent chapters, the two mains groups are.the.direct.keywords.and.the.control.keywords.

For.the.controls,.four.sub-groups.follow:layer: These controls are contained in a layer.LayerStack:.Controls.related.to.the.layer.stack.master: These are master controls.ui: These are controls that allows to access main user-interface parameters.

Then, each of these families has sub-groups like color, position, rotation, etc. The best is to use the browser.and.see.the.description.to.learn.what.keyword.and.what.group.does.what.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

The user-interface builder

Every module has a window. Even a module without a user-interface (entirely made of scripts) will have.its.own.window..If.your.module.does.not.include.any.user-interface,.it.would.be.a.good.idea.to.at.least.put.a.text.caption.in.the.window.to.explain.what.your.module.is.supposed.to.do.

By default the module editor shows the user-interface of the module when it is open. The module editor.is.made.of.three.main.components:

• The user-interface builder• The script editor• The information describing the functionality of the module

You can move from one section to another using the tab at the bottom of the editor (Visual, Scripts, Info).

The user-interface builder is the first main component of the module editor. Most of the time your modules.will.have.at.least.a.minimal.user-interface.and.this.is.where.you.will.create.it.

The creation of your user-interface is pretty easy. When you create a new module you can see its empty window in the editor. At the top of the editor, you can see the information relative to the selected object.in.the.window..If.you.click.on.the.module.window.title.in.the.editor.it.shows.the.global.information.relative to the module such as the window size.

At the bottom of the editor you can find all the control types. The control types are divided in five sections:.

•. Controls:.simple.controls.such.as.buttons,.etc.• Text controls: text controls such as text field, etc.•. Shapes:.decoration.objects• Tools: editor tools•. Groups:.managing.groups.of.objects

Adding a new control is as easy as dragging and dropping it in the module’s window. Once a module has been added just click on it to edit it. You can drag it in the window to move it to a new place or resize it by clicking on the right/bottom box of the control selection. You can select several controls by clicking on them and pressing the Shift key or simply by clicking in the background and dragging the mouse. To remove a control, simply select it and press “Command + Backspace” or select “Delete” in the edit menu. The control is immediately removed.

When a module is selected, all its attributes are displayed at the top of the editor. The control settings are.divided.in.three.parts:

• Attributes: Control main attributes.•. Key word connect: Direct connection of the control to a Modul8 keyword (without scripting).•. Script:.Script.related.options.

While the options of the “connect” and “script” sections are nearly similar for all controls, the attributes are.really.specific.to.the.control.type..For.example,.a.button.does.not.have.the.same.attributes.than.a.pad.or than a text field. Nevertheless all the controls have at least a name that can be set in the attributes panel. The name is useful to identify a control from a script.

In the Modul8 model, almost all controls (with the exceptions of the decorator objects) represent one or.more.values..Most.of.the.time.these.values.are.floating.point.numbers..For.instance.controls.like.knobs,.sliders or number fields are used to represent a value that can be edited by the user. Now some other controls can represents more than one value. Typically the color picker represents three values: one for

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

the.red,.one.for.the.green,.one.for.the.blue..In.this.case,.each.value.can.be.mapped.to.a.different.keyword..Most of the time you will connect these values to a RGB color attribute, however there is not limit in how you can use the output of the control. It is possible for example to connect the color picker to the x,y,z rotation.angle.of.the.layer..In.this.case,.changing.the.red.will.change.the.x.angle,.changing.the.green.will.change the y angle and changing the blue, the z angle. This example shows the flexibility of the module mechanism.

The global attributes

When.you.click.in.the.window.background.or.on.the.window.title.in.the.editor,.the.global.attributes.of.the.module.appear.at.the.top.of.editor..Currently.only.the.following.attributes.are.available:

Width/height: the window size of the moduleLayer.contextual:.when.this.flag.is.set,.the.module.contains.an.internal.copy.of.itself.for.every.layer..

See the “Layer Contextual Module” chapter.

The controls

The module architecture supports many different types of controls. Each control type has its own attributes and behavior. This section contains a description of every control available in the current version of.the.interface.builder.

The slider

The slider allows the user to set a floating-point value. The range of the value is specified in attributes using the minimum/maximum values. Typically the range goes from 0.0 to 1.0.

The attributes of the slider are:

•. Default.value:.the.default.value.to.set.when.the.module.is.launched.• The minimum value: the value when the slider is empty.• The maximum value: the value when the slider is full.

The knobs

Knobs represent a floating-point value in a specified range, just like sliders.

There are two different kinds of knobs: one that allows only a rotation from the minimum value to the maximum value and another one that is entirely circular (it loops from the minimal value to the maximal value). The circular mode is useful for representing angles while the standard mode works more like a slider..

Both knobs have the same attributes than the slider:

•. Default.value:.the.default.value.to.set.when.the.module.is.launched.•. The minimum value: the value when the knob is at its minimal rotation.• The maximum value: the value when the slider is at its maximal rotation.

For.a.circular.knob,.maximum.and.minimum.values.are.nearly.at.the.same.rotation.

The buttons

There are three kinds of buttons: the push button, the checkbox and the radio button. While all these buttons are supposed to work differently, they have all the same attributes. The main difference is the way they are initialized and they representation. When you create a new checkbox, its attributes are automatically.set.in.toggle.mode..However.it.is.possible.to.set.a.push.button.in.toggle.mode.for.instance..

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

Now for the clarity of your user-interface, try to use the button as they are supposed to work:

• The push button: send an action• The radio button: mutually exclusive options• The checkbox: on/off option

The attributes allow you to associate three different values to a button:

• The down value: It is sent when the button is pressed• The up value: it is sent when the button is released• The continue value: it is continuously sent as long as the button is pressed and only if the

“continuous” flag is set in the option.

The other attributes are:

• Selected: Is the button selected by default (works only in toggle or mode).•. Continuous:.Enable.the.continue.value.• Toggle: Set the button in toggle mode.• Caption: The caption of the button.

The “Exclusion group” attribute allows you to group mutually exclusive buttons such as the radio button..In.other.words,.all.the.radio.buttons.in.a.module.that.has.the.same.exclusion.group.name,.are.mutually exclusive (when the user selects one, it deselects another one). If you want to have several groups.of.radios,.simply.give.a.different.exclusion.name.for.each.group.

The “Show Media” allows you to transform your button into a media preview button. See the “media buttons”.

The media buttons

A media button is a standard button, which displays the thumbnail of one of the media in the preview panel.instead.of.its.standard.shape..You.can.transform.a.button.into.a.media.button.simply.by.setting.in.the Show Media option the media number going from 1 to 128 (where 1 is the first media of the first set and 128 the last media of the last set). If you set 0, the button will display its regular shape.

The color pickers

There are three types of color picker today: One to select an RGB color, one to select a unique value in.a.gray.scale.and.the.last.one.which.allows.you.to.open.the.system.standard.color.picker.

The main difference between the fpickers is the number of value they send. The RGB picker manages three different values (see “Connecting controls to Modul8 keywords” for more information) while the gray scale, only one. The system picker is able to manage up to four values (red, green, blue and alpha). Please note.also.that.the.first.pickers.send.values.immediately.and.do.not.show.the.last.value.that.has.been.set..They really send immediate actions just like a button. Their values are always in the range of 0.0 to 1.0, where.0.0.is.black.and.1.0.is.white..Color.pickers.do.not.have.special.attributes.

Unlike.the.first.two.pickers,.the.system.color.picker.displays.the.last.selected.value.in.a.box..When.the.box.is.selected.a.dialog.box.is.open.to.let.the.user.pick.a.color.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

The �d pad

The 2D pad allows the user to specify two values X/Y on a 2D pad. Dragging a cross over the pad modifies the values. The pad can be used typically to move an object on a plane or to edit two values simultaneously (two effects for example).

The pad works with two floating points values. These values works like for a slider, with the initial default value and the minimal, maximal values for both X/Y axis.

The bottom/left represents the minimal value where the top/right represents the maximal values.

The draw view

This control is a very advanced control, which allows a user to generate images dynamically. It can be to create control with custom shapes or to generate images that will be sent to the composition. This control.can.be.used.only.from.the.scripts.

The captions

Captions are simple texts that cannot be edited by the user. There are two kinds of caption, the standard one that uses the Modul8 font and the text one that uses the system font. The text caption is useful.when.you.want.to.write.texts.in.languages.that.cannot.be.represented.by.the.Modul8.font..

Text and numeric fields

The text and numeric fields allow the user to enter by hand a number or a text. The numeric field works.with.floating.point.values..You.can.specify.the.minimum.and.maximum.values,.plus.the.default.initial.value.

The text field has different attributes. First you can enter a default text if required.

Also the text field includes two different settings:

• Accept line feed: When not set, the field exits when the user presses the return key. When set, . the.return.key.insert.a.line.feed.

•. Live:.When.set,.the.text.is.resent.each.time.to.the.script.each.time.it.is.modified..When.it.is.not... set,.it.is.sent.when.it.is.validated.or.the.user.exits.the.field.

The text list

This control can be used to represent a text list. There are several ways to initialize a text list. When you select the “Init With” attributes, you can set a list of text separated by a coma. For instance: red, green, blue. It is also possible to initialize it automatically with the list available font in the system. If you write scripts you can initialize it also dynamically (see the Script chapter).

The text list sends the user selection as its value. The user selection can be represented in three different.ways:

• Abs. Index: The value is the index in the text list. If there are 10 text in the list the value goes . from.0.to.9.

• Prop.Index: The value is a floating point in the range of 0.0 to 1.0 where 0.0 means the first . element.is.selected.and.1.0.the.last.

• Text: The value is the selected text.

shapes

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


88

The shapes allow you to use decoration element to your module. Basically it allows you to include surface and lines to your module. Surface can be round rectangle or box. The lines can be dashed or filled.

Tools

The tool section does not contain objects but tools that allow you to re-arrange the user-interface. There are currently two functions useful to change the display order of the elements:

• Bring to front: Bring the selected objects to the front.•. Send.to.back:.Send.to.back.the.selected.objects.

connecting controls to Modul8 keywords

It.is.possible.to.connect.controls.directly.to.the.Modul8.keywords.without.writing.scripts.allowing.the.creation.of.new.user-interfaces.pretty.easily.

To connect a control to a Modul8 keywords you need to select the module and then the “UI Connect” tab.at.the.top.of.the.editor.window.

Basically, each control can be mapped to up to 10 different keywords. You select the map at the left of the “UI Connect” section. For example you can do a slider that at the same time change the blur and the saturation. In this case you will use the map 1 and the map 2 to creation to connection. As long as you need.only.one.map,.you.don’t.have.to.use.the.map.popup.

Under. the. map. pop-up. is. another. pop-up. that. represents. the. value. of. the. control. you. want. to.connect..While.some.controls.like.the.slider.simply.represents.one.single.value,.some.other.like.the.pad.may.represents.two.or.more.values..In.this.case,.each.value.can.be.mapped.to.a.different.keyword..For.example.if.you.create.a.pad.you.will.have.in.the.pop-up.the.x.and.the.y.value..You.can.choose.to.connect.the.x.to.the.blur.keyword.and.the.y.to.the.saturation.to.modify.the.two.values.simultaneously.

Then you have to choose to what keyword you want to connect the control value. The “to” field allows you.to.enter.the.name.of.the.keyword,.however.it.is.a.lot.easier.to.use.the.keyword.browser.or.the.picker.

The picker allows you to directly pick a keyword in the main user interface of Modul8. Click on pick, select.for.instance.the.additive.color.slider.and.that’s.it,.the.connection.is.done.

You.can.also.use.the.browse.button.if.you.want.to.choose.a.keyword.by.name.or.a.keyword.that.cannot.be.picked.

Once the keyword has been set you can choose to what layer you want the map to be effective. Possible.values.are:

All layers: The control changes all layers simultaneously.1-10 layer: The absolute layer number.Active layer: The current selected layer.

The last attribute is the “expression”. This is a powerful function that allows you to enter a mathematical expression that is applied to the value before it is sent to the keyword. By default it is set to “value=value” which means the value is sent as it is. However you may want to create several maps each one sending a value that is normalized in a different way. For instance to multiply the value per two, simply set “value=value*2”, etc.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


8�

a simple module examples

In this chapter, we will create two simple modules without scripting (see the “Scripting” chapter for scripting samples). The first module is a simple module that allows you to change the additive post-colorization and the second one will allow the modification of two effects simultaneously using a pad.

a colorize module

Creating a simple colorize module is very simply and can be pretty useful.

First of all, open the module editor and click on the add button. Then give a name to your module (“Colorize” for instance).

The first step is to add the required controls. We will begin with the rgb color picker. Go to the “Controls” tab at the bottom of the editor and drag the rgb color picker to the module window.

Once added, move it and resize it until it is big enough. Keep a bit of room so we can also add a gray slider.later.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�0

Once added select it and go to the “Keyword Connect” section at the top of the editor.

Now we are going to connect the RGB values to the active layer. By default the “red” is selected in the pop up value. So we are going to connect the red value to the red additive post-colorize. Click on the pick button and select in the main user-interface the red additive slider in the post-colorize area (at the right top of the window).

For the “In:” field, select “Active Layer” so it will send the value to the active layer:

Now the red component is connected and should work. Let’s try it. Go to the module menu and select show “Colorize”. Click on the arrow button at the top/right of the module to start it.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�1

Click.in.the.color.picker.and.examine.the.red.additive.color.changing:

As you can see only the red component is changing. Now we want to be able to change also the green and the blue. Go back to the editor. In the value pop-up just below the “Map” pop-up there is the “red” value that is selected. Click on the pop-up and select the “green” value. Once you can see the keyword is now empty. This is because each value has a different connection. Click another time to pick and select the green slider this time. Also do not forget to select the “Active Layer” in the “In:” pop-up. Now the green is connected:

All the modifications are entirely dynamic. So you can immediately try the module to see if the green component.is.also.changing.

You should be able to connect the blue component by your self now. Once it is done you can modify the.three.additive.sliders.of.the.active.layer.with.picker.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

Now we are going to add a gray picker to modify the three additive sliders at the same time, changing the luminosity of the layer. Add a gray picker beside the RGB color:

Go back to the UI connect tab. As you can see in the value pop-up you don’t have the red, green and blue values but only “level”. This is because this control exports only one value. However what we want is.to.set.this.value.to.three.different.keywords.so.we.can.change.the.red,.the.green.and.the.blue.additive.color.with.only.one.control.

To do this, we need to use the maps. Basically we are going to map three times the same to the three-color.keywords.

So.first.let’s.connect.the.red..Use.the.pick.button.and.select.the.red.additive.slider,.just.like.you.did.before. And then select the “Active Layer” in the “In:” pop-up. You should have this:

You.can.also.try.the.module.right.now.to.see.what.does.the.gray.picker..It.should.modify.only.the.red.additive.color.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

However what we want is to modify the three values. So select the “Map 2” in the map pop-up. And now.connect.the.green.slider:

Now the gray picker changes the red and the green. Go to the “Map 3” and connect the blue keyword. This time it is done. You can change the additive color just as if it is one luminosity slider.

a pad effect module

In.this.example,.I.want.to.be.able.to.use.a.pad.that.changes.both.the.saturation.and.the.contrast.effects.

First of all, create a module called “ColorPad” and then add a pad control:

By default, the pad attributes are set to work from 0.0 to 1.0. It is perfect because like most of the Modul8 keywords, both the saturation and the contrast effects are set using a normalized value from 0.0 to.1.0..So.we.won’t.have.to.change.the.attributes.

Go to the “UI Connect” tab. In the value pop-up you can find “x” and “y”. It represents the two axis

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

of the pad. We are going to connect the contrast to the X and the saturation to the Y.

To do that use the keyword browser and select: ctrl_layer_pixelFX_contrastLevel.

Now the keyword to change the contrast level is linked to the x value. Let’s do the same with the other axis. Select the “y” value and then use the browser to select this keyword: ctrl_layer_pixelFX_saturationLevel.

Now let’s try our module. Go to the module menu to show the “ColorPad” menu. Launch it using the “arrow” icon at the top/right of the window.

As you can see when you drag the mouse in the pad, both the saturation and the contrast level knobs.are.modified.depending.of.the.axis..However.we.still.have.a.small.problem..If.the.saturation.or.the.contrast.effects.are.not.enabled.in.the.main.user-interface,.their.level.will.be.changed.but.the.effects.won’t.be.applied.until.you.select.the.effect.by.clicking.on.the.tab..While.it.is.an.acceptable.way.to.implement.it,.it would be a nice to be able to turn on the effect when it is to a non-zero value and to turn it off when it is at zero.

Actually this can be done pretty easily. Both the saturation and the contrast effects have a keyword to turn them on/off. These keywords expect to receive True or False value. The convention is that any value that is non-zero is considered as True and zero as False. This is good new for our effects because this is exactly what we want. When the pad is at zero, we want the effects to be turned off. And when it is at anything but zero we want the effects to be turned on.

Now let’s use a new map for this purpose. Select the “Map “ and for the x value select the “ctrl_layer_pixelFX_contrastOn” keyword. Be sure to link it to the x value and not the y value, or it won’t work properly:

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

Now do the same for the y value but with the “ctrl_layer_pixelFX_saturationOn” keyword:

Go back to the module and try it. As you can see when one of the axis reaches zero the effect is turned off. In the following capture, the x is at zero, so the contrast is off:

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

And when it is not at zero, it is turned on:

This module is working perfectly but there is still a small problem. All the maps are done directly on the.active.layer..It.means.that.when.the.active.layer.is.changed,.the.module.is.not.updated..For.a.module.like.where.all.the.functionalities.are.layer.contextual.it.would.be.better.if.it.has.a.different.state.for.every.layer. This can be done very easily. All you have to do is to set the layer contextual option. Click on the background of the module (or on the title) to see the module global preferences in the editor. Then select the layer contextual checkbox. That’s it. Now your module will have a different state for each layer. When the.layer.is.changed,.it.is.automatically.updated.to.reflect.the.changes.

These two examples show you the incredible flexibility of the module system. And this is without even having.written.a.line.of.script.

scripting

Modul8 integrates a complete scripting environment. The scripting language is Python. A brief introduction.to.this.language.is.included.in.this.documentation,.however.for.a.more.advanced.tutorial.and.for.the.complete.reference.go.to.the.official.python.web.site:

http://www.python.org

Beside the scripting language it is important to understand what is the Modul8 scripting model. Modul8.is.a.multi-threaded.application..It.means.that.several.tasks.can.be.executed.simultaneously..For.example.while.a.pixel. filer. is.applied,.new.frames.can.be.rendered.on.screen,.new.movie.data.can.be.streamed.from.the.disk,.etc.

So how scripts are executed in this context? The scripts are linked to the rendering thread. So what is the.rendering.thread?.It.is.the.place.where.the.on-screen.animation.is.achieved..In.other.words,.the.scripts.are.executed.between.the.on.screen.render.of.the.new.frames..

For.instance,.typically.the.rendering.thread.follows.this.schema:

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

A) Call the required scriptsB) Animate and prepare the object (rotation, scale, …)C) Render a new frame to the screenBack to A)

It.means.that.a.script.will.never.be.executed.at.the.same.time.than.a.new.frame.of.the.animation.will be generated. And this is a good thing, because it allows the scripts to be synchronized with the animation.. It.means.also.that. if.your.scripts.do.a. loop,.new.frames.won’t.be.rendered.until. the. loop. is.finished..It.is.very.important.to.understand.that..You.can’t.animate.an.object.by.creating.a.loop,.because.no frames will be rendered until the loop is finished. To animate objects you have to use special scripts called “PeriodicalEvent”. This will be covered in the next chapters.

So how the scripts are connected to Modul8 ? Basically it exists several script types. Each script type handles.a.specific.event.in.Modul8..For.example,.you.have.a.script.type.that.is.called.each.time.a.midi.value.is.modified,.or.when.a.module.is.launched.for.the.first.time,.or.when.a.control.of.the.user-interface.is.modified.

Each module implements its own list of scripts. All you have to do is select the required script type and write your script here. They will be called automatically when the corresponding event occurs.

a brief introduction to Python

Python is a pretty easy language to learn. This chapter gives you a very short introduction to Python in.the.context.of.Modul8.

Python.is.a.line-oriented.language..It.means.that.each.line.defines.a.sentence..For.example,.here.is.a.simple.python.program.that.prints.two.message.to.the.console.

print “hello”print “world”

The first like is executed and then the second one. The “print” keyword is a special function of Python that print a message to the console. This simple script prints “hello” and then “world”.

The variables in Python are simply defined by assigning them a value. You don’t have to define a type (if it is a floating point, an integer or a string). It is implicit.

For example, you can define the variable ‘i’ this way:

i=0

In this case “i” is created with the value of zero. You can print the value of ‘i’ this way:

print.i

In.this.case.it.simply.returns.0..In.Modul8.you.can.see.the.result.in.the.console.

There are two important functionalities in every language: loops and conditions.

LoopsLoops.in.Python.are.very.easy.to.define..For.example,.a.10.iterations.loop,.can.be.written.this.way:

for i in range(0,10):. print.i

Let’s decompose these two lines. The first line defines the loop. The “range(0,10)” defines a loop that

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


�8

starts at 0 and does 10 iterations. The variable ‘i’ is used as an index during the loop iteration. During the first iteration it is equal to 0, then to 1, and so on. At the end of the line you can see the ‘:’ character. In Python.it.defines.the.start.of.a.block.of.expressions.

Every.language.needs.a.way.to.define.an.expressions.block..In.this.case.it.is.used.to.define.what.instructions.are.part.of.the.loop.and.where.the.loop.ends..In.Python,.expressions.blocks.are.defined.using.indentation by inserting “tabs” characters at the beginning of the line. In the precedent example, the block has only one line; it is the “print i” instruction. As you can see the print instruction does not start at the beginning.of.the.line..

Now if I add a new line like that :

for i in range(0,10):. print.iprint “end”

As you can see the new print is at the beginning of the line. It is after the “for” block and will be executed only once the loop is finished. The output of this script will be:

0123456789end

conditionsConditions are very easily defines too. The ‘if’ can be used to define a condition blocks:

if i==0: print “i is zero”else: print “i is not zero”

In this case two expressions block are defined but only one will be executed. If I is equal to zero the first one is executed, else it is the second one.

Of course it is possible to insert new expression blocks in existing expression blocks. For example:

if doloop==1: for i in range(0,10):. . print.ielse: print “bye bye”

In this example, the loop is done only if the ‘doloop’ variable is equal to one. As you can see the loop block is in the first condition block. If ‘doloop’ is not equal to 1, “bye bye” is printed.

Python defines several type of variable. Let’s take a loop at the most common ones:

Integer

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


��

It is a simple integer value. You define it like that:

i=120

It.is.also.possible.to.use.negative.number

i= -10

floating-pointTThe floating points are used a lot in Modul8. They are defined this way:

i=10.0.or.

i=-230.124

stringStrings are used to store text. A string is a chain of characters enclosed by ‘ or by “:

str = ‘Hello’

or.

str = “Hello”

listA list is more complicated type. It is used to store a list of values.

You can define it this way:

mylist = [0,10,20,30]

It defines a list of four numbers: 0,10,20,30

You.can.access.or.modify.the.entry.of.a.list.this.way:

mylist[0] = 1

Set the first entry of the list to 1.

dictionaryA dictionary is another type a little bit more complicated but very useful.It allows you to map a value to another. For example, imagine that you want the word ‘house’ to correspond to the value ‘ a build for human habitation‘. In this case ‘house’ is the key, and the definition is the value.

You can define your dictionary this way:

mydict = {‘ house’ : ’ ‘a build for human habitation.’}

As you can see you write the key, followed by : and then a string for the definition.

Then if you write this expression:

print mydict[‘house’]

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


100

The definition of the house will be printed.

Of course you can use any type of Python, not only strings:

mydict = {‘red’:0, ’green’:1, ‘blue’:2}

In.this.case:

print mydict[‘green’]

… will print 1.

operatorsIn.order.to.do.any.kind.of.computing.you.need.to.have.at.least.some.mathematical.operator..Most.of.them.are.obvious:

+.:.addition-.subscration/ : division* : multiplication

For.instance:

y = (10 * 0.5) + 0.33

For.conditions,.you.can.use.these.operators:

== equal!= not equal<= smaller or equal>= greater or equal< smaller> greater

For.instance:

if i!=0:print “i not equal to zero”

commentsYou can insert comments in your code using the # character. The rest of the line is ignored by Python when is.character.is.found:

i=0 # set i to 0

PackagesThe Python language contains a large library of functions that can be used from any program. Functions are grouped in Python modules or packages. You will find the list of available packages (or Python modules) on.the.python.web.site.

Some.of.them.like.the.math.module.are.very.standard.and.can.be.very.useful.in.the.Modul8.context..Before using a Python package you should import it.

To import the math package:

import.math

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


101

Once imported you can use all the math functions of this package:

print math.cos(0.5) # Do a cos of 0.5

See.the.Python.web.site.for.more.information.

The scripting environment

The scripting environment is made of several components designed to simplify your life when coding in.the.context.Modul8.

Before being able to script anything you need to have at least a module created. The best solution to.discover.the.scripting.is.to.create.an.empty.module..So.go.to.the.module.editor.and.add.new.module.called “ScriptTest”. You can remove it later when it is not required anymore.

Once your module is created, select the “Script” tab at the bottom of the window. This is where the scripts are written. At the top of the editor is a pop-up that allows you to select what script you want to edit. A script is always executed when a specific event occurs. By default, the pop-up shows the “Init()” script. This script is called when the module is executed the first time or when it is restarted.

Let’s try to write our first simple script. Write this simple line in the “Init()” script:

print “Hello World!”

This script simply writes “Hello World!” to the console. Modul8 includes its own console that is pretty useful for debugging script. You can find it in the “Script” sub-menu of the “Module” menu. Open it.

Now go to the “Module” menu and select “Restart”. The script is restarted and the Init script is called. “Hello World” should be printed in the console. If you restart it another time, the text will be written another time.

When you modify a script, it is not immediately executed. You should call the “Restart” function to restart the module. You can also use the “Resync” function in the “Script” sub-menu. The main difference is that the “Resync” function does not restart the script but simply updates the changes you did to the executing.module..It.is.pretty.useful.if.want.to.apply.an.update.without.restarting.completely.your.module..However the “Resync” does not call the “Init()” script, because the module is not restarted. So if you did any.change.in.this.function.you.will.have.to.restart.the.module.to.see.the.result.

The module architecture is able to show you automatically an error in your script. Try to modify your script.like.that:

print.a

Restart it. The error window open, showing you the error and its position:

If.you.double-click.on.the.error,.the.module.editor.jumps.directly.to.the.position.of.the.error.in.the.scripts. You can also click on the “Go to Error”.

The script sub-menu includes also several useful tools to write code:

Shift Right/Left: Allows you to shift the indentation of the selected block of text.Comment/Uncomment: Comment or uncomment the selected block of text.

The keyword browser can also be used to insert a keyword in a script. Simply open it from the menu, select the script and click on the insert button. The keyword is automatically inserted in the text at the

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

cursor.position..

The Modul8 main functions

In order to communicate with Modul8, you need to use a global object called “modul8”. All the communication. is. done. by. using. the. famous. Modul8. keywords. and. two. functions:. setValue. and.getValue.

These functions are defined this way:modul8.setValue(name,value,layer)modul8.getValue(name,layer)

For.example.to.get.the.value.of.a.keyword:

modul8.getValue(‘ctrl_layer_color_modulateG’,1)

This example returns the rotation x of the first layer.

For values that are not layer relative (Master Controls for instance), the layer parameter is not used and you.can.pass.any.value..

If you pass zero to the layer variable, it is the active layer that is used. The number from 1 to 10 is for absolute.layer.referring..

For.the.setValue.you.can.also.pass.–1.to.the.layer.parameter,.in.this.case.the.value.is.set.to.all.the.layers.

Please note that for layer contextual module, the layer is not used at all. Simply pass zero.

The Module functions

While.the.Modul8.functions.allow.you.to.communicate.with.the.Modul8.application.and.its.keywords,.the.Module functions can be used to communicate with your module and its user-interface. All the functions should be sent to the “module” object.

For.instance:

module.setValue(‘myRedColorSlider’,’red’,0.5)

Here.follows.a.list.of.the.functions:

setvalue/getvalueThese functions can be used to get or to set a value to the controls of your module.

They are defined this way:

module.setValue(name,valueIndex,value)module.getValue(name,valueIndex)

The name is the name of the control that you specified in the interface builder. The valueIndex corresponds to the value want to change. Because some controls can have several values this is where you specify the value.you.want.to.get.or.set..For.example,.the.pad.has.two.values:.the.x.and.the.y..You.can.pass.the.value.index.using.an.integer.index.or.by.passing.a.string.with.the.name.of.the.value.

For.example,.for.a.pad:

module.setValue(‘myPad’,’x’,0.5)

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

module.setValue(‘myPad’,’y’,0.5)

is.the.same.as:

module.setValue(‘myPad’, 0, 0.5)module.setValue(‘myPad’, 1, 0.5)

setdefaults / getdefaultsThese functions can be used to store a permanent dictionary in your module. It is very useful if you want to.store.preferences.that.can.be.re-used.even.when.Modul8. is.quitted.and.restarted. later..Please.note.that this dictionary is saved inside the module file. So if you share the module online or move it to another machine,.the.preferences.will.be.included.with.it.

Typically you will use the getDefaults function in the Init() script and the setDefaults in the Finish() script.

These two functions are very easy to use:

module.setDefaults(dict)module.getDefaults() # returns the dictionary with the preferences

setattribute / getattributeThese two functions can be used to get or to set attributes of your user-interface controls.

Their definitions are:

module.setAttribute(name, attributeType, value)module.getAttribute(name, attributeType) # return the attribute value

The name is the name of the control as you specified it in the user-interface builder. The two other parameters.depend.of.the.control.type.

Here.is.a.list.of.the.possible.attributes:

HIDDEN: Show/Hide the control, the value should be True or FalseFRAME: Change the size and the position of the control. You should pass a list of four values: x,y,width,heightSCRIPT_MESSAGE: Set a new script messageTEXTLIST: Set a new text list. Only for the text list controlCAPTION : Change the caption of the control. Only for button and captionSHOW_MEDIA: This is keyword that can be used to set the media associated to a button. Pass 1 to 128 to.display.the.media.thumbnail.or.0.for.the.standard.button.shape

getshareddictionaryThis function returns the global shared dictionary. This dictionary is useful to allow the modules to communicate together and share values. By default, all the modules are executed in completely separated spaces to avoid any conflict of variables and functionalities. However there is a global dictionary that any module can use to read or to store values. This function can be used to get this dictionary.

flushallcontrolsThis function can be used to force all the controls to flush their values to the Modul8 keywords. It is useful to force a resynchronization of your module controls with Modul8.

sendMessageToallInstancesThis function is useful in layer contextual mode when you need to communicate to all the other instances of your module. You simply call it with the message and a parameter. Then all the instance of your module will.receive.a.MessageEvent.call.with.the.msg.and.the.param.you.set.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

showGroup / hideGroupThese two functions allow you to show or to hide a group of control. Simply pass the group name as you set.it.in.the.editor:showGroup(mygroupname)

The Modul8 advanced functions

Beside the standard function set/getValue function the Modul8 object has several other useful functions.

sending midi messagesIt.is.possible.to.send.midi.messages.from.Modul8.to.an.external.or.virtual.midi.device.

The function to send midi message is:

modul8.sendMidiMessage(endpoint,channel,message,value1,value2)

The endpoint is the name of the device that should receive the message. If you pass an integer instead of a string, it will be the index in the device list (for instance zero for the first device). You can obtain the midi device list, using the modul8.getMidiDestinationsList() function.

The message can be either directly a numerical message or a string. For string, possible values are: NOTE_OFF, NOTE_ON, POLY_AFTERTOUCH, CONTROL_CHANGE, MODE_CHANGE, AFTERTOUCH, PITCHBEND, SYSTEM.

The value1 and value2 represents the midi value. Possible values depend of the message type.

hsbTorgb / rgbToHsbThese two functions can be used to convert rgb value to hsb value. Sometimes it can be useful to work in hue/saturation/brightness mode instead of red/green/blue.

You.simply.pass.a.list.with.the.three.values,.and.a.converted.list.is.returned:

hsb = modul8.rgbToHsb([1,1,1])

setfilters / getfiltersdescThese functions can be used to manipulate and apply filters to a layer. Because Modul8 supports filter such as the FreeFrame or CoreImage, the filter list is dynamic. You can obtain a list of all the filters including all the parameters for every filter using the getFiltersDesc function. This function returns a list with one entry per filter. Each entry is a dictionary. For instance the Modul8 Contrast filter looks like this:

{‘FILTER’: ‘(M8) Contrast’, ‘PARAMETERS’: [{‘DEFAULTVALUE’: 0.0, ‘TYPE’: ‘BOOLEAN’, ‘NAME’: ‘Boost’}, {‘DEFAULTVALUE’: 0.0, ‘TYPE’: ‘BOOLEAN’, ‘NAME’: ‘Invert’}, {‘DEFAULTVALUE’: 0.5, ‘TYPE’: ‘STANDARD’, ‘NAME’: ‘Level’}]}

FILTER contains the name of the filter and PARAMETERS contains a list of the possible parameters.

For each parameter you have the default value, the type, and the name. STANDARD means that it is a value going from 0.0 to 1.0 while BOOLEAN is a True/False value.

To apply one or more filters from a script you use the modul8.setFilters() function:

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

modul8.setFilters(filterList, layer, future)

The filterList contains the list of the filter you want to apply. If you plan to apply only one filter you simply create.a.list.with.one.entry.

A filter is defined with a dictionary, which should have at least two entries. First entry is the name of the filter, the second is a dictionary containing the parameters and their values.

For instance, here is a dictionary, which defines a contrast filter:

contrastDict = {‘FILTER’: ‘(M8) Contrast’, ‘PARAMETERS’: {‘Boost’ : False,‘Invert’:False,‘Level’:0.5 }}

This dictionary defines a contrast filters of 50% with Boost and Invert disabled.

To send this filter to the specified layer:

modul8.setFilters([contrastDict], layer, False)

The last parameter is a future parameter and is ignored yet. You should simply pass False.

You can pass several filters like this:

modul8.setFilters([contrastDict,chromaDict], layer, False)

If you want to remove all the filters you simply pass an empty list:

modul8.setFilters([], layer, False)

The script types

Each script type is linked to a specific event. This chapter describes all the script types and how and when.they.are.called..

It.is.important.to.understand.that.in.Modul8.all.the.declared.variables.are.available.from.every.script..So.typically.if.you.declare.a.variable..

Init()This script type is called each time a module is started. It is the right place to declare global variables or to do any kind of required initialization. The init() function is not called when the user click on the pause button.in.the.window.menu..It.is.called.only:

The first time the module is startedWhen “Restart” is selectedAfter a “Stop All “ has been selected and the module is started again.

Messageevent(msg,param)This script is called each time a control is modified in the user-interface of the module. It is called only if a message has been defined in the interface-builder. To define a message, select you control in the user-

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

interface.and.go.to.the.Script.tab..You.can.enter.the.message.here:

Whenever the control is modified the “MessageEvent” script is called with the message you set in the “msg” variable and a dictionary in the “param” variable. The dictionary typically contains several entries: A ‘NAME’ entry that defines also the name of the control and one or more keys containing the modified value.of.the.control..You.can.test.the.this.script.by.simply.printing.the.passed.parameters:

print.msgprint.param

Then change a control that has a script message defined and see the result in the console.

directevent(type,param)This script is called each time a midi message is received or a keyboard key is pressed or released. It allows.you.to.shortcut.the.standard.user-interface.of.the.input.mapping..Most.of.the.time.it.is.better.to.use.controls.and.let.the.user.maps.the.midi.like.he.wants..However.if.you.want.to.handle.directly.the.midi.or.the.keyboard.you.should.use.this.script.

The “type” variable is a string that defines the type of event. The “param” is a dictionary that includes the parameters related to the event (the key pressed or the midi information).

You.can.test.this.script.by.printing.the.received.parameter:

print.typeprint.param

keywordevent(keyword,param)This script allows you to track changes made by the user in the Modul8 keywords. For instance when the user rotates a layer, the rotation keyword is modified. In this case you may want to change the state of some of your controls to reflect the new state of the layer rotation. This is the place were it should be done. Each time a keyword is modified, this script is called with the modified keyword and its new value in the “param” variable. It allows to track focus layer changes, effects changes, etc.

Periodicalevent(elapsed)This script is called repetitively and should be use to do any kind of periodical actions. It is the place to implement animation or motion. The passed parameter is a floating-point value that represents the time in.second.that.elapsed.since.the.last.time.this.function.has.been.called..It.is.important.to.note.that.this.function.is.called.between.frame.renders..So.as.long.as.you.are.in.this.function,.no.frames.will.be.rendered.to.the.screen..It.means.that.doing.a.loop.in.this.function.that.simply.change.the.rotation.of.a.layer.just.won’t work to do an auto-rotate or any kind of animation. This is because this script is synchronized with the render process. Animation must be implemented over multiple called of periodical events and animation.should.be.time.based.so.you.should.always.use.the.elapsed.variable.to.calculate.the.speed.of.your.animation.

For.instance.let’s.try.to.implement.an.auto-rotate.periodical..We.are.going.to.user.a.direct.key.so.the.user.can.continue.to.use.the.rotation.standard.user.interface.

We are going to use a global variable that we call ‘zangle’ to store the current angle. The best is to initialize it in the Init() script:

zangle = 0.0

Now in the periodical script:

zangle = zangle + elapsed*360modul8.setValue(‘direct_layer_rotation_z’,zangle,0)

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

The first line increments the “zangle” value by 360 degrees per second. It is important to use always the elapsed.parameter.to.compute.the.speed.of.your.animation.so.it.is.time.based.and.not.based.on.the.speed.of.the.machine.The second line simply passes the new zangle to the active layer z rotation. If.you.follow.these.simple.rules,.you.can.do.custom.animation.very.easily.in.Modul8.

Pauseevent(paused)This script is called when the user pauses a module by clicking on the pause button in the module window or.when.it.un-pauses.it.using.the.play.button..It.allows.you.to.insert.an.action.before.and.after.the.module.is.paused..Please.note.that.pausing.a.module.is.not.the.same.as.stopping.it.or.restarting.it..Pause.is.a.temporary action. For example you should not save or read preferences here, but in the Init() and Finish() scripts.

finish()The finish script is called each time the module is entirely reset by a “Stop All” or a “Restart” or when the application quits. Each Init() call is balanced with a Finish() call. It is typically used to store preferences.

serialize(outdict)/deserialize(indict)These two scripts are called when a document is saved (serialize) or open (deserialize). It allows you to save.data.such.as.module.parameters.or.states.into.the.user.document.

The serialize function give you a dictionary which is private to your module where you can store the Python objects you want to be stored. Once a document is open you receive through the Deserialize function the dictionary filled with the objects that was serialized before. Then it is up to you to update your module with these values. See the module chapter about serialization.

Module serialization

When.a.user.open.a.Modul8.document.he.or.she.expects.to.see.exactly.the.scene.as.it.was.saved.before..Now suppose that you did a module that animates a layer at the specific speed. The users changed the speed.using.a.knob.for.instance.and.then.he.saved.the.composition.to.a.document..What.happens.when.he.open.the.document.?.Does.you.module.will.automatically.be.update.with.the.speed.set.before.the.document.was.saved.?.Does.Modul8.automatically.save.the.sate.of.the.module.?

Well,. the.answer. is.yes.and.no..Modules.are.complex.beast.and.there. is.simply.no.way.for.Modul8.to.automatically.save.the.complete.context.of.a.module.

However serialization can be done nearly automatically for most of the simple modules. Each control has an “Auto-Serialize” option that can be found by selecting a control in the interface builder. If you set this flag the state of the control will be stored when a user save a Modul8 document. When the document is open.the.state.of.the.control.is.set.to.the.correct.value.and.the.script.message.associated.to.the.control.(if any) is sent to your scripts allowing you to update internal values if required. Simply setting this option will allow most of the module to be automatically serialized. It is event possible to serialize the content of a.draw.view.with.it.

Now it is not always possible to use this kind of automatic serialization. For instance you may want to save data which are not related to a control, like a list of values. In this case you should use the “Serialize/Deserialize” script functions.

When a module is saved the “Serialize” function is called with a dictionary as a parameter. Basically you can.store.python.object.such.as.strings,.numbers,.lists.and.dictionaries.in.this.dictionary.

For.instance:

* Serialize(outDict)

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


108

outDict[‘thespeedofmyanim’] = animspeedoutDict[‘listofnames’] = namelist

When a document is open by the user the deserialize function is called with a dictionary containing the values that was saved in the document. Then you can get back these values and use them in your module:.

* Deserialize(inDict)

animspeed = inDict[‘thespeedofmyanim’]namelist = inDict[‘listofnames’]

Most of the time it is safer to check that the key really exists in the module. This will avoid errors if you change.or.add.key.in.future.versions.of.the.module.

For.instance:If ‘thespeedofmyanim’ in inDict:animspeed = inDict[‘thespeedofmyanim’]if ‘listofnames’ in inDict:namelist = inDict[‘listofnames’]

The module draw view control

There is a special control in the Modul8 user-interface builder that is called a draw view. This control can be used.to.create.dynamic.animation,.custom.control.and.much.more..For.instance,.the.painter.module.uses.this.control.to.allow.the.user.to.paint,.to.display.the.brush.and.to.send.the.drawings.to.the.composition.

While.all.the.other.controls.are.pretty.simple.the.draw.view.is.more.complicated.and.much.more.powerful..Basically it is an area where your module can draw what it wants. Of course it can also send the drawing into.the.composition.as.a.static.image..It.can.even.store.frames.over.multiple.internal.layers.and.then.send.a specific frame to create pre-computed animation.

This control can also receive mouse input from the user, like mouse click and mouse drag. It is very useful when you want to build a custom control (a button with a specific look for example).

First of all it is important to understand how to draw to the view. Actually it is very easy! You simply have to call draw functions such as “module.drawLine” and when all the drawings are finished you call “module.finishDrawings”.

For.instance:

module.drawLine(‘myview’,x1,y1, x2, y2, pointSize,r,g,b,a)module.finishDrawings(‘myview’)

This will draw a line going from (x1,y1) to (x2,y2) in the control view called ‘myview’. The width of the line is specified using pointSize and the color by r,g,b,a (color range is 0.0 to 1.0, a is the alpha channel). The finishDrawings call will actually draw the line. It allows you to send several draw commands and then get them.rendered.in.the.view.

The simple drawing functions

The draw view supports the following drawing functions:

module.frameRect(‘view’,x,y, w, h,r,g,b,a)module.paintRect(‘view’,x,y, w, h,r,g,b,a)

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


10�

module.frameOval(‘view’,x,y, w, h,r,g,b,a)module.paintOval(‘view’,x,y, w, h,r,g,b,a)module.drawLine(‘view’,x1,y1,x2,y2,drawShapeSize,r,g,b,a)module.drawCurve(‘view’,x1,y1,x2,y2,cpx1,cpy1,cpx2,cpy2,drawShapeSize,r,g,b,a)

The text drawing functionsIt.is.possible.to.draw.a.string.using.the.default.Modul8.font.using.this.function:

module.drawString(‘view’,myStringToDraw, x, y, r,g,b,a)

The bezier functions

It is also able to draw Bezier curves. You start a new Bezier curve using the following function:

module.bezierNew(‘view’)

Then you can add new points and lines using these functions:

module.bezierLineTo(‘view’,x,y)module.bezierMoveTo(‘view’,x,y)

Once your Bezier curve is finished you can draw it using the following fuction:

module.bezierDraw(‘view’,lineWidth,lineCapStyle,r,g,b,a)

The lineCapts allows you to speficy the shape of the curve at the edge, it can be: “ROUNDLINE”, “BUTTLINE” or “SQUARELINE”.

Erasing.contentTo erase content you need to enter the erase mode:

module.enterEraseMode(‘myView’)

Then you can use all the standard drawing functions to erase content.

When it is finished you can use the following function to exit this mode:

module.exitEraseMode(‘myView’)

Multiple.layersEach draw view may contain one or more layer. By default only one layer is active. However sometimes is may.be.useful.to.create.a.background.and.then.draw.to.a.front.layer.without.having.to.rebuild.completely.the.draw.view.

Using multiple layers is very easy. To select a new layer you simply call this function:

module.setDrawingsLayer(‘myView’,’myLayerName’)

It.is.up.to.you.to.choose.a.name.for.every.layer.you.plan.to.use..If.you.call.this.function.and.the.layer.does.not exist it will be created. Once a layer has been selected all the drawings are executed in it.

Receiving input in the draw viewIn.order.to.create.interactive.draw.view.it.is.necessary.to.allow.your.script.to.receive.mouse.input.

First all you have to define a script message in the interface builder just like you do for standard controls.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


110

When. a. user. will. click. and. drag. the. mouse. in. the. view. you. will. receive. your. script. message. in. the.MesssageEvent.script.

In the param dictionary you will have an ACTION keyword describing the action type. It can be:

MOUSEDOWN: The mouse button has been pressed in the viewMOUSEUP: The mouse button has been releasedMOUSEDRAGGED: The mouse has been dragged

For each of these messages you will also receive the mouse position in view coordinate as ‘X’ and ‘Y’ entries.in.the.param.dictionary.

Sending.the.drawings.to.the.Modul8.composition

You.can.send.the.content.of.your.draw.view.as.a.standard.image.into.a.Modul8.layer.

You.simply.have.to.call.this.function:

module.sendContentToLayer(‘view’,caption,layer)

The caption is a simple string that will be displayed in layer caption of the main Modul8 interface.

This function can be very useful if you want to create dynamic content in the Modul8 composition.

Creating.animationThe draw view is able to store one or more frames, which can be sent at any time to the composition. It is very.useful.if.you.want.to.pre-compute.an.animation.

The first function is:

module.addContentToFrameStack(‘view’)

Basically this function will add the current content of the view to the frame stack. This is an invisible action. The draw view has an internal frame list that you can manipulate as you wish.

When you want to send a specific frame to a Modul8 layer, you can use this function:

module.sendFrameToLayer(‘view’,caption,layer,frame)

This function works exactly like the sendContentToLayer function. The only difference is that instead of.sending.the.content.of.the.view.to.the. layer. it.sends.a.frame.that.has.been.stored.before.using.the.addContentToFrameStack. You pass the frame number starting at zero for the first frame.

If you want to delete a specific frame you can use:

module.removeFrame(‘view’,frame)

If.you.need.to.remove.all.frames:

module.removeAllFrames(‘view’)

sharing your modules online

Once you have created a great module you may want to share it with other users in the public online library. Sharing a module is very easy. First of all you have to fill the module description so the users know what.your.module.is.doing.what.version,.etc.

MO

DU

LE

S

MAIN PANEL

01Main panel

VERSION 2.5


111

To do that, you should use the Module editor and select the info tab:

Verify.also.that.there.is.no.other.module.with.the.same.name.in.the.online.library..If.it.is.the.case.you.should.find a new name. Once you have filled the description, open the online browser and select the “Public Library”. Then select your module in the “Modules” list and click on the Share button.You can at any time remove your module from the library by clicking on the “Unshare” button.If you create a new version of your module you can update it simply by re-using the “Share” function. The module.is.replaced.online..It.is.a.good.idea.to.change.the.version.of.your.module.when.you.improve.it,.so.Modul8.users.know.that.changes.have.been.done.to.your.module.

SU

PP

OR

T A

ND

CO

NT

AC

T

MAIN PANEL

01Main panel

VERSION 2.5


11�

suPPorT, coMMunITy and conTacTs

The official Modul8 site: ................................... http://www.garagecube.com/modul8GarageCUBE distributes Modul8: .................... http://www.garagecube.comFor.information:................................................. [email protected] support: ............................................ [email protected]:.................................................... http://www.garagecube.com/forumBug Report: ...................................................... http://www.garagecube.com/bugFax:................................................................... +41.22.800.16.18

GarageCUBEC/o Ultrapepita3, Rue de la MuseCH-1205.GenevaSwitzerland

http://www.garagecube.com/modul8

http://www.garagecube.com

mailto:[email protected]

mailto:[email protected]

http://www.garagecube.com/forum

http://www.garagecube.com/bug

AB

OU

T

MAIN PANEL

01Main panel

VERSION 2.5


11�

abouT

Original Concept: Boris Edelstein and Yves SchmidEngine.Programming:.. . Yves.SchmidPython Programming: Boris EdelsteinGraphic.Design:.. . . Vincent.Schambacher.and.Matthias.GrauUser-Interface: Matthias Grau, Boris Edelstein and Vincent SchambacherDocumentation:.. . . Yves.Schmid,.David.HodgettsTesting: Jerom Doudet, Marco Gavini, Ilan Katin, Henrik Lundbergh,

Anton Marini, Michel Parenti, Daniel Vatsky, Chika Iijima

QuickTime® is a trademark of Apple ComputerOpenGL is a trademark of SGI

FlashTM is a trademark of Macromedia, Inc

modul8 documentation

Documents

modul8 offline

modul8 model

media panel

dynamic media

table of contents copyright

table of contentsintroduction

main panel01main panelversion