undocumented stuff

contains the latest version of our visualizer plugin (replacing Chrome)

Return to “ZGameEditor Visualizer forum”

[You can only see part of this thread as you are not logged in to the forums]
StevenM
Thu Nov 03, 2011 4:44 pm

0 x

undocumented stuff

Just gathering some topics here as a personal reference:
------------------------------------------------------------------------------------------

Private Data
Private Data allows you to store data that is save in the users project file. This can overcome many limitations of parameter controls. i.e. BitPadZ is currently the only effect that uses Private Data.

There are several components required to set it up. It not easy to explain:
Here is a simple test project example:
PrivateDataTest.zgeproj


------------------------------------------------------------------------------------------

Visualizer 2.0 usee interface Check Box and Dropdown:

Used with the ParamHelpConst string:

Examples:
Menu @list: first,second,"last item" : Creates a drop down menu Named "Menu" with four items.
Toggle @checkbox : Creates a check box named "Toggle"

------------------------------------------------------------------------------------------

Visualizer 2.0 new feature:

Variable: AuthorInfo

Type: const string

A ZGE visualizer specific variable that adds the script author's name at the top of top right the ZGE visualizer Layer.

------------------------------------------------------------------------------------------
Visualizer 2.0 new feature:

Variable: LayerNr

Type: int

A ZGE visualizer specific variable that indicates what layer the current effect is loaded on.

------------------------------------------------------------------------------------------

Visualizer 2.0 new feature:

Variable: FLPluginHandle

Type: xptr

A ZGE visualizer specific variable that returns the window handle to the visualizer plugin.

------------------------------------------------------------------------------------------

Visualizer 2.0 new feature:

ZExternalLibrary function:
void ParamsChangeName(xptr Handle,int Layer, int Parameters, string NewName) { }


ModuleName : ZGameEditor Visualizer
Calling convention : StdCall

This function allows script developers to change the names of parameter labels.

------------------------------------------------------------------------------------------
Visualizer 2.0 new feature:

ZExternalLibrary function:
void ParamsWriteValueForLayer(xptr Handle, int Layer,int Param, float NewValue) { }


ModuleName : ZGameEditor Visualizer
Calling convention : StdCall

This function allows script developers to automate any layer parameter with ZGE Script.

------------------------------------------------------------------------------------------
Visualizer 2.0 new feature:

ZExternalLibrary function:
void ParamsNotifyChanged(xptr Handle,int Layer) { }{ }


ModuleName : ZGameEditor Visualizer
Calling convention : StdCall

This function allows automattion of the current "LayerNr" parameters with ZGE Script. This This allows users to set parameter values and update the values when "ParamsNotifyChanged" is called. This function only works for one "LayerNr". Alternatively, The previous function "ParamsWriteValueForLayer" can write values to any other layers and parameters.

Example:

This code block sets parameters 2-5 of the script to a random value.

Code: Select all

Parameters[2] = rnd();
ParamsNotifyChanged(FLPluginHandle,LayerNr);
Parameters[3] = rnd();
ParamsNotifyChanged(FLPluginHandle,LayerNr);
Parameters[4] = rnd();
ParamsNotifyChanged(FLPluginHandle,LayerNr);
Parameters[5] = rnd();
ParamsNotifyChanged(FLPluginHandle,LayerNr);


------------------------------------------------------------------------------------------

Read from text file into array

A recent update makes it easier to read text files:

example from http://www.emix8.org/forum/viewtopic.php?f=2&t=1238&p=8025&hilit=write+file#p8025:

Code: Select all

string[] lines;  //Declare array

@FileAction( File : @File(FileName : "test.txt", TargetArray:lines) );  //Read from text file into array

for(int i=0; i<lines.SizeDim1-1; i++) //And just print out the lines
  trace(lines[i]);


------------------------------------------------------------------------------------------

Skelatal Animation

Rado's Cal3D library can import rigged 3d models to zge.


I've tried, rigged models with : Cal3D exporter for 3ds Max (64-bit) and it works really well.
Cal3D has been dormant for a while - but they are still active and are planning some new updates for 2015.
Popular 3D Chat website, IMVU shares a lot of tools and tips for Cal3D development as well.

------------------------------------------------------------------------------------------

Image copy Buffer

Module Name: ZgameEditor Visualizer

Functions:

Code: Select all

int ClipboardGetBitmapWidth() { }
int ClipboardGetBitmapHeight() { }
int ClipboardGetBitmapPixel(int x,int y) { }


Example :

Code: Select all

//get from clipboard

int pix=ClipboardGetBitmapPixel(x,y);
int r=(pix >> 16) & 255;
int g=(pix >> 8) & 255;
int b=pix & 255;


------------------------------------------------------------------------------------------

NoCustom Bitmap Component Comment

Use the comment "NoCustom" on the bitmap component to prevent image imports from replacing the default bitmap.

Example Bitmap component properties with No custom option:
NoCustom.jpg


------------------------------------------------------------------------------------------

Host message ID

It works just like the midi messages that you declare a library function that responds to messages.

Code: Select all

void OnHostMessage(int id, int index, int value) {
  trace("hostmessage id: " + intToStr(id) + "  index: " + intToStr(index) + " value: " + intToStr(value));

if(id==12) {  //12 = FPD_SetPlaying message
    if(value==0)
      trace("stopped");
    else
      trace("started");
  }
}


------------------------------------------------------------------------------------------

"ref" syntax

This allows you to return more than one value from a function.

Example 1:

Code:

Code: Select all

 //notice the "ref" word in front of the arguments that are passed by reference
 void splitColor(int color,ref int r, ref int g, ref int b) {
   //..separate r,g,b from color and return back to caller
 }

 //call this function
 int r,g,b;
 splitColor(0xff8020,r,g,b);


Another great thing with this feature is that it allows to call dll-functions that expects a pointer to an integer as an argument. This was previously not possible.

Example 2:

Code: Select all

//OpenGL-function, generate a texture id and return it into the second argument
 void glGenTextures(int n, ref int textureid) { }
 //Delete a texture, pass the id using a reference
 void glDeleteTextures(int n, ref int textureid) { }


Of course it works with other data types too, not just integers.

------------------------------------------------------------------------------------------

"xptr" datatype

At the moment only DefineArray components are valid xptr but other components may be added too if needed.

Example:

Code: Select all

//OpenGL external library definitions, notice the last parameter "xptr pixels"
 void glTexImage2D(int target, int level, int internalformat, int width,  int height, int border, int format, int atype, xptr pixels) {}
 void glGetTexImage(int target, int level, int format, int atype, xptr pixels) {}


These functions can now be called with an DefineArray instance as the last parameter. This should open for lots of interesting possibilities when working with OpenGL-functions.

------------------------------------------------------------------------------------------

ShaderVariable new ValueArrayRef

If you have a ShaderVariable:
<ShaderVariable VariableName="array1" ValueArrayRef="MyArray"/>

Then "MyArray" is your DefineArray component and in your fragment shader you declare the array like this:

Code: Select all

"uniform sampler1D array1;"


Use the GLSL-functions "texture" or "texelFetch" to read values from the array.

------------------------------------------------------------------------------------------

OnMidiMessage

Instructions

1. Download the latest ZgeViz-beta.
2. Copy/paste the following into the Content-node of a new ZGE-project: Code:

Code: Select all

ZZDC<?xml version="1.0" encoding="iso-8859-1" ?>
 <ZLibrary Name="FL_Library">
   <Source>
 <![CDATA[void OnMidiMessage(int status, int data1, int data2) {

 }]]>
   </Source>
 </ZLibrary>



3. Write code that acts on midi-input.

Note: For performance reasons please only include the above FL_Library-component in effects that act on midi input. This avoids redundant data copying in ZgeViz.

Table of Midi Messages :
http://www.midi.org/techspecs/midimessages.php

In the ZgeViz user interface you can select which Midi-port to use. -1 means midi input is turned off.

Example Project:

MidiTest.zgeproj


------------------------------------------------------------------------------------------

Script based Component invocation

Introducing "Script based Component invocation"

Syntax:

@ <component> ( [ <property> : <value> ] ... );

This will declare and execute a component with the properties set to the desired values.

Examples:

Code: Select all

@RemoveModel();  //A component that does not need any properties

 //Components with a single property
 @SetAppState(State : AppState_TitleScreen);
 @SpawnModel(Model : TitleScreenModel);
 @UseMaterial(Material : PlayerMaterial);
 @RenderMesh(Mesh : PlayerMesh);

 //Several properties
 @RenderText(Text : "Hello" + intToStr(i), X : -0.5, Y : -1 + (0.1*i));
 @PlaySound(Sound : Sound1, NoteNr : 85);


------------------------------------------------------------------------------------------

Arrays as parameters:
Code:

Code: Select all

//Add item to end of array
 void addItem(int item, int[] ar) {
   ar.SizeDim1++;
   ar[ ar.SizeDim1-1 ] = item;
 }



This function can be called like this:

Code: Select all

addItem(42, MyArray);

where MyArray is a Array component with type=int and dimensions=1.

------------------------------------------------------------------------------------------

Local arrays

A function can declare local arrays. Examples:

Code: Select all

int x[];  //Declare a one-dimensional int array
int xx[ , ];  //Declare a two-dimensional int array
int xx[ , , ];  //Declare a three-dimensional int array

x.SizeDim1=10; //Set array to hold 10 items



The arrays are automatically created on entry and freed on exit of the function.

The local arrays can now have specified default size:

Code: Select all

float[4,4] m;  //A 4x4 array
string[10] lines;  //Holds 10 items


------------------------------------------------------------------------------------------

new function getModels(items, category) :

This can be used for looping through models at runtime and do things like custom collision detection etc.

Code: Select all

 //Get all model instances of category zero
 model[] models;
 getModels(models,0) 
 //Loop through the list
 for(int i=0; i<models.SizeDim1; i++) {
   model m = models[i];
   //do something
 }


------------------------------------------------------------------------------------------

Explanation of FL Studio 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. **The 1D array uses interlaced values for stereo channels. **Like the SpecBandArray it can be configured by the user, but in the FL Studio Audio settings dialog(sample rate), so effects should be written with this in mind.

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. **Set default start values by setting the array component to persistent and editing the values. The default value can be restored by the user by right clicking over the parameter.

ParamHelpConst
This is a string (**constant variable type) 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.

A zgeproj-file for FL Studio get stored in the a subfolder of your choice in this directory.
Program Files-->Program Files (x86)\Image-Line\FL Studio 12\Plugins\Fruity\Effects\ZGameEditor Visualizer\Effects

**Video cue points can use midi input to set the video playback to a specific time. Input cue points in the visualizer settings by selecting the Video texture cue points tab. Units are in seconds with decimal values. For ease of use you can also import a .wav file with marker information to add cue points automatically. Markers can be added to a .wav file with Edison. A third party app can be used to extract the audio track from the video, if needed. Cue points are triggered by midi input(the first cue point is mapped to c0, second=c#0, third=d0...). Cue point Midi key assignment cycles, so that cue points can be triggered from any octave.

Video: Realtime playback
Depends on system resources. If an HD video import is not playing back in real-time (skipped frames). Importing a smaller video for a better real-time editing is a good option. You can use the ZgameEditor Visualizer to convert the HD video to a lower res video and import that in it's place. The low res video can later be swapped with the HD video prior to rendering for HD quality video exports. Dropped frames is not an issue when exporting videos.

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".
You do not have the required permissions to view the files attached to this post.

VilleK (staff)
Fri Nov 04, 2011 9:50 am

0 x

Re: undocumented stuff

Thanks Steven, this reminds me that I really sh...

StevenM
Sat Nov 05, 2011 2:53 am

0 x

Re: undocumented stuff

No problem - I should have these things committ...


Return to “ZGameEditor Visualizer forum”