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)
 
 

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

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