BuckoSoft Animation Controller


This document describes the BuckoSoft, Inc. Animation Controller. The BSAC is a set of programs used to generate frames for POV-Ray animations across several different networked computers.

BSAC does not generate frames or animations; it just manages and collects frames.

BSAC does not handle partial frame renders.

There are 2 main components to BSAC, the server and the client. In typical operation, the "owner" of the animation will run the client as the director of the animation and make requests to each server asking it to build frames.

Both client and server run on Windows and Linux (other Unix ports to be available later)

+- BuckoSoft Animation Controller
   +- Definitions
   |  +- World
   |  +- Users
   +- Tech Overview
   |  +- Authentication
   |  +- Files
   |  +- BuckoRoot
   +- Operation
   |  +- Client
   |  +- Server
   |  +- Status Checking
   +- Protocol



Generates frames of animation based on the requests of the client.


Maintains a list of servers and requests frames be generated by each.


A name that is unique to the client that defines the base name of the animation.

Tech Overview


Each client/project must have a unique identifier to identify itself to the server.

Each file that is read during a POV-Ray render must be authenticated between the client and server as being the same.

This is accomplished with a date stamp and a checksum. Note that Windows95 uses 2-second resolution on date stamps and BSAC must accommodate that.

Each client/server transaction must authenticate itself to avoid stray frames from undesirable sources entering the stream.

Server Security

Connections are accepted only between a previously established client.

Network Protocols

Each client/server will use 1 TCP port.

Communications port between client/server.

HTTP port used to monitor status of a client or a server and possibly allow configuration.

There are default values for each TCP port, but they must be configurable to allow for multiple servers and a client to run on the same machine, as in the case of a multiple CPU computer.


Client System Files

Client Project Files and Directories


All projects are anchored from a per-project root directory.  This directory can be located anywhere on the client computer and may be called anything.  The term Root/ is just to denote the existence of the project root.


This directory contains the frames that are returned from the servers.


This file contains a list of source files and directories to be included and excluded from this animation render (and the transfer of these files)
The file may contain any number of include exclude directives.  During parsing, the includes and excludes can appear in any order, but during file list generation, the excludes are all checked before the includes.  Wildcards are supported
Each subdirectory in the project may contain a .bsac file to further refine, or cascade the list of included and excluded files.
The default initial internal .bsac file looks like this.
This tells the file searching algorythm that, starting at the Project Root, include all *.pov and *.inc files.  Do not include anything called CVS or Frames; in this case, that would be CVS workspace directory and the generated frames subdirectory.

Note that if you have any imagemap files, then you will have to include them.  Be careful about specing graphics/imagemap files, you don't want to transfer any test renders you've generated!  So including *.tga is a bad idea :)

The .bsac file also supports a conditional, it is possible to specify files to be included only in certain frames.  Your file may look like this:

if %f > 100
This tells the filelist generator that if the frame number is greater than 100, then include the subdirectory critters.

Server System File

Windows (server_installation_dir)\bsacserv.ini
Linux $HOME/.bsacserv.rc

Per Project Root

The client and server each maintain a Project Root. All files to be rendered must be beneath the project root. NOTE that this includes POV-Ray system include files as well. It is imperative that the client/server be operating from the same set of files.

Subdirectories are supported.

Frame Generation

There are 2 styles of frame generation available.

Striped – When a server finishes a frame, the next available frame is given to it to build. Less efficient than the block method, but better for quickly gathering frames for making test animations.

Block – A server is given a range of frames to complete. The server will send each frame to the client on completion



See the Not Yet Written User's Guide for details about running bsac.


Initial Setup

Server Definition


Project Definition


Servers in Project

Server Definition

Defines how the client views each server


Initial Setup

Delete rendered frame after transmission?
ServerRoot Directory

Status Checking


The following statuses can be read from the client via a web browser.

Each section has an accessibility flag associated with it.

Private Only a browser from the client machine can access the status
Limited Browsers running on registered servers can view status.
Public Anyone can view status.
Frames Completed

An overview of the frames that have been completed can be queried. See http://www.buckosoft.com/gallery/raytrace/tteoac/framelist.html for an example.

Servers Status

The server’s status display contains
Each Server in the project.

Last frame completed by each server.

Last communication with each server.

Block assigned to each server.

Other server stats: Frames per hour; total frames completed.


The server can display


Current Project and Frame

Projects Belonged To

That slop right above this sentence is an Office97 WordArt picture defining the data layout in the BSAC configuration database. Converting it to HTML yielded that. (I had expected it to export as a GIF. J)


The basic protocol is HTTP. The client/server command is embedded in the GET request preceded with a hash sign "#". If the hash sign is omitted then the command is assumed to be a browser command and passed along to GUI (browser) for handling.

The protocol works best with "Short requests, long replies". So rather than try to force a file across with a GET, rather the other side is told to ask back to fetch the file.

After the initial GET command, the other attributes of the command are passed as additional HTTP headers. The HTTP request terminates as usual, with a blank line. A typical request looks like this:

GET /#SendFile
Project: haus
Server: spenser.buckosoft.com
Frame: 42
File: porch.inc
Passwd: aUthenticatER

Another aspect of the protocol is that all operations must be autonomous. No interactions may be dependent on any other actions. This could result in Disk Full Syndrome on the server side if the client fails to empty the server. The server therefore can be configured to delete files more than a month old. (Configurable) If the source files are ever needed again, the client will send them again. Any frames rendered and not collected will be lost.

Client/Server Interactions:

Server tells Client that he is online. Client will then query the server if there are things to be done.
Hello Hi ->  
Client checks to see if server is online.
Client will then query the server if there are jobs to be done.
How you doing?
      I am working on frame x for project p. I have n frames in the queue.
Tell me about your files for project p. ->  
      I have these files with these timestamps and checksums.
You need file f for project p ->  
Queues request to fetch the source file.
  ?- Please send me file f for project p.
  200 - Here is the file.    
AcceptingReqs   <- I am accepting a request for rendering
Project: p.
  200 - Thanks for the info
404 - Project doesn't exist

Go raytrace frames x-y ->  
      200 - Starts rendering.
404 - RenderReq rejected.
  ?- I have finished project p frame f with status pass/fail.
Client will then send another RenderReq before asking for the frame output file. This allows rendering to recommence before performing the FetchFrame
Please give me this frame's output. ->  
      Here is the file.
Delete this frame's output. ->  
Deletes file.
Delete all of this project's files. ->  
All files in this project's directory are deleted. The project definition is still kept and can be restarted at any time.

Finite State Machines

Client Per Project States

Each client can maintain and run several projects at once.  Each project has a current state associated with it.  The state pump exists in the form of a system timer.  The state pump will update the current state based on externally detected events.  The project state has evolved into less of a state machine and more of a state/status indicator.
State Event Action New State











Client/Server Interactions Version 2.  No server listen port:

It is desirable to be able to run a server behind a firewall where it doesn't have a listen port.
This protocol enhancement allows this feature to operate.  Note that even though there is no listen port, it is still a server.  It is rendering frames on behalf of a client.

In order for the listen-less server to operate, the meta-server must be running so that servers can locate clients.  Clients are still required to be listen for messages from the servers.

The client registers that it is online with the metaserver.  It also tells the metaserver that it has work.
The server registers with the metaserver that it is online.  The metaserver responds with a list of clients that the server should contact.
The metaserver is then out of the transaction loop for this server->client series.


Server tells Client that he is online.

Do you have any work for me?


Project: projname
Tell me about Project projname

Project: projname

File: fileA.pov (size, timestamp)
File: fileB.pov (size, timestamp)
Give me a source File

File: fileA.pov

File: fileA.pov (size, timestamp)
(Body) fileA.pov
What should i render?

I have finished a frame

Project: projname
Frame: 1

200 = send frame
270 = ignore results
Server is online

contact clients

server: servername
uptime: (# of secs)
queue0: clientname projname frame
queue1: ...

200 = ok
271 = not registered
client: clientname
Server is registering

server: servername
user: ownerID

200 = ok
Client is online

client: clientname
uptime: (# of secs)
serversInUse: servername

200 = ok
272 = not registered
Client is registering

client: clientname
fqdn: clientHostName
user: ownerID

200 = ok
Error code Detail
200 Success
270 Success, but ignore results
350 Not Registered.
404 Not found. An unknown command was issued