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.
addIncludeSearchPath
public final void addIncludeSearchPath(String path)
Add the specified path to the list of directories which are searched
automatically to resolve scene filenames.
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.
name
- camera namelens
- 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.
- 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.
filename
- filename to load
- 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).
name
- a unique name given to the geometryprimitives
- 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).
name
- a unique name given to the geometrytesselatable
- 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.
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.
- 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.
name
- instance namegeoname
- name of the geometry to instance
light
public final void light(String name,
LightSource light)
Adds the specified light to the scene.
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.
- 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.
- 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.
- 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).
name
- a unique name given to the modifiermodifier
- 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.
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.
name
- parameter namevalue
- parameter value
parameter
public final void parameter(String name,
String type,
String interpolation,
float[] data)
Declare a parameter with the specified name. The type may be one of the
follow: "float", "point", "vector", "texcoord", "matrix". The
interpolation determines how the parameter is to be interpreted over
surface (see
ParameterList.InterpolationType
). The data is specified in a
flattened float array.
name
- parameter nametype
- parameter data typeinterpolation
- parameter interpolation modedata
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
name
- parameter namevalue
- 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.
filename
- filename to load
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.
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.
optionsName
- name of the RenderObject
which contains the
optionsdisplay
- 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.
- 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.
- 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.
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).
name
- a unique name given to the shadershader
- 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.
name
- shader namephotonOverride
- 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.
name
- name of the object to update
true
if the update was succesfull, or
false
if the update failed