Package org.sunflow

## Class SunflowAPI

- java.lang.Object
- - org.sunflow.SunflowAPI

- All Implemented Interfaces:
    `SunflowAPIInterface`
  Direct Known Subclasses:
    `RealtimeBenchmark`

      public class SunflowAPI
      extends java.lang.Object
      implements SunflowAPIInterface

  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

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `DEFAULT_OPTIONS` |
    `static java.lang.String` | `VERSION` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SunflowAPI()` | Creates an empty scene.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `build()` | This method does nothing, but may be overriden to create scenes procedurally.
    `void` | `camera​(java.lang.String name, java.lang.String lensType)` | Defines a camera with a given name.
    `static SunflowAPI` | `compile​(java.lang.String code)` | Compile the specified code string via Janino.
    `static SunflowAPI` | `create​(java.lang.String filename, int frameNumber)` | Create an API object from the specified file.
    `int` | `currentFrame()` | Read the value of the current frame.
    `void` | `currentFrame​(int currentFrame)` | Set the value of the current frame.
    `void` | `geometry​(java.lang.String name, java.lang.String typeName)` | Defines a geometry with a given name.
    `BoundingBox` | `getBounds()` | Retrieve the bounding box of the scene.
    `TextureCache` | `getTextureCache()` |
    `boolean` | `include​(java.lang.String filename)` | Parse the specified filename.
    `void` | `instance​(java.lang.String name, java.lang.String geoname)` | Instance the specified geometry into the scene.
    `void` | `light​(java.lang.String name, java.lang.String lightType)` | Defines a light source with a given name.
    `Geometry` | `lookupGeometry​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String name, java.lang.String modifierType)` | Defines a modifier with a given name.
    `void` | `options​(java.lang.String name)` | Defines an option object to hold the current parameters.
    `void` | `parameter​(java.lang.String name, boolean value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, float value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, int value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, int[] value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, java.lang.String value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, java.lang.String[] value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, java.lang.String colorspace, float... data)` | Declare a color parameter in the given colorspace using the specified name and value.
    `void` | `parameter​(java.lang.String name, java.lang.String type, java.lang.String interpolation, float[] data)` | Declare a parameter with the specified name.
    `void` | `parameter​(java.lang.String name, Matrix4 value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, Point2 value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, Point3 value)` | Declare a parameter with the specified name and value.
    `void` | `parameter​(java.lang.String name, Vector3 value)` | Declare a parameter with the specified name and value.
    `void` | `plugin​(java.lang.String type, java.lang.String name, java.lang.String code)` | Declare a plugin of the specified type with the given name from a java code string.
    `void` | `remove​(java.lang.String name)` | Remove the specified render object.
    `void` | `render​(java.lang.String optionsName, Display display)` | Render using the specified options and the specified display.
    `void` | `reset()` | Reset the state of the API completely.
    `java.lang.String` | `resolveIncludeFilename​(java.lang.String filename)` | Attempts to resolve the specified filename by checking it against the include search path.
    `java.lang.String` | `resolveTextureFilename​(java.lang.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` | `searchpath​(java.lang.String type, java.lang.String path)` | Add the specified path to the list of directories which are searched automatically to resolve scene filenames or textures.
    `void` | `shader​(java.lang.String name, java.lang.String shaderType)` | Defines a shader with a given name.
    `static boolean` | `translate​(java.lang.String filename, java.lang.String outputFilename)` | Translate specfied file into the native sunflow scene file format.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### VERSION

          public static final java.lang.String VERSION

      See Also:
        Constant Field Values

    - #### DEFAULT_OPTIONS

          public static final java.lang.String DEFAULT_OPTIONS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SunflowAPI

          public SunflowAPI()

      Creates an empty scene.

  - ### Method Detail

    - #### runSystemCheck

          public static void runSystemCheck()

      This is a quick system test which verifies that the user has launched Java properly.

    - #### reset

          public final void reset()

      Description copied from interface: `SunflowAPIInterface`
      Reset the state of the API completely. The object table is cleared, and all search paths are set back to their default values.
      Specified by:
        `reset` in interface `SunflowAPIInterface`

    - #### plugin

          public final void plugin​(java.lang.String type,
                                   java.lang.String name,
                                   java.lang.String code)

      Description copied from interface: `SunflowAPIInterface`
      Declare a plugin of the specified type with the given name from a java code string. The code will be compiled with Janino and registered as a new plugin type upon success.
      Specified by:
        `plugin` in interface `SunflowAPIInterface`

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      java.lang.String value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      boolean value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      int value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      float value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      java.lang.String colorspace,
                                      float... data)

      Description copied from interface: `SunflowAPIInterface`
      Declare a color parameter in the given colorspace using the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `colorspace` - color space or `null` to assume internal color space
        `data` - floating point color data

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      Point3 value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      Vector3 value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      Point2 value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      Matrix4 value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      int[] value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      java.lang.String[] value)

      Description copied from interface: `SunflowAPIInterface`
      Declare a parameter with the specified name and value. This parameter will be added to the currently active parameter list.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `value` - parameter value

    - #### parameter

          public final void parameter​(java.lang.String name,
                                      java.lang.String type,
                                      java.lang.String interpolation,
                                      float[] data)

      Description copied from interface: `SunflowAPIInterface`
      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.
      Specified by:
        `parameter` in interface `SunflowAPIInterface`
      Parameters:
        `name` - parameter name
        `type` - parameter data type
        `interpolation` - parameter interpolation mode
        `data` - raw floating point data

    - #### remove

          public void remove​(java.lang.String name)

      Description copied from interface: `SunflowAPIInterface`
      Remove the specified render object. Note that this may cause the removal of other objects which depended on it.
      Specified by:
        `remove` in interface `SunflowAPIInterface`
      Parameters:
        `name` - name of the object to remove

    - #### searchpath

          public final void searchpath​(java.lang.String type,
                                       java.lang.String path)

      Description copied from interface: `SunflowAPIInterface`
      Add the specified path to the list of directories which are searched automatically to resolve scene filenames or textures. Currently the supported searchpath types are: "include" and "texture". All other types will be ignored.
      Specified by:
        `searchpath` in interface `SunflowAPIInterface`

    - #### resolveTextureFilename

          public final java.lang.String resolveTextureFilename​(java.lang.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

    - #### resolveIncludeFilename

          public final java.lang.String resolveIncludeFilename​(java.lang.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

    - #### shader

          public final void shader​(java.lang.String name,
                                   java.lang.String shaderType)

      Description copied from interface: `SunflowAPIInterface`
      Defines a shader with a given name. If the shader type name is left `null`, the shader with the given name will be updated (if it exists).
      Specified by:
        `shader` in interface `SunflowAPIInterface`
      Parameters:
        `name` - a unique name given to the shader
        `shaderType` - a shader plugin type

    - #### modifier

          public final void modifier​(java.lang.String name,
                                     java.lang.String modifierType)

      Description copied from interface: `SunflowAPIInterface`
      Defines a modifier with a given name. If the modifier type name is left `null`, the modifier with the given name will be updated (if it exists).
      Specified by:
        `modifier` in interface `SunflowAPIInterface`
      Parameters:
        `name` - a unique name given to the modifier
        `modifierType` - a modifier plugin type name

    - #### geometry

          public final void geometry​(java.lang.String name,
                                     java.lang.String typeName)

      Description copied from interface: `SunflowAPIInterface`
      Defines a geometry with a given name. The geometry is built from the specified type. Note that geometries may be created from `Tesselatable` objects or `PrimitiveList` objects. This means that two seperate plugin lists will be searched for the geometry type. `Tesselatable` objects are search first. If the type name is left `null`, the geometry with the given name will be updated (if it exists).
      Specified by:
        `geometry` in interface `SunflowAPIInterface`
      Parameters:
        `name` - a unique name given to the geometry
        `typeName` - a tesselatable or primitive plugin type name

    - #### instance

          public final void instance​(java.lang.String name,
                                     java.lang.String geoname)

      Description copied from interface: `SunflowAPIInterface`
      Instance the specified geometry into the scene. If geoname is `null`, the specified instance object will be updated (if it exists). In order to change the instancing relationship of an existing instance, you should use the "geometry" string attribute.
      Specified by:
        `instance` in interface `SunflowAPIInterface`
      Parameters:
        `name` - instance name
        `geoname` - name of the geometry to instance

    - #### light

          public final void light​(java.lang.String name,
                                  java.lang.String lightType)

      Description copied from interface: `SunflowAPIInterface`
      Defines a light source with a given name. If the light type name is left `null`, the light source with the given name will be updated (if it exists).
      Specified by:
        `light` in interface `SunflowAPIInterface`
      Parameters:
        `name` - a unique name given to the light source
        `lightType` - a light source plugin type name

    - #### camera

          public final void camera​(java.lang.String name,
                                   java.lang.String lensType)

      Description copied from interface: `SunflowAPIInterface`
      Defines a camera with a given name. The camera is built from the specified camera lens type plugin. If the lens type name is left `null`, the camera with the given name will be updated (if it exists). It is not currently possible to change the lens of a camera after it has been created.
      Specified by:
        `camera` in interface `SunflowAPIInterface`
      Parameters:
        `name` - camera name
        `lensType` - a camera lens plugin type name

    - #### options

          public final void options​(java.lang.String name)

      Description copied from interface: `SunflowAPIInterface`
      Defines an option object to hold the current parameters. If the object already exists, the values will simply override previous ones.
      Specified by:
        `options` in interface `SunflowAPIInterface`

    - #### lookupGeometry

          public final Geometry lookupGeometry​(java.lang.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

    - #### lookupShader

          public final Shader lookupShader​(java.lang.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

    - #### lookupModifier

          public final Modifier lookupModifier​(java.lang.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

    - #### render

          public final void render​(java.lang.String optionsName,
                                   Display display)

      Description copied from interface: `SunflowAPIInterface`
      Render using the specified options and the specified display. If the specified options do not exist - defaults will be used.
      Specified by:
        `render` in interface `SunflowAPIInterface`
      Parameters:
        `optionsName` - name of the `RenderObject` which contains the options
        `display` - display object

    - #### include

          public final boolean include​(java.lang.String filename)

      Description copied from interface: `SunflowAPIInterface`
      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.
      Specified by:
        `include` in interface `SunflowAPIInterface`
      Parameters:
        `filename` - filename to load
      Returns:
        `true` upon sucess, `false` if an error occured.

    - #### 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.

    - #### build

          public void build()

      This method does nothing, but may be overriden to create scenes procedurally.

    - #### create

          public static SunflowAPI create​(java.lang.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

    - #### translate

          public static boolean translate​(java.lang.String filename,
                                          java.lang.String outputFilename)

      Translate specfied file into the native sunflow scene file format.
      Parameters:
        `filename` - input filename
        `outputFilename` - output filename
      Returns:
        `true` upon success, `false` otherwise

    - #### compile

          public static SunflowAPI compile​(java.lang.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.

    - #### currentFrame

          public int currentFrame()

      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

    - #### currentFrame

          public void currentFrame​(int currentFrame)

      Description copied from interface: `SunflowAPIInterface`
      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.
      Specified by:
        `currentFrame` in interface `SunflowAPIInterface`
      Parameters:
        `currentFrame` - current frame number

    - #### getTextureCache

          public TextureCache getTextureCache()