/////////////////////////////////////////////////////////////////////////////// // XRS Protocol version 0.9.0 // -------------------------- // // (c) 2004 George Pantazopoulos // // "Nothing astonishes men so much as common sense and plain dealing." // -- Ralph Waldo Emerson // /////////////////////////////////////////////////////////////////////////////// Introduction ------------ The XRS Protocol is a communication standard for the network rendering of computer graphics. It defines how a Client program may control one or more Servers to render a 3D image in parallel. The Server and Client programs communicate over the network using platform independent XML-RPC calls, which encode the communication in plain text using XML. The Server and Client can be written in different programming languages. The XRS Protocol was designed with the POV-Ray renderer in mind, but it is also possible to use it with other renderers. Purpose of this document ------------------------ In order for programmers to write clients to interface to the Server, they must know how a Server works, the names of the RPC methods available, and also the expected input arguments as well as the format of any returned results. Server Concepts --------------- The Server's job is to render sections of an image upon request. These subimages are the basic work unit of the Server and are referred to as Tiles. For the POV-Ray renderer (and other renderers), there is often a lengthy period of initialization before an image can be rendered. To avoid doing this initialization over and over for every Tile, we introduce the concept of Sessions. A Session is a period of time dedicated to the rendering of Tiles that belong to the same scene and are based on the same render settings. When a new Session is opened, the renderer loads the scene file and performs as much of the pre-render initialization as possible. Then, the renderer pauses and waits for work requests to arrive. Because the Server maintains its internal state between rendering work requests, the Server can render all work requests without having to repeat the pre-render initialization for each Tile. Typical Server Operation ------------------------ The typical Server operates as a state machine. As an example, my POV-Ray XRS patch defines the following states: STATE_IDLE - Waiting for a new Session. STATE_INIT - Initializing new Session STATE_READY - Waiting for work (Session initialized successfully) STATE_ERROR - Error during previous session, which was aborted. STATE_RENDERING - Rendering. The exact state definitions and transitions are up to the implementation, however both the Client and Server must agree on these. In the case of my POV-Ray XRS Patch: The Server starts up in STATE_IDLE where it waits for a new Session to be requested. Upon receiving a valid NewSession request, the Server goes into STATE_INIT and initializes the renderer. As much pre-render initialization as possible is done in this phase (For POV-Ray this includes parsing the scene file and computing photon maps). If the Server encounters an error during this phase, the Server sets its state to STATE_ERROR, aborts the current session and waits for a new one. Otherwise, the Server is ready to render work units (Tiles) and indicates this by reporting STATE_READY. While Tiles are being rendered, the Server reports STATE_RENDERING. If the Server runs out of work it remains in STATE_READY until NewSession is called. This is because work requests can arrive at any time. It is assumed that the Server has some way of queuing up and tracking work requests and also keeps a record of completed (rendered) Tiles. References ---------- XML-RPC Home Page - http://www.xmlrpc.com POV-Ray (the best 3D renderer! :-) - http://www.povray.org Libiqxmlrpc (a great C++ XML-RPC library) - http://libiqxmlrpc.sourceforge.net ------------------------------------------------------------------------------- /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // Server interface // ---------------- // // Methods that require arguments take an XML-RPC struct as the first argument. // This struct should contain the members that the method requires. // // Servers compatible with this version of the XRS Protocol make the // following methods available for calling via RPC. Methods are called using // the exact name in quotes. // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // XML-RPC data types used (see http://www.xmlrpc.com/spec) // // int // boolean // string // base64 // struct /////////////////////////////////////////////////////////////////////////////// // // "NewSession" RPC Method // ----------------------- // // Initiates a new session on the render server. // // When a new session is started, the Server performs all the initialization // required to render a particular scene. During this step the Server carries // out all initializations that do not need to be done on a per-tile basis, // such as parsing the scene and creating photon maps. // // Since some initialization steps (such as parsing and photons) can take a // long time and also may fail at any time, "NewSession" does NOT wait for // the initialization to complete, but merely sets the process in motion. // Use "Status" to determine if and when the new session has initialized // successfully. // // If a previous session has been started, NewSession causes the server to // close out the old session and remove all tiles from its work queue. Tiles // rendered in a previous session may no longer be accessible for retrieval. // // Input: A struct with the following member(s): // ------------------------------------------------------------ // (string) "command" - Arguments to be passed to the renderer. // ------------------------------------------------------------ // // Output: Returns true to acknowledge that a new session has been started, // or a Fault Response if there was an error. // // Possible errors: // ---------------- // Invalid argument format // // // Notes: // A true response does NOT mean that the session initialized // successfully. The initialization could take an unpredictable // amount of time and may fail at any moment. // // Use "Status" to determine if the session initialized // successfully. If the Server is still busy initializing a // session, "Status" will return STATE_INIT. // // If the session failed to initialize properly (eg. parsing // failed), "Status" will show STATE_ERROR and the Server will // go back to waiting for a "NewSession" request. // // When the Server successfully initializes a session, it will change // its status to STATE_READY. You may now assign work to it by // calling "RenderTile" // // After calling NewSession you should expect that any previous tiles // in the server's work queue and rendered tile queue to be flushed and // no longer accessible. // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "Status" RPC Method // ------------------- // // Queries the status of the Server. // // Input: None // // Returns: // A Status info struct containing the following members: // ----------------------------------------------------------- // (string) "state" - The current state of the Server // (string) "info" - Optional additional state info // ----------------------------------------------------------- // // Returns with a Fault Response if there was an error getting the Status. // // // Status info is composed of two parts: State and StateInfo // // "state" describes what State the Server is in, and must be strictly // from a set of predefined state definitions that are the same for both // client and server. Altering the set of states reported by the Server has a // very high chance of breaking existing Clients. // // "info" on the other hand, provides optional additional info about the // current state. Additional StateInfo definitions may be added to the server // to support newer, more sophisticated clients without breaking existing // clients. Some implementations may use certain StateInfo definitions that may // be depended on by Clients and not entirely optional // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "RenderTile" RPC Method // ----------------------- // // Requests the Server to render the rectangular image region described by the // input arguments. // // The Server queues this request and begins rendering when it is ready and has // finished any other work that was requested earlier. // // Input: A struct describing the image region, with the following members: // ----------------------------------------------------------------- // (int) "id" - unique identifier for the Tile // (int) "sc" - Start Column (X coord of the upper left corner) // (int) "ec" - End Column (X coord the upper right corner) // (int) "sr" - Start Row (Y coord of the upper left corner) // (int) "er" - End Row (Y coord of the lower left corner) // ----------------------------------------------------------------- // // Returns true if the Tile was accepted by the Server or a Fault Response if // there was an error. // // Possible errors: // ---------------- // Invalid argument format // Improper Tile coordinates // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "RetrieveImage" RPC Method // -------------------------- // // Retrieves the image data for the specified Tile (if it has been rendered). // // Input: // A struct that contains the following member(s) // ----------------------------------------------- // (int) "id" - The identifier of the desired Tile // ----------------------------------------------- // // If a value of -1 is used for "id", then the Server retrieves the next // available Tile // // Returns: // A struct containing information about the retrieved image: // ------------------------------------------------------------- // (int) "id" - The identifier of the retrieved image // (string) "filename" - the filename of the image // (base64) "base64data" - the base64-encoded binary image data. // ------------------------------------------------------------- // // A Fault Response is returned in the event of an error. // // Possible errors: // ----------------- // Invalid argument format. // Tile not found. (Probably because it is not ready. Try again later.) // No Images - (No images are ready for retrieval. Try again later.) // // Notes: // Even if the image was retrieved, a record of the rendered tile still // exists on the Server and repeated calls to RetrieveImage (with the same "id // argument) will get the same image over and over again. In order to remove it // from the Server's list, you must explicitly call RemoveFromRenderedTiles // with the tileID of the image that was retrieved. This explicit delete step // is necessary to ensure that a temporary communication glitch doesn't cause a // rendered image to become irretrievable. // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "RemoveFromRenderedTiles" RPC Method // ------------------------------------ // // Searches the list of rendered tiles on the Server and removes the one with // the given tileID (making it no longer accessible). // // Input: A struct that contains the following member(s): // ------------------------------------------------------ // (int) "id" - The identifier of the Tile to be removed. // ------------------------------------------------------ // // Returns true if successful, or a Fault Response if there was an error. // // Possible errors: // Invalid argument format. // Tile not found. // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "Exit" RPC Method // ----------------- // // Commands the Server to terminate operation as soon as possible. // // Input: None // // Returns true to acknowledge receipt of the command. // /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// // // "ProtocolVersion" RPC Method // ---------------------------- // Returns the name and version of the XRS protocol that the server supports. // (eg. XRS 1.0.0) // // // "ServerVersion" RPC Method // -------------------------- // Returns the name and version of the XRS Server (eg. povray-xrs 1.0.2) // // // "RendererVersion" RPC Method // ---------------------------- // Returns the name and version of the renderer that the Server was // (eg. povray 3.6.0) built on top of. // // // Input: None // // Returns: // A struct containing the following members: // ------------------------------------------------------------------ // (string) "name" - The name of the protocol/server/renderer/etc // (int) "major" - Major version number // (int) "minor" - Minor version number // (int) "revision" - Revision number // ------------------------------------------------------------------ // // Returns a fault response if there was an error. // ///////////////////////////////////////////////////////////////////////////////