Helper class for rendering generated OSL code to produce images. More...

#include <OslRenderer.h>

Inheritance diagram for OslRenderer:

Public Member Functions
virtual	~OslRenderer ()
	Destructor.

Setup
void	initialize (RenderContextHandle renderContextHandle=nullptr) override
	Internal initialization required for program validation and rendering. More...

Rendering
void	createProgram (ShaderPtr shader) override
	Create OSL program based on an input shader. More...

void	createProgram (const StageMap &stages) override
	Create OSL program based on shader stage source code. More...

void	validateInputs () override
	Validate inputs for the compiled OSL program. More...

void	setSize (unsigned int width, unsigned int height) override
	Set the size for rendered image. More...

void	render () override
	Render OSL program to disk. More...

Utilities
ImagePtr	captureImage (ImagePtr image=nullptr) override
	Capture the current rendered output as an image. More...

Compilation settings
void	setOslCompilerExecutable (const FilePath &executableFilePath)
	Set the path to the OSL executable. More...

void	setOslIncludePath (const FileSearchPath &dirPath)
	Set the search locations for OSL include files. More...

void	setOslOutputFilePath (const FilePath &dirPath)
	Set the location where compiled OSL files will reside. More...

void	setShaderParameterOverrides (const StringVec &parameterOverrides)
	Set shader parameter strings to be added to the scene XML file. More...

void	setEnvShaderParameterOverrides (const StringVec &parameterOverrides)
	Set shader parameter strings to be added to the scene XML file. More...

void	setOslShaderOutput (const string &outputName, const string &outputType)
	Set the OSL shader output. More...

void	setOslTestShadeExecutable (const FilePath &executableFilePath)
	Set the path to the OSL shading tester. More...

void	setOslTestRenderExecutable (const FilePath &executableFilePath)
	Set the path to the OSL rendering tester. More...

void	setOslTestRenderSceneTemplateFile (const FilePath &templateFilePath)
	Set the XML scene file to use for testrender. More...

void	setOslShaderName (const string &shaderName)
	Set the name of the shader to be used for the input XML scene file. More...

void	setOslUtilityOSOPath (const FilePath &dirPath)
	Set the search path for dependent shaders (.oso files) which are used when rendering with testrender. More...

void	useTestRender (bool useTestRender)
	Used to toggle to either use testrender or testshade during render validation By default testshade is used. More...

void	setRaysPerPixelLit (int rays)
	Set the number of rays per pixel to be used for lit surfaces.

void	setRaysPerPixelUnlit (int rays)
	Set the number of rays per pixel to be used for unlit surfaces.

void	compileOSL (const FilePath &oslFilePath)
	Compile OSL code stored in a file. More...

Public Member Functions inherited from ShaderRenderer
void	setCamera (CameraPtr camera)
	Set the camera.

CameraPtr	getCamera () const
	Return the camera.

void	setImageHandler (ImageHandlerPtr imageHandler)
	Set the image handler used by this renderer for image I/O.

ImageHandlerPtr	getImageHandler () const
	Return the image handler.

void	setLightHandler (LightHandlerPtr lightHandler)
	Set the light handler used by this renderer for light bindings.

LightHandlerPtr	getLightHandler () const
	Return the light handler.

void	setGeometryHandler (GeometryHandlerPtr geometryHandler)
	Set the geometry handler.

GeometryHandlerPtr	getGeometryHandler () const
	Return the geometry handler.

virtual void	updateUniform (const string &name, ConstValuePtr value)
	Update the program with value of the uniform. More...

Static Public Member Functions
static OslRendererPtr	create (unsigned int width=512, unsigned int height=512, Image::BaseType baseType=Image::BaseType::UINT8)
	Create an OSL renderer instance.

Static Public Attributes
static string	OSL_CLOSURE_COLOR_STRING
	Color closure OSL string.

Protected Member Functions
void	shadeOSL (const FilePath &dirPath, const string &shaderName, const string &outputName)
	Shade using OSO input file. More...

void	renderOSL (const FilePath &dirPath, const string &shaderName, const string &outputName)
	Render using OSO input file. More...

	OslRenderer (unsigned int width, unsigned int height, Image::BaseType baseType)
	Constructor.

Protected Member Functions inherited from ShaderRenderer
	ShaderRenderer (unsigned int width, unsigned int height, Image::BaseType baseType, MatrixConvention matrixConvention=MatrixConvention::OpenGL)

Additional Inherited Members
Public Types inherited from ShaderRenderer
enum class	MatrixConvention { OpenGL = 0 , Metal = 1 }
	Viewing API matrix conventions designation (default to OpenGL).

using	StageMap = StringMap
	A map with name and source code for each shader stage.

Protected Attributes inherited from ShaderRenderer
unsigned int	_width

unsigned int	_height

Image::BaseType	_baseType

MatrixConvention	_matrixConvention

CameraPtr	_camera

ImageHandlerPtr	_imageHandler

GeometryHandlerPtr	_geometryHandler

LightHandlerPtr	_lightHandler

Detailed Description

Helper class for rendering generated OSL code to produce images.

The main services provided are:

Source code validation: Use of "oslc" to compile and test output results
Introspection check: None at this time.
Binding: None at this time.
Render validation: Use of "testrender" to output rendered images. Assumes source compliation was success as it depends on the existence of corresponding .oso files.

Member Function Documentation

◆ captureImage()

ImagePtr captureImage ( ImagePtr image = nullptr )

overridevirtual

Capture the current rendered output as an image.

Reimplemented from ShaderRenderer.

◆ compileOSL()

void compileOSL ( const FilePath & oslFilePath )

Compile OSL code stored in a file.

Will throw an exception if an error occurs.

Parameters

oslFilePath OSL file path.

◆ createProgram() [1/2]

void createProgram ( const StageMap & stages )

overridevirtual

Create OSL program based on shader stage source code.

Parameters

stages Map of name and source code for the shader stages.

Reimplemented from ShaderRenderer.

◆ createProgram() [2/2]

void createProgram ( ShaderPtr shader )

overridevirtual

Create OSL program based on an input shader.

A valid executable and include path must be specified before calling this method. setOslCompilerExecutable(), and setOslIncludePath().

Additionally setOslOutputFilePath() should be set to allow for output of .osl and .oso files to the appropriate path location to be used as input for render validation.

If render validation is not required, then the same temporary name will be used for all shaders validated using this method.

Parameters

shader Input shader

Reimplemented from ShaderRenderer.

◆ initialize()

void initialize ( RenderContextHandle renderContextHandle = nullptr )

overridevirtual

Internal initialization required for program validation and rendering.

An exception is thrown on failure. The exception will contain a list of initialization errors.

Reimplemented from ShaderRenderer.

◆ render()

void render ( )

overridevirtual

Render OSL program to disk.

This is done by using either "testshade" or "testrender". Currently only "testshade" is supported.

Usage of both executables requires compiled source (.oso) files as input. A shader output must be set before running this test via the setOslOutputName() method to ensure that the appropriate .oso files can be located.

Reimplemented from ShaderRenderer.

◆ renderOSL()

void renderOSL	(	const FilePath &	dirPath,
		const string &	shaderName,
		const string &	outputName
	)

protected

Render using OSO input file.

Will throw an exception if an error occurs.

Parameters

dirPath	Path to location containing input .oso file.
shaderName	Name of OSL shader. A corresponding .oso file is assumed to exist in the output path folder.
outputName	Name of OSL shader output to use.

◆ setEnvShaderParameterOverrides()

void setEnvShaderParameterOverrides ( const StringVec & parameterOverrides )

inline

Set shader parameter strings to be added to the scene XML file.

These strings will set parameter overrides for the shader.

◆ setOslCompilerExecutable()

void setOslCompilerExecutable ( const FilePath & executableFilePath )

inline

Set the path to the OSL executable.

Note that it is assumed that this references the location of the oslc executable.

Parameters

executableFilePath Path to OSL compiler executable

◆ setOslIncludePath()

void setOslIncludePath ( const FileSearchPath & dirPath )

inline

Set the search locations for OSL include files.

Parameters

dirPath Include path(s) for the OSL compiler. This should include the path to stdosl.h.

◆ setOslOutputFilePath()

void setOslOutputFilePath ( const FilePath & dirPath )

inline

Set the location where compiled OSL files will reside.

Parameters

dirPath Path to output location

◆ setOslShaderName()

void setOslShaderName ( const string & shaderName )

inline

Set the name of the shader to be used for the input XML scene file.

The value is used to replace the shader% token in the file.

Parameters

shaderName Name of shader

◆ setOslShaderOutput()

void setOslShaderOutput	(	const string &	outputName,
		const string &	outputType
	)

inline

Set the OSL shader output.

This is used during render validation if "testshade" or "testrender" is executed. For testrender this value is used to replace the shader_output% token in the input scene file.

Parameters

outputName	Name of shader output
outputType	The MaterialX type of the output

◆ setOslTestRenderExecutable()

void setOslTestRenderExecutable ( const FilePath & executableFilePath )

inline

Set the path to the OSL rendering tester.

Note that it is assumed that this references the location of the "testrender" executable.

Parameters

executableFilePath Path to OSL "testrender" executable

◆ setOslTestRenderSceneTemplateFile()

void setOslTestRenderSceneTemplateFile ( const FilePath & templateFilePath )

inline

Set the XML scene file to use for testrender.

This is a template file with the following tokens for replacement:

shader% : which will be replaced with the name of the shader to use
shader_output% : which will be replace with the name of the shader output to use
Parameters

templateFilePath Scene file name

◆ setOslTestShadeExecutable()

void setOslTestShadeExecutable ( const FilePath & executableFilePath )

inline

Set the path to the OSL shading tester.

Note that it is assumed that this references the location of the "testshade" executable.

Parameters

executableFilePath Path to OSL "testshade" executable

◆ setOslUtilityOSOPath()

void setOslUtilityOSOPath ( const FilePath & dirPath )

inline

Set the search path for dependent shaders (.oso files) which are used when rendering with testrender.

Parameters

dirPath Path to location containing .oso files.

◆ setShaderParameterOverrides()

void setShaderParameterOverrides ( const StringVec & parameterOverrides )

inline

Set shader parameter strings to be added to the scene XML file.

These strings will set parameter overrides for the shader.

◆ setSize()

void setSize	(	unsigned int	width,
		unsigned int	height
	)

overridevirtual

Set the size for rendered image.

Reimplemented from ShaderRenderer.

◆ shadeOSL()

void shadeOSL	(	const FilePath &	dirPath,
		const string &	shaderName,
		const string &	outputName
	)

protected

Shade using OSO input file.

Will throw an exception if an error occurs.

Parameters

dirPath	Path to location containing input .oso file.
shaderName	Name of OSL shader. A corresponding .oso file is assumed to exist in the output path folder.
outputName	Name of OSL shader output to use.

◆ useTestRender()

void useTestRender ( bool useTestRender )

inline

Used to toggle to either use testrender or testshade during render validation By default testshade is used.

Parameters

useTestRender Indicate whether to use testrender.

◆ validateInputs()

void validateInputs ( )

overridevirtual

Validate inputs for the compiled OSL program.

Note: Currently no validation has been implemented.

Reimplemented from ShaderRenderer.

The documentation for this class was generated from the following files:

source/MaterialXRenderOsl/OslRenderer.h
source/MaterialXRenderOsl/OslRenderer.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ captureImage()

◆ compileOSL()

◆ createProgram() [1/2]

◆ createProgram() [2/2]

◆ initialize()

◆ render()

◆ renderOSL()

◆ setEnvShaderParameterOverrides()

◆ setOslCompilerExecutable()

◆ setOslIncludePath()

◆ setOslOutputFilePath()

◆ setOslShaderName()

◆ setOslShaderOutput()

◆ setOslTestRenderExecutable()

◆ setOslTestRenderSceneTemplateFile()

◆ setOslTestShadeExecutable()

◆ setOslUtilityOSOPath()

◆ setShaderParameterOverrides()

◆ setSize()

◆ shadeOSL()

◆ useTestRender()

◆ validateInputs()