Events

Events are sent before, during and after the execution of service commands. Some are triggered via processes that occur within neuray Services and others are triggered by commands. You can implement and register event handlers which are called whenever the associated event is sent.

Events

An event is identified by a UUID. neuray Services defines 5 built in events and you are able to define and send your own events. There is no need to register new event types. Simply choose an unused UUID, register handlers to it and then send events. In addition to the UUID, sent events contain additional data providing contextual information about the event.

An event is sent by creating an mi::nservices::IEvent from the factory, populating its data and then sending with mi::nservices::IEvent_context::send_event. A helper class mi::nservices::Event_helper is provided to assist with this.

Event Handlers

Event handlers are implemented by the user and installed by name into neuray services. This is not enough however to have an event handler called. It must be then associated with a particular event using mi::nservices::IEvent_context::register_handler. A handler only remains registered for the lifetime of a service request. Once a set of commands are executed the registration is discarded and the handler must be re-registered for the next request.

An event handler has access to the event itself (and its associated data) as well as the neuray library and both the execution and state transaction. Handlers are able to manipulate the event data, send other events and manipulate neuray. They also return an integer value which can affect ongoing processing.

Pre Execution Event

The pre execution event is sent by neuray services before any service command is executed. It is provided with the following data:

• 0 - mi::nservices::ICommand_request The command request being made.

Pre execution handlers can modify the arguments and attachments of the command request but not the name of the command being executed. The handler can prevent the command from being executed by returning 0. Any other return value indicates that the command should be executed. If command execution is refused then the Post Execution Event is not sent.

Post Execution Event

The post execution event is sent by neuray services after every service command is executed. It is provided with the following data:

• 0 - mi::nservices::ICommand_response The response to the command.

Post execution handlers can modify the response returned by the command.

Change Scope Event

The change scope event is sent by neuray services whenever mi::nservices::ICommand_context::change_scope is called. It is provided with the following data:

• 0 - mi::IString the name of the previous scope.
• 1 - mi::IString the name of the new scope.

This event is useful to keep track of the current scope within the user state.

Pre Render Event

The pre render event is sent by the user just before a render is performed. It is provided with the following data:

• 0 - mi::nservices::IScene the scene to be rendered.
• 1 - mi::IString the content to be rendered into the canvas.
• 2 - mi::IString the pixel type of the canvas.
• 3 - mi::IString the renderer to be used.
• 4 - mi::IUint32 x resolution.
• 5 - mi::IUint32 y resolution.

This event is called by the user just before a render occurs. All data is modifiable in the handler so you should ensure your command honors any changes made.

Note that neuray Services does not call this automatically so if your command implements rendering then you should manually call this. mi::nservices::Event_helper_neuray::send_pre_render_event can be used to assist.

Post Render Event

The post render event is sent twice by the user just after a render is performed. It is provided with the following data:

• 0 - mi::nservices::IScene the scene the canvas was rendered from.
• 1 - mi::IUint32 the post render phase (0 or 1).
• 2 - mi::neuraylib::ICanvas the rendered canvas.
• 3 - mi::IString the name of the renderer used.

This event is called by the user twice after a render occurs. The first time it is called the Phase data (index 1) will be set to 0. This is the 'pre tonemapping' call and the canvas supplied will be direct from the renderer. The second time the Phase data will be set to 1 and the canvas will have been tonemapped (if applicable). This allows the handler to manipulate the canvas either before or after tonemapping.

Note that neuray Services does not call this automatically so if your command implements rendering then you should manually call this. mi::nservices::Event_helper_neuray::send_post_render_event can be used to assist and will send both phases of the event. It is not necessary for the user to do anything to perform tonemapping between these as neuray Service does so automatically.