The Smallest FLIC animation player

Skip to main content (skip navigation menu)






The Smallest FLIC animation player

 

The purpose of this page is to create the smallest animation player for the EGI frame animation toolkit in various programming languages/systems. To test the little programs presented here, you need the evaluation version, which can downloaded from its own page, or (of course) the retail release of EGI.

The languages covered in this paper are:

Most programming courses and tutorials start with a "Hello world" style program —the smallest real-world program that "does something" in the language of choice. In a similar vein I wish to introduce the topic of programming the EGI API with the smallest functional program that I could come up with: TINY. Note that the TINY program is also included (in various versions) in the evaluation version of EGI.

What TINY does is:

Since the example programs are so small, each of these steps is easily recognizable in the source code. The C++ example does not do the "clean up" step explicitly, but leaves it to the destructors of the FlicAnim and FlicWindow classes).

The smallest example

The EGI players are currently available as DLLs for Microsoft Windows. Consequently, writing a program that uses EGI necessarily means writing a Microsoft Windows application. And writing a Windows application means: registering window classes, creating windows, writing message handlers (the callback functions), writing a message loop, dealing with resource and linker definition files,... those few calls to the EGI player would be hard to spot between those nearly 100 lines of Windows API ballast.

I set out to cut off this weight by making creative use of the Windows functions. The user interface of TINY is restricted to a message box (and hence, no message loop is needed). The FLIC file is played back in a window that is pre-registered by the EGI player. This window is palette-aware and correctly repaints the FLIC file if one is attached to it. With these tricks, a complete program that plays a FLIC file is now less than 30 lines. (If your compiler requires a .DEF file, use a dummy one; TINY does not export any functions.)

Despite its simplicity, TINY shows the most important EGI functions. The program is so straightforward that the source code should speak for itself. The only thing worth mentioning is that TINY sets the width and height to CW_USEDEFAULT, which causes the animation window to adjust itself to the size of the animation frame.

The tiniest example (in the C programming language)
#include <windows.h>
#include "eplay.h"

int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                   LPSTR lpCmdLine, int nCmdShow)
{
  LPFLIC lpFlic;
  HWND hwnd;

  if ((lpFlic=FlicOpenEx("fanni1.flc", 0, NULL)) != NULL) {

    hwnd = FlicCreateWindow("", WS_POPUP | WS_BORDER | WS_VISIBLE,
                            0, 0, CW_USEDEFAULT, CW_USEDEFAULT, NULL, 0);

    FlicPlay(lpFlic, hwnd);

    MessageBox(NULL,"FLIC file now playing\n"
               "click \"OK\" to stop.", NULL, MB_OK);

    FlicClose(lpFlic);
    DestroyWindow(hwnd);

  } else {

    MessageBox(NULL, "Unable to open FLIC file", NULL, MB_OK);

  } /* if */
  return 0;
}

An important limitation of TINY.C is that the window that it creates is neither a child window, nor the "active" window. The active window is the message box that pops up to tell that you the FLIC file is playing. For reasons explained better in the paper The Microsoft Windows Palette Manager, only the active window can realize its palette as a foreground palette. Palettes of windows that are not the foreground window are always realized in the background. What this means is that the animation that TINY.C plays uses the palette of the "MessageBox", until you activate the animation window with a mouse click in its caption.

Tiny in C++

TINY.C cuts away much of the overhead that Microsoft Windows imposes on a Windows application. By reducing the overhead of the (rather low level) C language, you can make the program smaller still. The example in C++ below does so by letting the constructor and destructor open and close the FLIC file automatically.

The tiniest example in C++
#include <windows.h>
#include "eplay.h"

int PASCAL WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
{
  FlicAnim anim("fanni1.flc");
  if (anim) {

    FlicWindow wnd("", WS_POPUP | WS_BORDER | WS_VISIBLE, 0, 0);

    anim.Play(wnd);

    MessageBox(NULL,"FLIC file now playing\n"
               "click \"OK\" to stop.", NULL, MB_OK);

  } else {

    MessageBox(NULL, "Unable to open FLIC file", NULL, MB_OK);

  } /* if */
  return 0;
}

The complete C++ interface is defined in the file EPLAY.H. The interface is just a thin wrapper around the API (which already was designed as an "abstract data type").

The constructor of the FlicAnim call takes three optional arguments, the first of which is the filename of the FLIC file to open. The destructor of the class closes the FLIC file. You can also open and close a file explicitly with the ::Open and ::Close methods.

Tiny in Delphi

The C version of the TINY program is effortlessly converted to Borland Delphi. Below is what the sample looks like in the PASCAL language:

The tiniest example in Delphi
program tiny;
{$APPTYPE GUI}

uses Windows, eplay;

var
  Flic   : LPFLIC;
  window : HWND;

begin
  Flic := FlicOpenEx('fanni1.flc', 0, Nil);
  if Flic <> Nil then
  begin

    window := FlicCreateWindow('', WS_POPUP or WS_BORDER or WS_VISIBLE,
                               0, 0, cw_UseDefault, cw_UseDefault, 0, 0);

    FlicPlay(Flic, window);

    MessageBox(0, 'FLIC file now playing; click "OK" to stop.',
               Nil, MB_OK);

    FlicClose(Flic);
    DestroyWindow(window);

  end else
    MessageBox(0, 'Unable to open FLIC file', Nil, MB_OK);
end.

The Delphi program needs the Eplay unit. This unit can be compiled from the EPLAY.PAS file that you can find in the INCLUDE subdirectory of where EGI is installed.

Tiny in Visual Basic

When we start a new project, we can insert the snippet below as the form's code. In addition to the code, we also need to add a "reference" to the player DLL in the Visual Basic project. After adding the reference, the EGI function and constant definitions are available from the object browser.

The "Object browser" window is available from the "View" sub-menu, or with function key F2.

The tiniest example in Visual Basic
Dim Flic As Long

Private Sub Form_Load()
    ' You will probably need to change the line below.
    Dim FlicFile As String
    FlicFile = "c:\egi\examples\fanni1.flc"

    ' Open the FLIC file.
    Flic = FlicOpenEx(FlicFile, FLIC_FLAG_SCRIPT, "")
    If (Flic <> 0) Then
        FlicWidth% = FlicGetParam(Flic, FLIC_PARAM_WIDTH)
        FlicHeight% = FlicGetParam(Flic, FLIC_PARAM_HEIGHT)

        ' Create the animation window
        Dim FlicWindow As Long
        FlicWindow = FlicCreateWindow("", 0, 80, 10, FlicWidth%, FlicHeight%, hWnd, 0)

        ' Play the FLIC file in its window
        FlicPlay Flic, FlicWindow
    End If
End Sub

Private Sub Form_Unload(Cancel As Integer)
    If Flic <> 0 Then
        FlicClose Flic
    End If
End Sub

End notes

The primary purpose of this paper is to show you how easy it is to use the EGI player in your program, regardless of the programming language that you use.

The TINY program plays an animation in its own window. While this may suit many applications, you may instead want to play the animation in an application window that you create and manages specifically. This allows, for example, to play several animations in the same window. There is a separate note, "An EGI player in C++" that shows you how to do this.

EGI features transparency, with various kinds of masks, but the TINY program ignores masks completely. A modified version of TINY that plays back animations transparently on the desktop is in the paper "Transparent animations on the desktop".