The Rendering API's interface for managing the render process. More...

#include <IRenderingProcess.h>

Classes
class	IMainThreadJob
	Interface to a job which gets executed from the main thread. More...

class	NamedTimerGuard
	Guard class for starting and stopping a timer automatically. More...

Public Types
enum class	ProgressType { Translation , Rendering }

Public Member Functions
Progress Reporting
virtual void	SetRenderingProgressTitle (const MCHAR *title)=0
	Sets the progress title, displayed in the render progress dialog. More...

virtual void	SetRenderingProgress (const size_t done, const size_t total, const ProgressType progressType)=0
	Sets the numerical progress to be displayed in the progress dialog. More...

virtual void	SetInfiniteProgress (const size_t done, const ProgressType progressType)=0
	Reports progress for an infinite render. More...

Scene Reporting & Statistics
virtual void	SetSceneStats (int nlights, int nrayTraced, int nshadowed, int nobj, int nfaces)=0
	Sets the scene statistics which get displayed in the render progress dialog. More...

virtual void	ReportMissingUVWChannel (INode &node, const unsigned int channel_id)=0
	Reports a UVW channel is required but missing on the given geometric object. More...

Abort Management
virtual bool	HasAbortBeenRequested ()=0
	Returns whether the user has requested that the renderer abort. More...

Event Logging
These methods implement events which are used by the system for logging and reporting timing statistics.
virtual void	TranslationStarted ()=0
	To be called when the render session starts translating the scene. More...

virtual void	TranslationFinished ()=0
	To be called when the render session finishes translating the scene. More...

virtual void	RenderingStarted ()=0
	To be called when the render session starts rendering the scene. More...

virtual void	RenderingPaused ()=0
	To be called by the render session when it effectively pauses the renderer. More...

virtual void	RenderingResumed ()=0
	To be called by the render session when it effectively resumes the renderer, following a pause. More...

virtual void	RenderingFinished ()=0
	To be called when the render session finishes, aborts, or stops rendering the scene. More...

virtual float	GetTranslationTimeInSeconds () const =0
	Returns the elapsed translation time, as delimited by calls to TranslationStarted() and TranslationFinished(). More...

virtual float	GetRenderingTimeInSeconds () const =0
	Returns the elapsed rendering time, as delimited by calls to RenderingStarted() and RenderingFinished(). More...

Timing Statistics
These method are used to register timing statistics, associating them with a name that may be reported to the user at the end of the rendering operation. Starts the timer with the given name.
virtual void	StartTimer (const MSTR &timer_name)=0
	Creates a new timer with the given name, and starts that timer. More...

virtual void	StopTimer (const MSTR &timer_name)=0
	Stops the timer with the given name. More...

virtual float	GetTimerElapsedSeconds (const MCHAR *timer_name) const =0
	Returns the total time accumulated for the timer with the given name. More...

Running Jobs from the Main Thread
virtual void	CancelMainThreadJobs ()=0
	Cancels all pending main thread jobs, preventing further jobs from running. More...

virtual bool	RunJobFromMainThread (IMainThreadJob &job)=0
	Runs a job from the main thread. More...

Protected Member Functions
virtual	~IRenderingProcess ()
	Protected destructor prevents deletion through this interface. More...

Detailed Description

The Rendering API's interface for managing the render process.

This interface abstracts various tasks related to the rendering process:

Progress reporting
Event reporting and logging
Abort management
Running jobs from the main thread
Reporting scene statistics

The interface's implementation of these tasks is specialized for the rendering API, and should be used rather than existing (more general) 3ds Max SDK equivalents (such as RendProgressCallback).

Member Enumeration Documentation

◆ ProgressType

enum ProgressType

strong

Enumerator
Translation
Rendering

     {
         Translation,
         Rendering
     };

Constructor & Destructor Documentation

◆ ~IRenderingProcess()

virtual ~IRenderingProcess ( )

inlineprotectedvirtual

Protected destructor prevents deletion through this interface.

192 {}

Member Function Documentation

◆ SetRenderingProgressTitle()

virtual void SetRenderingProgressTitle ( const MCHAR * title )

pure virtual

Sets the progress title, displayed in the render progress dialog.

Remarks: It's a good idea to reset the progress title (to an empty string) once a task is done - to avoid lingering, invalid titles.; The title string is also passed to the message logging system.; This method may safe be called from any thread, but not concurrently as it contains no locking.; This method must not be used for reporting while scene translation is in progress. Instead, use class ITranslationManager.

Parameters

title The string to display as the progress title.

◆ SetRenderingProgress()

virtual void SetRenderingProgress	(	const size_t	done,
		const size_t	total,
		const ProgressType	progressType
	)

pure virtual

Sets the numerical progress to be displayed in the progress dialog.

Remarks: The progress is not reported to the logging system, so it is a good idea for the render session to also report progress messages.; This method may safe be called from any thread, but not concurrently as it contains no locking.

Parameters

done	The number of units of work which are done. Current progress is expressed as: done / total.
total	The number of units of work in total. Current progress is expressed as: done / total.
progressType	The type of progress being reported. The system may report both types of progress differently.

Remarks: This method must not be used for reporting while scene translation is in progress. Instead, use class ITranslationManager.

◆ SetInfiniteProgress()

virtual void SetInfiniteProgress	(	const size_t	done,
		const ProgressType	progressType
	)

pure virtual

Reports progress for an infinite render.

This method is used to report the number of work units performed, when there is no set limit - i.e. the renderer will progress indefinitely, until explicitly stopped by the user. The progress dialog will set itself up with an infinite/ongoing progress bar.

Parameters

done	The number of units of work which are done.
progressType	The type of progress being reported. The system may report both types of progress differently.

Remarks: This method must not be used for reporting while scene translation is in progress. Instead, use class ITranslationManager.

◆ SetSceneStats()

virtual void SetSceneStats	(	int	nlights,
		int	nrayTraced,
		int	nshadowed,
		int	nobj,
		int	nfaces
	)

pure virtual

Sets the scene statistics which get displayed in the render progress dialog.

See RendProgressCallback::SetSceneStats().

◆ ReportMissingUVWChannel()

virtual void ReportMissingUVWChannel	(	INode &	node,
		const unsigned int	channel_id
	)

pure virtual

Reports a UVW channel is required but missing on the given geometric object.

A translator may determine that it requires a certain UVW channel to be present (because a texture may be dependent on it). If the channel is not present on the mesh, then it should report it using this method. The system will automatically report the error using the standard mechanisms - though only for offline rendering (MEdit and ActiveShade do not report an error).

Parameters

node	The node which references the mesh for which a UVW channel is missing.
channel_id	The ID for the UVW channel which is missing.

◆ HasAbortBeenRequested()

virtual bool HasAbortBeenRequested ( )

pure virtual

Returns whether the user has requested that the renderer abort.

This method is to be polled at regular intervals by the renderer to determine whether the user has requested that the renderer abort. If it returns true, then the renderer should terminate as soon as possible, regardless of how far the rendering process has progressed. It is perfectly fine to have a partial or otherwise invalid frame buffer when aborting.

Remarks: Once a render session has been aborted, that session will no longer be used for rendering: it is destroyed. It is therefore OK for the render session to assume it will no longer be used.; If the renderer has been paused, then this method may block until the renderer is resumed. This is the legacy, passive method for pausing a renderer.

Returns: True if the an abort has been requested. False otherwise.

◆ TranslationStarted()

virtual void TranslationStarted ( )

pure virtual

To be called when the render session starts translating the scene.

This method reports a progress message and starts a timer.

◆ TranslationFinished()

virtual void TranslationFinished ( )

pure virtual

To be called when the render session finishes translating the scene.

This method reports a progress message and the total time used for translating the scene.

◆ RenderingStarted()

virtual void RenderingStarted ( )

pure virtual

To be called when the render session starts rendering the scene.

This method reports a progress message and starts a timer.

Remarks: This method should also be called if the renderer is restarted, such as following a scene update.

◆ RenderingPaused()

virtual void RenderingPaused ( )

pure virtual

To be called by the render session when it effectively pauses the renderer.

This method reports a progress message and pauses the rendering timer.

Remarks: This method does nothing if the renderer is already paused.

◆ RenderingResumed()

virtual void RenderingResumed ( )

pure virtual

To be called by the render session when it effectively resumes the renderer, following a pause.

This method reports a progress message and resumes the rendering timer.

Remarks: This method does nothing if the renderer is not already paused.

◆ RenderingFinished()

virtual void RenderingFinished ( )

pure virtual

To be called when the render session finishes, aborts, or stops rendering the scene.

This method reports a progress message and the total time used for rendering.

Remarks: This method does nothing if the render was not currently running (paused is considered running).

◆ GetTranslationTimeInSeconds()

virtual float GetTranslationTimeInSeconds ( ) const

pure virtual

Returns the elapsed translation time, as delimited by calls to TranslationStarted() and TranslationFinished().

Remarks: May be called while tranlsation is active (i.e. before TranslationFinished() has been called).

Returns: The elapsed translation time, in seconds.

◆ GetRenderingTimeInSeconds()

virtual float GetRenderingTimeInSeconds ( ) const

pure virtual

Returns the elapsed rendering time, as delimited by calls to RenderingStarted() and RenderingFinished().

Remarks: May be called while rendering is active (i.e. before RenderingFinished() has been called).

Returns: The elapsed rendering time, in seconds.

◆ StartTimer()

virtual void StartTimer ( const MSTR & timer_name )

pure virtual

Creates a new timer with the given name, and starts that timer.

If a timer with that name already exists, then it is resumed (un-paused).

Parameters

timer_name The name of the timer, which will be reported to the user (through the log system) at the end of the rendering operation. An empty name causes the call to no-op.

Remarks: The timer may be sopped/paused by calling StopTimer() with the same timer name.; Consider using class NamedTimerGuard to more easily start and stop timers.

◆ StopTimer()

virtual void StopTimer ( const MSTR & timer_name )

pure virtual

Stops the timer with the given name.

Stops the existing timer with the given name.

Parameters

timer_name The name of the timer, which will be reported to the user (through the log system) at the end of the rendering operation. An empty name causes the call to no-op.

Remarks: The time is actually paused, and may be re-started by calling StartTimer() again with the same timer name.

◆ GetTimerElapsedSeconds()

virtual float GetTimerElapsedSeconds ( const MCHAR * timer_name ) const

pure virtual

Returns the total time accumulated for the timer with the given name.

Parameters

timer_name The name of the timer for which to retrieve the running timer.

Remarks: Calling this method on a timer which is currently running is perfectly valid; the current running time will be correctly queried.

◆ CancelMainThreadJobs()

virtual void CancelMainThreadJobs ( )

pure virtual

Cancels all pending main thread jobs, preventing further jobs from running.

This must be called by an offline renderer when it cancels its render in order to avoid deadlocks. When a render is aborted, some render threads may be waiting on a main thread job to finish executing - for example through logging, progress reporting call, or bitmap update. To avoid a deadlock, where the main thread would be waiting for the renderer to abort which would in turn be waiting for main thread jobs to finish, it's crucial that the offline render session call this method before it starts waiting for the renderer to finish. Calling this method causes all calls to RunJobFromMainThread() to return false.

Remarks: This method is only to be called from the main thread.

◆ RunJobFromMainThread()

virtual bool RunJobFromMainThread ( IMainThreadJob & job )

pure virtual

Runs a job from the main thread.

The 3ds Max SDK is generally not thread safe. Most SDK operations, such as scene translation/update, must therefore be done from the main thread. Because the render session will not necessarily operate from the main thread (e.g. IInteractiveRenderSession::UpdateInteractiveSession()), this method provides a simple mechanism for execute an arbitrary job from the main thread.

Remarks: This call is synchronous: it returns once the job has completed or has been aborted.; If the render session is aborted, then pending jobs are cancelled and this method returns false.; If this method is called from the main thread, then the job is immediately executed with no synchronization overhead.; Consider calling CancelMainThreadJobs(), when aborting an offline render, to avoid deadlocks.

Returns: True if the job executed successfully, false if the job didn't execute because the render session was aborted.

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ ProgressType

Constructor & Destructor Documentation

◆ ~IRenderingProcess()

Member Function Documentation

◆ SetRenderingProgressTitle()

◆ SetRenderingProgress()

◆ SetInfiniteProgress()

◆ SetSceneStats()

◆ ReportMissingUVWChannel()

◆ HasAbortBeenRequested()

◆ TranslationStarted()

◆ TranslationFinished()

◆ RenderingStarted()

◆ RenderingPaused()

◆ RenderingResumed()

◆ RenderingFinished()

◆ GetTranslationTimeInSeconds()

◆ GetRenderingTimeInSeconds()

◆ StartTimer()

◆ StopTimer()

◆ GetTimerElapsedSeconds()

◆ CancelMainThreadJobs()

◆ RunJobFromMainThread()