org.sunflow

Class SunflowAPI

Known Direct Subclasses:
RealtimeBenchmark

public class SunflowAPI
extends java.lang.Object

This API gives a simple interface for creating scenes procedurally. This is the main entry point to Sunflow. To use this class, extend from it and implement the build method which may execute arbitrary code to create a scene.

Field Summary

static String
DEFAULT_OPTIONS
static String
VERSION

Constructor Summary

SunflowAPI()
Creates an empty scene.

Method Summary

void
addIncludeSearchPath(String path)
Add the specified path to the list of directories which are searched automatically to resolve scene filenames.
void
addTextureSearchPath(String path)
Adds the specified path to the list of directories which are searched automatically to resolve texture filenames.
void
build()
This method does nothing, but may be overriden to create scenes procedurally.
void
camera(String name, CameraLens lens)
Defines a camera with a given name.
static SunflowAPI
compile(String code)
Compile the specified code string via Janino.
static SunflowAPI
create(String filename, int frameNumber)
Create an API object from the specified file.
void
geometry(String name, PrimitiveList primitives)
Defines a geometry with a given name.
void
geometry(String name, Tesselatable tesselatable)
Defines a geometry with a given name.
BoundingBox
getBounds()
Retrieve the bounding box of the scene.
int
getCurrentFrame()
Read the value of the current frame.
String
getUniqueName(String prefix)
Returns a name currently not being used by any other object.
void
instance(String name, String geoname)
Instance the specified geometry into the scene.
void
light(String name, LightSource light)
Adds the specified light to the scene.
Geometry
lookupGeometry(String name)
Retrieve a geometry object by its name, or null if no geometry was found, or if the specified object is not a geometry.
Modifier
lookupModifier(String name)
Retrieve a modifier object by its name, or null if no modifier was found, or if the specified object is not a modifier.
Shader
lookupShader(String name)
Retrieve a shader object by its name, or null if no shader was found, or if the specified object is not a shader.
void
modifier(String name, Modifier modifier)
Defines a modifier with a given name.
void
options(String name)
Defines an option object to hold the current parameters.
void
parameter(String name, String value)
Declare a parameter with the specified name and value.
void
parameter(String name, String type, String interpolation, float[] data)
Declare a parameter with the specified name.
void
parameter(String name, String[] value)
Declare a parameter with the specified name and value.
void
parameter(String name, boolean value)
Declare a parameter with the specified name and value.
void
parameter(String name, float value)
Declare a parameter with the specified name and value.
void
parameter(String name, int value)
Declare a parameter with the specified name and value.
void
parameter(String name, int[] value)
Declare a parameter with the specified name and value.
void
parameter(String name, Color value)
Declare a parameter with the specified name and value.
void
parameter(String name, Matrix4 value)
Declare a parameter with the specified name and value.
void
parameter(String name, Point3 value)
Declare a parameter with the specified name and value.
void
parameter(String name, Vector3 value)
Declare a parameter with the specified name and value.
boolean
parse(String filename)
Parse the specified filename.
void
remove(String name)
Remove the specified render object.
void
render(String optionsName, Display display)
Render using the specified options and the specified display.
void
reset()
Reset the state of the API completely.
String
resolveIncludeFilename(String filename)
Attempts to resolve the specified filename by checking it against the include search path.
String
resolveTextureFilename(String filename)
Attempts to resolve the specified filename by checking it against the texture search path.
static void
runSystemCheck()
This is a quick system test which verifies that the user has launched Java properly.
void
setCurrentFrame(int currentFrame)
Set the value of the current frame.
void
shader(String name, Shader shader)
Defines a shader with a given name.
void
shaderOverride(String name, boolean photonOverride)
Sets a global shader override to the specified shader name.
boolean
update(String name)
Update the specfied object using the currently active parameter list.

Field Details

DEFAULT_OPTIONS

public static final String DEFAULT_OPTIONS

VERSION

public static final String VERSION

Constructor Details

SunflowAPI

public SunflowAPI()
Creates an empty scene.

Method Details

addIncludeSearchPath

public final void addIncludeSearchPath(String path)
Add the specified path to the list of directories which are searched automatically to resolve scene filenames.
Parameters:
path -

addTextureSearchPath

public final void addTextureSearchPath(String path)
Adds the specified path to the list of directories which are searched automatically to resolve texture filenames.

build

public void build()
This method does nothing, but may be overriden to create scenes procedurally.

camera

public final void camera(String name,
                         CameraLens lens)
Defines a camera with a given name. The camera is built from the specified CameraLens. If the lens object is null, the camera with the given name will be updated (if it exists). It isn't possible to change the lens of an existing camera.
Parameters:
name - camera name
lens - camera lens to use

compile

public static SunflowAPI compile(String code)
Compile the specified code string via Janino. The code must implement a build method as described above. The build method is not called on the output, it is up the caller to do so.
Parameters:
code - java code string
Returns:
a valid SunflowAPI object upon succes, null otherwise.

create

public static SunflowAPI create(String filename,
                                int frameNumber)
Create an API object from the specified file. Java files are read by Janino and are expected to implement a build method (they implement a derived class of SunflowAPI. The build method is called if the code compiles succesfully. Other files types are handled by the parse method.
Parameters:
filename - filename to load
Returns:
a valid SunflowAPI object or null on failure

geometry

public final void geometry(String name,
                           PrimitiveList primitives)
Defines a geometry with a given name. The geometry is built from the specified PrimitiveList. If the primitives object is null, the geometry with the given name will be updated (if it exists).
Parameters:
name - a unique name given to the geometry
primitives - primitives to create the geometry from

geometry

public final void geometry(String name,
                           Tesselatable tesselatable)
Defines a geometry with a given name. The geometry is built from the specified Tesselatable. If the object is null, the geometry with the given name will be updated (if it exists).
Parameters:
name - a unique name given to the geometry
tesselatable - the tesselatable object to create the geometry from

getBounds

public final BoundingBox getBounds()
Retrieve the bounding box of the scene. This method will be valid only after a first call to render(String,Display) has been made.

getCurrentFrame

public int getCurrentFrame()
Read the value of the current frame. This value is intended only for procedural animation creation. It is not used by the Sunflow core in anyway. The default value is 1.
Returns:
current frame number

getUniqueName

public final String getUniqueName(String prefix)
Returns a name currently not being used by any other object. The returned name is of the form "prefix_n" where n is an integer starting at 1. Only a simple linear search is performed, so this method should be used only when there is no other way to guarentee uniqueness.
Parameters:
prefix - name prefix
Returns:
a unique name not used by any rendering object

instance

public final void instance(String name,
                           String geoname)
Instance the specified geometry into the scene. If geoname is null, the specified instance object will be updated (if it exists). It is not possible to change the instancing relationship after the instance has been created.
Parameters:
name - instance name
geoname - name of the geometry to instance

light

public final void light(String name,
                        LightSource light)
Adds the specified light to the scene.
Parameters:
light - light source object

lookupGeometry

public final Geometry lookupGeometry(String name)
Retrieve a geometry object by its name, or null if no geometry was found, or if the specified object is not a geometry.
Parameters:
name - geometry name
Returns:
the geometry object associated with that name

lookupModifier

public final Modifier lookupModifier(String name)
Retrieve a modifier object by its name, or null if no modifier was found, or if the specified object is not a modifier.
Parameters:
name - modifier name
Returns:
the modifier object associated with that name

lookupShader

public final Shader lookupShader(String name)
Retrieve a shader object by its name, or null if no shader was found, or if the specified object is not a shader.
Parameters:
name - shader name
Returns:
the shader object associated with that name

modifier

public final void modifier(String name,
                           Modifier modifier)
Defines a modifier with a given name. If the modifier object is null, the modifier with the given name will be updated (if it exists).
Parameters:
name - a unique name given to the modifier
modifier - a modifier object

options

public final void options(String name)
Defines an option object to hold the current parameters. If the object already exists, the values will simply override previous ones.
Parameters:
name -

parameter

public final void parameter(String name,
                            String value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            String type,
                            String interpolation,
                            float[] data)
Parameters:
name - parameter name
type - parameter data type
interpolation - parameter interpolation mode
data - raw floating point data

parameter

public final void parameter(String name,
                            String[] value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            boolean value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            float value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            int value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            int[] value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            Color value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            Matrix4 value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            Point3 value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parameter

public final void parameter(String name,
                            Vector3 value)
Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
Parameters:
name - parameter name
value - parameter value

parse

public final boolean parse(String filename)
Parse the specified filename. The include paths are searched first. The contents of the file are simply added to the active scene. This allows to break up a scene into parts, even across file formats. The appropriate parser is chosen based on file extension.
Parameters:
filename - filename to load
Returns:
true upon sucess, false if an error occured.

remove

public void remove(String name)
Remove the specified render object. Note that this may cause the removal of other objects which depended on it.
Parameters:
name - name of the object to remove

render

public final void render(String optionsName,
                         Display display)
Render using the specified options and the specified display. If the specified options do not exist - defaults will be used.
Parameters:
optionsName - name of the RenderObject which contains the options
display - display object

reset

public final void reset()
Reset the state of the API completely. The object table is cleared, and all search paths areset back to their default values.

resolveIncludeFilename

public final String resolveIncludeFilename(String filename)
Attempts to resolve the specified filename by checking it against the include search path.
Parameters:
filename - filename
Returns:
a path which matches the filename, or filename if no matches are found

resolveTextureFilename

public final String resolveTextureFilename(String filename)
Attempts to resolve the specified filename by checking it against the texture search path.
Parameters:
filename - filename
Returns:
a path which matches the filename, or filename if no matches are found

runSystemCheck

public static void runSystemCheck()
This is a quick system test which verifies that the user has launched Java properly.

setCurrentFrame

public void setCurrentFrame(int currentFrame)
Set the value of the current frame. This value is intended only for procedural animation creation. It is not used by the Sunflow core in anyway. The default value is 1.
Parameters:
currentFrame - current frame number

shader

public final void shader(String name,
                         Shader shader)
Defines a shader with a given name. If the shader object is null, the shader with the given name will be updated (if it exists).
Parameters:
name - a unique name given to the shader
shader - a shader object

shaderOverride

public final void shaderOverride(String name,
                                 boolean photonOverride)
Sets a global shader override to the specified shader name. If the shader is not found, the overriding is disabled. The second parameter controls whether the override applies to the photon tracing process.
Parameters:
name - shader name
photonOverride - apply override to photon tracing phase

update

public boolean update(String name)
Update the specfied object using the currently active parameter list. The object is removed if the update fails to avoid leaving inconsistently set objects in the list.
Parameters:
name - name of the object to update
Returns:
true if the update was succesfull, or false if the update failed