BuckoSoft Animation Controller

Overview

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)

Definitions

Server

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

Client

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

Project

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

Tech Overview

Authentication

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.

Files

Client System Files

Client Project Files and Directories

Root/

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.

Root/Frames/

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

Root/.bsac

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.

Include
*.pov
*.inc
Exclude
CVS
Frames

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:

Include
myHeightField.gif
if %f > 100
critters

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

Users

Operation

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

Client

Initial Setup

Server Definition

Name

Project Definition

Striped/Block

Servers in Project

Server Definition

Defines how the client views each server

Server

Initial Setup

Name
Port
Delete rendered frame after transmission?
ServerRoot Directory

Status Checking

Client

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.

Server

The server can display

Active/Inactive

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)

Protocol

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:

Command	Client		Server
Hello		?-	Hi.
	Hi. Server tells Client that he is online. Client will then query the server if there are things to be done.
Hello	Hi	->
			Hi. Client checks to see if server is online. Client will then query the server if there are jobs to be done.
StatCheck	How you doing?	->
			I am working on frame x for project p. I have n frames in the queue.
ProjectCheck	Tell me about your files for project p.	->
			I have these files with these timestamps and checksums.
AddFile	You need file f for project p	->
			Ok. Queues request to fetch the source file.
SendFile		?-	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
RenderReq	Go raytrace frames x-y	->
			200 - Starts rendering. 404 - RenderReq rejected.
RenderDone		?-	I have finished project p frame f with status pass/fail.
	OK. Client will then send another RenderReq before asking for the frame output file. This allows rendering to recommence before performing the FetchFrame
FetchFrame	Please give me this frame's output.	->
			Here is the file.
DeleteFrame	Delete this frame's output.	->
			Ok. Deletes file.
DeleteProject	Delete all of this project's files.	->
			Ok. 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
ps_init
ps_noRootDirectory
ps_noFramesDirectory
ps_noFiles
ps_noServers
ps_idle
ps_run
ps_waitFrames
ps_complete
ps_errors
ps_internalError

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.

Overview
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.

Command	Server	Client
S2Hello
	Hi. Server tells Client that he is online.
S2Status

S2StatusQuery	Do you have any work for me?
		Project: projname
S2ProjectQuery	Tell me about Project projname
	Project: projname	File: fileA.pov (size, timestamp) File: fileB.pov (size, timestamp) ...
S2RequestFile	Give me a source File
	File: fileA.pov	File: fileA.pov (size, timestamp) (Body) fileA.pov
S2RequestRender	What should i render?

S2RenderFinish	I have finished a frame
	Project: projname Frame: 1	200 = send frame 270 = ignore results
S2MetaStatus	Server is online	contact clients
	server: servername uptime: (# of secs) queue0: clientname projname frame queue1: ...	200 = ok 271 = not registered client: clientname
S2MetaRegister	Server is registering
	server: servername user: ownerID	200 = ok
C2MetaStatus	Client is online
	client: clientname uptime: (# of secs) serversInUse: servername	200 = ok 272 = not registered
C2MetaRegister	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