Advertisement
=============

To look on the example functions, there is 'Edit...' button in the respective plugin dialog, but you may need a text editor. By default, it is `emacs', and nothing has to be done if it is installed. If not, you can set your favorite editor via the corresponding environment variable, like those:

export CIN_EDITOR=kate
export CIN_EDITOR=nedit
export CIN_EDITOR='konsole -e vim'

If text editor is a console editor without its own GUI, it must be run from some terminal emulator, like `xterm' or `konsole'.

Example 1.
----------

Let's say, we are going to write our own implementation of the Arithmetic Subtract overlay function, according to the formula from CinelerraGG manual. Such a function, attached to the Blend Algebra plugin, could look as follows.

------------------------------------------------------------------------
BLEND_ALGEBRA_INIT /* this is a required statement */

COLORSPACE_RGB /* our working color space, can be also YUV or HSV */
PARALLEL_SAFE /* can be safely parallelized */
REQUIRE_TRACKS(2) /* refuse to work if only one track is given */

BLEND_ALGEBRA_PROC /* this is a required statement */

#define s 1 /* mnemonics for source and destination */
#define d 0

R_OUT = R(s) - R(d); /* for red, green, blue, alpha: */
G_OUT = G(s) - G(d); /* result = source - destination */
B_OUT = B(s) - B(d);
A_OUT = A(s) - A(d);

BLEND_ALGEBRA_END /* this marks the end of our program */
------------------------------------------------------------------------

And here is an Arithmetic Addition variant, working on any number of tracks.

------------------------------------------------------------------------
BLEND_ALGEBRA_INIT

COLORSPACE_RGB
PARALLEL_SAFE

BLEND_ALGEBRA_PROC

int i;

R_OUT = G_OUT = B_OUT = A_OUT = 0; /* preinitialize results */

for (i=0; i<TOTAL_TRACKS; i++) /* repeat for all tracks */
{
  R_OUT += R(i); /* accumulate sum for R,G,B,A */
  G_OUT += G(i);
  B_OUT += B(i);
  A_OUT += A(i);
}

BLEND_ALGEBRA_END
------------------------------------------------------------------------

Blend Algebra functions can be keyframable, i.e. switched between plugin keyframes. Untar the ovl2.tar.gz archive, load the ovl2.xml project and play it. You can see 30 different functions switched one after another. The source files of the functions have the suffix '.ba'.

Example 2.
----------

Let's look on the following short Blend Algebra function:

------------------------------------------------------------------------
BLEND_ALGEBRA_INIT

COLORSPACE_YUV
PARALLEL_SAFE
REQUIRE_TRACKS(2)

BLEND_ALGEBRA_PROC

Y_OUT = (Y(0)-Y(1))/2+0.5;
U_OUT = V_OUT = 0;
A_OUT = 1;

BLEND_ALGEBRA_END
------------------------------------------------------------------------

What do you think this is? It is nothing else as the famous `ydiff' program, written in less than 10 lines of code and working not externally, but directly inside a Cinelerra plugin. Although this is not yet so complete, the standard ydiff program has an argument to enhance or reduce the difference effect, but we can easily add it here, too:

------------------------------------------------------------------------
BLEND_ALGEBRA_INIT

COLORSPACE_YUV
PARALLEL_SAFE
REQUIRE_TRACKS(2)

BLEND_ALGEBRA_PROC

Y_OUT = (Y(0)-Y(1))/2*exp((KEY_A-0.5)*14*M_LN2)+0.5;
U_OUT = V_OUT = 0;
A_OUT = 1;

BLEND_ALGEBRA_END
------------------------------------------------------------------------

Here we changed only the expression for Y, adding a factor which depends on the KEY_A parameter in logarithmic scale. The KEY_A parameter itself is interactively controlled by the opacity slider in the Blend Algebra plugin dialog.

Good, the ydiff program additionally prints some statistics. This printout can also be implemented by us, although the program becomes slightly more complex:

------------------------------------------------------------------------
static int npix=0; /* these variables will accumulate statistics */
static float sum=0, sabs=0; /* parallelizing not possible here */

BLEND_ALGEBRA_INIT

COLORSPACE_YUV
REQUIRE_TRACKS(2)

printf ("sz=%8d err=%10g abs=%10g", npix, sum, sabs);
if (npix > 0) printf (" rel=%10g", sabs*256/npix);
printf ("\n"); /* here we print statistics in CGG console */
sum = sabs = 0; /* and clear accumulators for the next frame */
npix = 0;

BLEND_ALGEBRA_PROC

float diff;
diff = Y(0)-Y(1);
sum += diff; /* update accumulators */
sabs += ABS (diff);
npix ++;

Y_OUT = (Y(0)-Y(1))/2*exp((KEY_A-0.5)*14*M_LN2)+0.5;
U_OUT = V_OUT = 0; /* and make video track output */
A_OUT = 1;

BLEND_ALGEBRA_END
------------------------------------------------------------------------

The statistics is printed in the terminal emulator from which Cinelerra was started.

You can look in the ydiff.tar.gz archive. In the project ydiff.xml there are two identical tracks displaced by 1 frame. The ydiff.ba function from the archive has the commented out line #define NO_PRINTOUT. It works slowly because of statistics printout. If you uncomment this definition, statistics will be switched off, the function will run parallelized, noticeably faster.

Example 3.
----------

Untar the example archive transitions.tar.gz and load the project transitions.xml. It demonstrates how transitions-like effects can be imitated by a Blend Algebra function. Here, depending on the current value of the opacity slider from plugin's dialog, interpolated between keyframes, and the (X,Y) pixel coordinates, the function takes pixels of either track #0 or track 0000001.

Example 4.
----------

Untar the archive swap.tar.gz and load the project swap.xml. Now there is another companion plugin, Blend Program, with its function swap01.bp (ending with the .bp suffix). This example resembles the preceding one which imitated transition. The main difference here is that blend program does not return a function result, but modifies any given tracks directly. The program from this example swaps two tracks, along a transition controlled by keyframable interpolated opacity parameter. To see the effect, the bottom track is up-down reflected, and the top one has a mask applied, through which one can see that the bottom track is also changed.

Example 5.
----------

The preceding example was perhaps somehow artificial demo, not too close to reality. Let's now suggest another application which could be really useful. Untar the ck.tar.gz example and load firstly the project ck.xml.

There is a still picture and a second track with solid white background on bottom. The blend function attached is:

------------------------------------------------------------------------
BLEND_PROGRAM_INIT

COLORSPACE_HSV
PARALLEL_SAFE

BLEND_PROGRAM_PROC

if (ABS(H(0)-KEY_H) < KEY_A*100) A(0) *= SQR((H(0)-KEY_H)/KEY_A/100);

BLEND_PROGRAM_END
------------------------------------------------------------------------

It is a rather complete chromakey plugin, writable by user in only six lines of code! Isn't it cool! With these two new small plugins one can do really much! I do not know if a similar functionality exists in any other NLE.

Here if the 'Hue' component (in HSV color space) differs from that of the key color defined in the plugin dialog less than by the amount scaled by the opacity slider, the aplha component (the transparency) is set proportional to the squared difference (completely transparent where the two Hues are identical). You can open plugin dialog and turn the slider in it to the left and right and see its effect.

Now load another project from here, ckbg.xml. Now there is only one track with the same picture. Instead of the second one contained the background, there is one more Blend Program plugin attached, its function generating the desired background by itlesf. The background color is set via the color selection dialog of the Blend Program plugin GUI.