|
Render Toolbox 3
v2.1
|
Plugins to work with various renderers. More...
Functions | |
| rendererFunction functionPath | GetRendererAPIFunction (functionName, hints) |
| Find the function_handle of a RenderToolbox3 renderer API function. | |
| ApplyPBRTObjects (idMap, objects) | |
| Apply PBRT mappings objects to the adjustments DOM. | |
| adjustments | RTB_ApplyMappings_SampleRenderer (objects, adjustments) |
| Convert mappings objects to native adjustments for the SampleRenderer. | |
| radianceImage scaleFactor | RTB_DataToRadiance_SampleRenderer (multispectralImage, scene, hints) |
| Convert Sample Renderer data to units of radiance. | |
| scene | RTB_ImportCollada_SampleRenderer (colladaFile, adjustments, imageName, hints) |
| Convert a Collada parent scene file the Sample Renderer native format. | |
| status result multispectralImage S | RTB_Render_SampleRenderer (scene, hints) |
| Invoke the Sample Renderer. | |
| versionInfo | RTB_VersionInfo_SampleRenderer () |
| Get version information about the Sample Renderer. | |
Plugins to work with various renderers.
These functions provide templates for Renderer Plugin API functions. RenderToolbox3 can invoke a named renderer plugin during scene file generation and rendering. Thus, and renderer that defines a set of Renderer Plugin API functions can be used with RenderToolbox3.
| rendererFunction functionPath GetRendererAPIFunction | ( | functionName | , |
| hints | |||
| ) |
Find the function_handle of a RenderToolbox3 renderer API function.
| functionName | the name of a renderer API function |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Attempts to locate the named API function for the given hints.renderer. Renderer API functions must on the Matlab path or within hints.workingFolder. They must have names that folow the pattern RTB_functionName_renderer, for example RTB_ApplyMappings_SampleRenderer.
hints.renderer may be the name of any supported renderer, for example, "SampleRenderer", "PBRT", or "Mitsuba".
functionName must be the name of a RenderToolbox3 Renderer API function:
Returns the function_handle of the RenderToolbox3 Renderer API function, for the given hints.renderer and functionName. If no such function is found, retuns an empty []. Also returns the full path to the named function, if found. Usage: [rendererFunction, functionPath] = GetRendererAPIFunction(functionName, hints)
| ApplyPBRTObjects | ( | idMap | , |
| objects | |||
| ) |
Apply PBRT mappings objects to the adjustments DOM.
| idMap | |
| objects |
Modify the document represented by the given idMap, with the given mappings objects. objects must be a struct array of mappings objects as returned from MappingsToObjects() or GenericObjectsToPBRT().
Used internally by RTB_ApplyMappings_PBRT().
| adjustments RTB_ApplyMappings_SampleRenderer | ( | objects | , |
| adjustments | |||
| ) |
Convert mappings objects to native adjustments for the SampleRenderer.
| objects | mappings objects as returned from MappingsToObjects() |
| adjustments | native adjustments to be updated, if any |
This function is a template for a RenderToolbox3 "ApplyMappings" function.
The name of an ApplyMappings function must match a specific pattern: it must begin with "RTB_ApplyMappings_", and it must end with the name of the renderer, for example, "SampleRenderer". This pattern allows RenderToolbox3 to automatically locate the ApplyMappings function for each renderer. ApplyMappings functions should be included in the Matlab path.
An ApplyMappings function must read mappings values from the given mappings objects and create or update adjustments in a renderer's native format. objects may be empty but will usually contain data parsed from a scene mappings file. adjustments will be used by the renderer's ImportCollada function to modify the scene following initial Collada conversion.
adjustments may have any renderer-specific format. Some renderers may treat adjustments as a file name, and read and write adjustments to and from that file. Other renderers may use adjustments as a normal Matlab variable to store scene adjustments directly.
If the adjustments parameter is empty, an ApplyMappings function must create new renderer-native adjustments from scratch and populate it with data from the given objects. Otherwise, an ApplyMappings function must update the given adjustments based on the the given objects.
An ApplyMappings function must return new or updated renderer-native adjustments, which incorporates data from the given objects.
Usage: adjustments = RTB_ApplyMappings_SampleRenderer(objects, adjustments)
| radianceImage scaleFactor RTB_DataToRadiance_SampleRenderer | ( | multispectralImage | , |
| scene | , | ||
| hints | |||
| ) |
Convert Sample Renderer data to units of radiance.
| multispectralImage | numeric rendering data from a Render function |
| scene | description of the scene from an ImportCollada function |
| hints | struct of RenderToolbox3 options |
This function is a template for a RenderToolbox3 "DataToRadiance" function.
The name of a DataToRadiance function must match a specific pattern: it must begin with "RTB_DataToRadiance_", and it must end with the name of the renderer, for example, "SampleRenderer". This pattern allows RenderToolbox3 to automatically locate the DataToRadiance function for each renderer. DataToRadiance functions should be included in the Matlab path.
A DataToRadiance function must convert the multispectralImage data that was returned from a RenderToolbox3 Render function into inits of physical radiance. It must also accept a scne parameter, as returned from a RenderToolbox3 ImportCollada function, which describes the rendered scene and may provide scene-specific and renderer-specific data to informs the conversion to radiance units. It must also accept a hints parameter of RenderTooblox3 options, which also may inform the conversion.
Converting a multispectralImage to units of physical radiance units is a highly-renderer specific proicess. Some renderers may be able to return images in radiance units natively, in which case the DataToRadiance function simply return the multispectralImage. Other renderers might return data that is a scaled version of radiance, in which case the DataToRadiance should apply the proper scale factor to the multispectralImage. Determining the proper scale factor probably requires prior investigation.
For some renderers, the proper scale factor may depend on partcular scene parameters, like the nubmer of ray samples used or the type of sample integrator. In this case, scene and hints should be used to choose or calculate a proper scale factor. Getting this right may require a lot of prior investigation, which may not be feasible in all cases. A DataToRadiance should make a best effort to return accurate radiance units, and raise a warning when it is unable to do so.
A DataToRadiance function must return the given multispectralImage, scaled into units of physical radiance. It must also return the scale factor that was applied to the original multispectralImage.
Usage: [radianceImage, scaleFactor] = RTB_DataToRadiance_SampleRenderer(multispectralImage, scene, hints)
| scene RTB_ImportCollada_SampleRenderer | ( | colladaFile | , |
| adjustments | , | ||
| imageName | , | ||
| hints | |||
| ) |
Convert a Collada parent scene file the Sample Renderer native format.
| colladaFile | input Collada parent scene file name or path |
| adjustments | native adjustments data, or file name or path |
| imageName | the name to use for this scene and new files |
| hints | struct of RenderToolbox3 options |
This function is a template for a RenderToolbox3 "ImportCollada" function.
The name of an ImportCollada function must match a specific pattern: it must begin with "RTB_ImportCollada_", and it must end with the name of the renderer, for example, "SampleRenderer". This pattern allows RenderToolbox3 to automatically locate the ImportCollada function for each renderer. ImportCollada functions should be included in the Matlab path.
An ImportCollada function must convert the given colladaFile ('.dae' or '.xml') to a native format that the renderer can use for rendering. It must also create a Matlab struct that contains a description of the scene, which will be passed to the renderer's Render function.
An ImportCollada function may use the given adjustments to modify the native scene, following an initial conversion from Collada. adjustments may contain scene data or the name of a partial scene file to be merged with the scene in a renderer-specific way. adjustments will be returned from a RenderToolbox3 ApplyMappings function.
hints will be a struct with RenderToolbox3 options, as returned from GetDefaultHints(), which may inform the conversion process.
An ImportCollada function must return a struct that describes the renderer-native scene. This struct must contain all of the information needed to render the scene, including the names of any new files created.
An ImportCollada function may write new renderer-native scene files and other auxiliary files. It should put any new files in the current working "scenes" folder, obtained as follows:
The names of all new files should appear in the returned scene description struct, or appear within other files whose names appear in turn in the scene description struct. These file names must be converted to relative paths using GetWorkingRelativePath(), in order to make scenes portable across machines and users.
The specific format of the returned struct does not matter, it just has to be a struct. RenderToolbox3 may add or update some struct fields automatically, including the authorInfo and imageName fields.
Usage: scene = RTB_ImportCollada_SampleRenderer(colladaFile, adjustments, imageName, hints)
| status result multispectralImage S RTB_Render_SampleRenderer | ( | scene | , |
| hints | |||
| ) |
Invoke the Sample Renderer.
| scene | struct description of the scene to be rendererd |
| hints | struct of RenderToolbox3 options |
This function is a template for a RenderToolbox3 "Render" function.
The name of a Render function must match a specific pattern: it must begin with "RTB_Render_", and it must end with the name of the renderer, for example, "SampleRenderer". This pattern allows RenderToolbox3 to automatically locate the Render function for each renderer. Render functions should be included in the Matlab path.
A Render function must invoke a renderer using the given scene. scene will be a struct scene description returned from the ImportCollada function for the same renderer.
RenderToolbox3 does not care how the renderer is invoked. Some possibilities are:
call another m-function
A Render function must return three outputs:
This template function returns sample values but does not render anyting. Usage: [status, result, multispectralImage, S] = RTB_Render_SampleRenderer(scene, hints)
| versionInfo RTB_VersionInfo_SampleRenderer | ( | ) |
Get version information about the Sample Renderer.
This function is a template for a RenderToolbox3 "VersionInfo" function.
The name of a VersionInfo function must match a specific pattern: it must begin with "RTB_VersionInfo_", and it must end with the name of the renderer, for example, "SampleRenderer". This pattern allows RenderToolbox3 to automatically locate the VersionInfo function for each renderer. VersionInfo functions should be included in the Matlab path.
A VersionInfo function must return information about a renderer's version. This may have any form, including string or struct. The may have any content, including a software revision or version name or number, a renderer executable file creation date, etc. RenderToolbox3 uses VersionInfo functions to save renderer version information along with rendering data. Usage: versionInfo = RTB_VersionInfo_SampleRenderer()
1.8.2
