Page 1 of 1

ZgeViz: effect development documentation

Posted: Fri Jul 02, 2010 11:22 am
by VilleK
To develop a effect in ZgeViz start by downloading the latest ZGameEditor distribution.

If you are new to ZGameEditor (ZGE) it is strongly recommended to look at Kjells Video Tutorials and the documentation.

Start a new project and then copy/paste the following into the project tree:

Code: Select all

ZZDC<?xml version="1.0" encoding="iso-8859-1" ?>
<Group>
  <Children>
    <DefineArray Name="SpecBandArray" SizeDim1="32"/>
    <DefineArray Name="AudioArray" SizeDim1="32"/>
    <DefineVariable Name="SongPositionInBeats"/>
    <DefineArray Name="Parameters" SizeDim1="32"/>
    <DefineConstant Name="ParamHelpConst" Type="2"/>
  </Children>
</Group>
When an effect is loaded these variables will be captured by ZgeViz and fed with data from FL-Studio.

Explanation of variables

SpecBandArray : This array is filled with the amount of audio at different frequencies. The values range from -1 to 1. Note that when the effect is loaded the actual length will be set by ZgeViz. The initial size is 32 but it can be configured to another size by the user in the settings dialog, so effects should be written with this in mind.

AudioArray : This array is filled with the audio pcm data that is currently playing. The values range from -1 to 1. The actual size of this array is set at runtime.

SongPositionInBeats : This variable holds the current position in beats. An example use of this variable is to take the fraction part and modify camera Z position to make the scene pulse in sync with the music.

Parameters : This is an array that hold values that range from 0 to 1 and are controlled by the sliders in the ZgeViz interface. They can be used freely (or ignored) in the effect to modify visuals.

ParamHelpConst : This is a string that is used to hold the names of the parameters the effect is using. So if you have an effect with two parameters that controls shape and color, this property could hold the names "Shape" and "Color" separated with a carriage return. The names of the parameters are shown as labels in the ZgeViz user interface.

When you have created a zgeproj-file with an effect store it in the Foreground subfolder of ZgeViz directory. The effects are currently split into foreground and background but they work the same and both categories load the effects from the same folder. ZgeViz will load all effects on startup. If you make a change in the zgeproj-file while the effect is running in ZgeViz use the "Reload" button to make ZgeViz reload the effect.

There is a third category of effects called "Clear" that is rendered before the other categories to clear the screen. This is useful for feedback effects.

MIDI
See the thread about MIDI-input.

Video textures
If your effect file contains a bitmap component named "VideoTextureBitmap" it will be filled with the content of the currently selected video texture or camera input. For examples of this check out the effects that are named "Video...".

UserTextArray
Add a DefineArray component of string type named "UserTextArray" if you want to use the strings that the user can enter in the custom content dialog.

Effect help
Use the comment property of the ZApplication-component to write some help text about your effect that will be displayed in ZgeViz when you right-click and choose "Show help for this effect".