KGLDiaShow - Command Reference

The KGLDiaShow is an interpreter for simple scripts. It will allow you to show, move, scale, rotate and fade images on top of openGL.

If you want a fast introduction and a practical entrance, there should have come a demoscript with this archive.

This is the reference documentation for the KGLDiaShow script interpreter.
If anything here does not fit the behaviour of the interpreter, there's something wrong: either in the interpreter or in the documentation.
In this case: mail to thomas.luebking@web.de

Index

Syntax

Some basic rules:

Type notation: Suggestions:

Command Reference

Control commands

loop ( [Times] )
  1. How many times ( optional )
This starts a loop.
Anything between loop( ) and endloop( ) is executed several times
If you leave the parameter the loop runs infinite
If 'Times' is '0', the loop content is skipped. loop( 3 )
   scaleImageTo( $image, 100, -1 )
   showImage( $image )
   scaleImageTo( $image, 50, -1, 5000 )
   wait( 4500 )
   setImageAlpha( $image, 0, 500 )
   wait( 500 )
   hideImage( $image )
endloop( )
Loops can be cascaded.
endloop ( )
This ends a loop started with loop( )
for ( Variable=Image1:Image2:Image3:... )
This is very usefull if you need to process the same commands on many images ( e.g. to prepare them for action )
The Variable is assigned to each image in the list and then the following instructions are performed on this image. loadImage( konsole.png, konsole )
loadImage( konqueror.png, konqueror )
loadImage( kmail.png, kmail )
loadImage( kwrite.png, kwrite )

for ( image=$konsole:$konqueror:$kmail:$kwrite )
   scaleImageTo( $image, 15, -1 )
   moveImageTo( $image, 50, -15 )
   showImage( $image )
   moveImageTo( $image, 50, 115, 3000 )
   hideImage( $image )
endfor( )
For loops can be cascaded.
endfor ( )
This ends a loop started with for( )
wait ( Milliseconds )
  1. The time to wait
This holds the script execution for some time.

NOTICE: This has nothing to do with the onscreen action - animations will go on!

wait( ) allows you to control the animation flow. If you e.g. want to scale an image up, then wait some time and in the end, fade it out: # scale for 5 seconds
scaleImageTo( $image, 80, -1, 5000 )
# wait 4 seconds
wait( 4000 )
# start fade 1 second before scaling ends
setImageAlpha( $image, 0, 1000 )

quit ( )
This exits the script ( otherwise it keeps running, showing the last state )
Don't forget to wait( ) until your animations have finished before calling this
requireVersion ( Version )
  1. floating point of the required version
As this API will grow over the time, you must make sure that the version your user is running matches the version you're working on. ( Otherwise ( s )he'll bug you and say your an idiot ; )
Soif you want to make use of commands that were not features of the initial released version ( 0.5 ), you should call this with the number of the highest version you require.
debug ( 0|1 )
  1. off or on, later versions may support verbosity values ( e.g. 5 talks more than 2 )
This triggers the script debugger to be on or off and can be called anytime in the script to debug your actions

Commands on images

loadImage ( ImageFile, [Image] )
  1. Path to the image
  2. the variable the image is assigned to ( optional )

NOTICE: Images are loaded hidden, you must explpicitly showImage( ) them!

Well, of course one of the first things you want to do, is to load an image ( or more ; )
Qt currently supports jpegs, pngs, bmps and ( probably ) gifs.

To do something with the images, you must be able to reference them.
This is why you better pass the second parameter that may be any kind of string that does NOT contain '( ,;: )' ( those chars are used internal ).

If you later want to refer to this variable, you need ( just like in bash or perl ) to prepend a '$' loadImage( wallpaper.png, background )
...
...
...
scaleImageTo( $background, 100 )
The imagepath may be relative or full, where the best choice is probably to make it relative to the script.
So assuming you have the script in a subfolder 'script' and the image in a subfolder 'images', you'll have to reenter this directory like: loadImage( ../images/wallpaper.png, background )
copyImage ( Image, Variable )
  1. The image to copy
  2. the variable the imagecopy is assigned to

NOTICE: Images are loaded hidden, you must explpicitly showImage( ) them!

If you want to use the same image more than once, instead of loading it several times you should better just copy it.

1: This is MUCH faster
2: It comsumes no additional TRAM

The image copy is completely independed from the original. It can be scaled, move, rotated, faded, etc. and also removed without affecting the original in any way - they just share the same texture data. copyImage( $image, imagecopy )
...
removeImage( $imagecopy )
# $image is still available
scaleImageTo( $image, 20, -1, 500 )
showImage ( Image )
  1. The image to be shown
Shows an image

NOTICE: Images are loaded hidden, you must explpicitly showImage( ) them!

loadImage( image.png, image ); showImage( $image )
hideImage ( Image )
  1. The image to be hidden
Hides a previously shown image

NOTICE: Hiding an images improves performance over setImageAlpha( .,0 )!

rotateImageBy ( Image, Axis, Degrees, [Time] )
  1. The image to be rotated
  2. X, Y or Z ( Z is the Axis for 2D rotation )
  3. How much, may be negative or exceed 360° ( float )
  4. How long the rotation shall last ( optional, Integer )
Rotates the image by some degrees around any 3D Axis relative to it's current rotation and the view rotation. rotateImageBy( $image, Z, 360, 2000 )
# this would cancel the above statment and start from an arbitrary rotation
# rotateImageBy( $image, Z, 360, 4000 )
wait( 2000 )
rotateImageBy( $image, Z, 360, 4000 )

NOTICE: Image rotation is relative to the scenery rotation!

NOTICE: Images lie on top of the screen by default,
i.e. if you rotate them around the X or Y axis, the part towards you will be clipped ( as it's now "outside" the screen )!
To avoid that, move the scenery "into" the screen, e.g. moveTo( Z, 2 )

rotateImageTo ( Image, Axis, Degrees, [Time] )
  1. The image to be rotated
  2. X, Y or Z ( Z is the Axis for 2D rotation )
  3. How much, may be negative or exceed 360° ( float )
  4. How long the rotation shall last ( optional, Integer )
Rotates the image to a specific degree of rotation around any 3D Axis. # rotate around the vertical axis
rotateImageBy( $image, Y, 360, 2000 )
wait( 500 )
# this will ensure the image is set back to 0°
# no matter where it was when the call was made
rotateImageTo( $image, Y, 0, 1000 )

NOTICE: Image rotation is relative to the scenery rotation!

NOTICE: Images lie on top of the screen by default,
i.e. if you rotate them around the X or Y axis, the part towards you will be clipped ( as it's now "outside" the screen )!
To avoid that, move the scenery "into" the screen, e.g. moveTo( Z, 2 )

moveImageBy ( Image, Axis, Percent, [Time] )
  1. The image to be moved
  2. X, Y or Z
  3. How far, may be negative or exceed 100 ( float )
  4. How long the movement shall last ( optional, Integer )
Moves the image on the scenery. # move the image half the screen width to the left
moveImageBy( $image, X, -50, 2000 )
wait( 2000 )
# and back
moveImageTo( $image, X, 50, 2000 )

NOTICE: Image movement is relative to the scenery movement!

moveImageTo ( Image, Axis, Percent, [Time] )
  1. The image to be moved
  2. X, Y or Z
  3. How far, may be negative or exceed 100 ( float )
  4. How long the movement shall last ( optional, Integer )
Moves the CENTER of the image to a specific position on the scenery.
If you pass values outside [0,100] the center of the image will leave the screen, what can be usefull to slide in images # center the image on the screen
moveImageTo( $image, X, 50 )
moveImageTo( $image, Y, 50 )

NOTICE: Image movement is relative to the scenery movement!

scaleImageBy ( Image, Percent, [Percent], [Time] )
  1. The image to be scaled
  2. [horizontal] scale factor ( float > 0 )
  3. vertical scale factor ( optional, float > 0 )
  4. How long the scale shall last ( optional, Integer )
Scales the image relative to it's current scale. # scale image to 20% of the scenery
scaleImageTo( $image, 20, -1 )
# scale by 150%
scaleImageBy( $image, 150, -1, 2000 )
# the image now takes 30% of the scenery
scaleImageTo ( Image, Percent, [Percent], [Time] )
  1. The image to be scaled
  2. [horizontal] size relative to the scenery ( float > 0 )
  3. vertical size relative to the scenery ( optional, float > 0 )
  4. How long the scale shall last ( optional, Integer )
Scales the image relative to the SCENERY. # scale image to 20% of the scenery and keep the ratio
scaleImageTo( $image, 20, -1 )
# scale image to 20% of the scenery with and 20% of the height ( regardless of the image dimensions )
scaleImageTo( $image, 20, 20 )
tintImage ( Image, Red, Green, Blue, [Time] ), [since 0.6]
  1. The image to be tinted
  2. Opacity, 0 is transparent, 100 opaque ( float )
  3. How long the fade shall last ( optional, Integer )
setImageBrightness ( Image, Percent, [Time] ), [since 0.6]
  1. The image to be lightned/darkened
  2. Opacity, 0 is transparent, 100 opaque ( float )
  3. How long the fade shall last ( optional, Integer )
clipImage ( Image, x, y, width, height ), [since 0.6]
  1. The image to be clipped
  2. Opacity, 0 is transparent, 100 opaque ( float )
  3. How long the fade shall last ( optional, Integer )
blurImage ( Image, Percent, [Time] ), [since 0.6]
  1. The image to be blurred
  2. Opacity, 0 is transparent, 100 opaque ( float )
  3. How long the fade shall last ( optional, Integer )
setImageAlpha ( Image, Percent, [Time] )
  1. The image to be scaled
  2. Opacity, 0 is transparent, 100 opaque ( float )
  3. How long the fade shall last ( optional, Integer )
Moves the CENTER of the image to a specific position on the scenery.
If you pass values outside [0,100] the center of the image will leave the screen, what can be usefull to slide in images setImageAlpha( $image, 0 )
showImage( $image )
# fade in to 70%
setImageAlpha( $image, 70, 2000 )
# don't forget to wait wait( 2000 ) # fade out setImageAlpha( $image, 0, 2000 )
removeImage ( Image )
  1. The image to be removed
Removes an image.
Though this is not necessary as all images are auto-removed when the script exits, it can be usefull to save TRAM ( Texture memory of the GPU ) if you want to load a bunch of images and can remove some of them in the mid of action. loadImage( image.png, image )
...
...
removeImage( $image )
# $image can now be reassigend ...
...
quit( )

Commands on the scenery

setCanvasColor ( Red, Green, Blue )
  1. red part of the color
  2. green part of the color
  3. blue part of the color
The three values must be integers ranged [0,255].
The higher a value is, the more impact has this color.
E.g. ( 255,0,0 ) is fully red, ( 0,0,0 ) is black, ( 255,255,255 ) is white, ( 0,255,255 ) is cyan.
The default canvas color is black.
rotateBy ( Axis, Degrees, [Time] )
  1. X, Y or Z ( Z is the Axis for 2D rotation )
  2. How much, may be negative or exceed 360° ( float )
  3. How long the rotation shall last ( optional, Integer )
Rotates the whole scenery by some degrees around any 3D Axis relative to it's current rotation. rotateBy( Z, 360, 2000 )
# this would cancel the above statment and start from an arbitrary rotation
# rotateImageBy( Z, 360, 4000 )
wait( 2000 )
rotateImageBy( Z, 360, 4000 )

NOTICE: The scenery lies on top of the screen by default,
i.e. if you rotate them around the X or Y axis, the part towards you will be clipped ( as it's now "outside" the screen )!
To avoid that, move the scenery "into" the screen, e.g. moveTo( Z, 2 )

rotateTo ( Axis, Degrees, [Time] )
  1. X, Y or Z ( Z is the Axis for 2D rotation )
  2. How much, may be negative or exceed 360° ( float )
  3. How long the rotation shall last ( optional, Integer )
Rotates the whole scenery to a specific degree of rotation around any 3D Axis. # rotate around the vertical axis
rotateBy( Y, 360, 2000 )
wait( 500 )
# this will ensure the rotation is set back to 0°
# no matter where it was when the call was made
rotateTo( Y, 0, 1000 )

NOTICE: The scenery lies on top of the screen by default,
i.e. if you rotate them around the X or Y axis, the part towards you will be clipped ( as it's now "outside" the screen )!
To avoid that, move the scenery "into" the screen, e.g. moveTo( Z, 2 )

moveBy ( Axis, Percent, [Time] )
  1. X, Y or Z
  2. How far, may be negative or exceed 100 ( float )
  3. How long the movement shall last ( optional, Integer )
Moves the scenery around the screen. # move the scenery half it's width to the left
moveBy( X, -50, 2000 )
wait( 2000 )
# and back
moveTo( X, 50, 2000 )

NOTICE: Scenery movement distance is relative to the scenery scale!

moveTo ( Axis, Percent, [Time] )
  1. X, Y or Z
  2. How far, may be negative or exceed 100 ( float )
  3. How long the movement shall last ( optional, Integer )
Moves the CENTER of the scenery to a specific position on the screen.
If you pass values outside [0,100] the center of the scenery will leave the screen, what can be usefull to slide in effects # center the scenery on the screen
moveTo( X, 50 )
moveTo( Y, 50 )
scaleBy ( Percent, [Percent], [Time] )
  1. [horizontal] scale factor ( float > 0 )
  2. vertical scale factor ( optional, float > 0 )
  3. How long the scale shall last ( optional, Integer )
Scales the scenery relative to it's current scale. # scale scenery to 20% of the screen
scaleTo( 20, -1 )
# scale by 150%
scaleBy( 150, -1, 2000 )
# the scenery now takes 30% of the screen
scaleTo ( Percent, [Percent], [Time] )
  1. [horizontal] size relative to the scenery ( float > 0 )
  2. vertical size relative to the scenery ( optional, float > 0 )
  3. How long the scale shall last ( optional, Integer )
Scales the scenery relative to the SCREEN. # scale scenery to 20% of the screen
scaleImageTo( $image, 20 )