readme

Ray tracing on PS3, using the acceleration of PPU, No SPE acceleration is used. The code must be com

blue-steel Release 1.0 - 4/5/2007
Author: Brian Sweatt ([e-mail])

To Compile:

In the blue-steel home directory, type make to compile the default pong demo provided with blue-steel.

The source for pong, as well as the PPU API is contained in the PPU directory. A sample Makefile for
compiling pong is also provided therein. This Makefile shows the typical object files that must be 
imported for a program using blue-steel to function properly. Additionally, in order to correctly support
the blue-steel frame buffer methods, the directories containing the system frame buffer files must 
be included in the xlc flags, as shown in the sample Makefile.

Pong compiles into the main directory as a binary named blue-steel. This program accepts a single command
line option: an integer denoting the number of SPUs to dedicate to rendering.

blue-steel has been compiled and tested with IBM xlC. Compatability with gcc is not guaranteed as there
are a number of nested anonymous structures used in the shading system that gcc does not agree with.


Summary

blue-steel is a parallel ray tracer utilizing the synergistic processing elements of the CBEA
to render complex scenes composed of triangles, spheres, a number of different light sources,
as well as complex procedural shaders.

blue-steel also provides a simple interface to the PS3 frame buffer for writing prerendered images 
to the screen.


API

The blue-steel API is accessible from the ppu folder, in bsapi.h. This provides a number of
methods for sending messages to individual rendering SPUs, as well as methods for performing
operations on the rendering system as a whole. This API consists of the following methods:

bsInit(ObjectSet *objects)
  This method initializes blue-steel with the given ObjectSet as the scene to be rendered.
  Currently, this ObjectSet cannot be changed, so all frames rendered by the system must be
  Transformations applied to the objects in the given set. This ObjectSet need only be passed
  into this initialization function once, and all updates to the objects in the set will 
  automatically be reflected in the rendered image.
  The ObjectSet structure can be found in src/objectset.h.

bsSetCenter(float x, float y, float z)
  Sets the center position for the pinhole perspective camera used in rendering the scene.
  In order to render a meaningful view of the scene, this must be set before rendering.

bsLookAt(float x, float y, float z, float ux, float uy, float uz)
  Sets the direction and orientation of the camera. The position of the camera should first be
  set using bsSetCenter. Calling this method causes the camera to look from the current center
  position towards the point in space represented by (x,y,z). The camera orients itself so
  that the 'up' direction is the normalized (ux, uy, uz) direction.

bsSetAmbient(float r, float g, float b)
  Sets the constant ambient lighting term to be applied to all surfaces rendered.

bsRenderScene(vector unsigned int *image)
  Starts the asynchronous process of rendering the current scene (stored in the objects pointer
  passed to the bsInit procedure). image is a pointer to a two dimensional array that will
  be filled with the image data. The width of this array should be (SCREEN_WIDTH/4), since a 
  vector unsigned int will hold 4 32-bit RGBA color values. The height of this array should be
  the screen height. Each vector unsigned int in the image holds color data as specified by 
  the IBM Cell SDK's _pack_rgba8_v method. See the IBM documentation for details.

bsDone()
  Returns true if the last rendering process invoked has finished, or false otherwise

bsWait()
  Stalls executions until the last rendering process invoked has finished. Upon returning from
  a call to bsWait(), the image pointer passed in to bsRenderScene has been completely filled
  with the rendered image data.

Frame Buffer Interface
  See src/fb.h for details. 

Known Issues

- Noise in checkerboard texture / refraction at large distances:
  This is an issue with the floating point precision of certain SPU operations, as well as the 
  sensivity of the checkerboard and refracted rays to imprecisions in the calculations. In
  particular, the reciprocal and square root methods provided in the most recent Cell SDK are
  prone to low precision in the results. For best results, triangles using the checkerboard
  material should have an area no greater than 2. To represent larger triangles, subdivide. 
  Noise in transparent surfaces occurs at distances from the camera greater than about 10. For
  scenes that require such distances, shrinking the model and moving the camera closer should
  eliminate noise in the image.