neuray Services API Programmer's Manual

Overview of the neuray Services API

neuray Services provides no actual Neuray Library functionality in itself. On its own it cannot manipulate the database or render images. Access to the Neuray Library is provided to user implemented commands via the neuray Services C++ API. In the process of executing commands events may be triggered when certain processes occur. The user can implement and install custom event handlers to process these events.

Implementation

The neuray Services API provides three interfaces to allow for the implementation of user code: Implementation of each of these follows a common pattern. Each provides a get_name() method whose result is used to identify the implementation in the system. There may also be various methods to provide documentation or information to the system on how to execute the implementation. Finally there are one or more handlers which are called to execute the desired functionality. These can be identified as the methods taking a 'context' argument.

Contexts

All access to the neuray Services and the Neuray Library itself is provided through a context passed into the handler. Each of the three types of implementation takes a different type of context which provides access to the appropriate functionality. All contexts provide access to:
  • The Neuray Library.
  • A transaction into the execution scope.
  • A transaction into the user state (if one is setup).
Contexts may additionally provide access to the arguments or parameters related to the handler call, a factory to allow the creation of data, a converter to facilitate conversion between different data types, the event system and attachments.

Factory

neuray Services provides a wrapped implementation of the Neuray Library factory. This factory can be used to create any type supported by the Neuray Library in addition to the extended neuray Services types.

Commands

Commands are the core of neuray Services. All code execution is triggered as the result of a command being called. A command implementation has complete access to the Neuray Library and can also call any other registered command. This allows for various low level commands to be combined to provide more complex functionality.

neuray Services provides an execution environment for commands to work in. The main component of this environment is the execution transaction. Commands are always called within a particular scope and neuray Services maintains a transaction into this scope. This frees the implementor from having to discover which scope they should be using on a per command basis and obtaining a transaction into it. Commands are able to change the scope that is being used or create their own transactions if necessary.

The other main component of the execution environment is the arguments of the command. All commands are provided with named arguments as specified by the caller. Using named arguments as opposed to positional ones allows for great flexibility in adding or removing arguments and with supporting optional arguments. Commands are able to provide descriptions for each argument which in addition to supplying automated documentation provide typing and default values. If type information is supplied the neuray Services core will automatically convert incoming arguments to the correct type before command execution.

Event Handlers

neuray Services provides a simple event system. Users can implement event handlers which are executed when particular events occur. neuray Services defines a number of system events and the user is able to define their own. When an event handler is called it is provided with the event that was triggered, any additional information associated with the event and the current execution environment. The functionality expected of an event handler is dependent on the particular event being handled and may include simply storing information for later use, manipulating the execution environment or even the results of commands.

Event handlers are typically installed outside of command execution.

Tonemapping

Tonemapping of rendered images is an integral part of neuray Services. API for implementing custom tonemappers is provided as well as built in support for various industry standard tonemappers. As use of the tonemapping system is not always desirable it is not completely automated. To trigger tonemapping of a canvas you must send a post-render event and provide the canvas to the event. Helper methods for triggering these events are provided.

Render Loops

Render loops provide a highly efficient way of performing progressive rendering which will make full use of available resources. neuray Services provides a mechanism for starting, stopping and managing render loops as well as implementing custom handlers to perform the actual rendering.