Detailed Description

PreviewImageProvider interface implements the provision of an preview image stream of a node in a particular state. This interface is closely coupled to the NodeSpaceInterface which defines the type of PreviewImageProvider that is instantiated when a preview on a node is requested. The request may have different intends including but not limited to:

the thumbnail in the material manager,
the thumbnails in the attribute manager and node editor,
the gradient bar in the gradient node,
textures for the viewport, as well as
(future) bake requests for caching an material export.

Generally it can be expected that PreviewImageProvider instances are created by a dedicated JobQueue that manages and prioritizes the preview computations in a round-robin manner where multiple previews are active in parallel. The amount of active instances is limited to ensure fluid user interaction. Hence, it is not recommended to model dependencies such as wait conditions between PreviewImageProvider instances.

Due to the asynchronous nature of the scheduling mechanism it is not safe to access the active BaseDocument from a PreviewImageProvider.

User interactions such as dragging a slider will lead to a continuous instantiation and cancellation of PreviewImageProviders. Note that cancellation of an outdated state is not blocking the instantiation of the more recent state. Consequently, it is recommended to regularly react to cancellation within the ComputeIteration function to avoid overflowing of already cancelled instances.

Public Member Functions
MAXON_METHOD Result< void >	Initialize (const DataDictionaryObjectRef &request, Int numThreads)

MAXON_METHOD Result< void >	ComputeIteration (const JobRef &parentThread)

MAXON_METHOD Result< PreviewImageProviderOutput >	TakeOutput ()

Private Member Functions
	MAXON_INTERFACE (PreviewImageProviderInterface, MAXON_REFERENCE_NORMAL, "net.maxon.nodes.interface.previewimageprovider")

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE	(	PreviewImageProviderInterface	,
		MAXON_REFERENCE_NORMAL	,
		"net.maxon.nodes.interface.previewimageprovider"
	)

private

◆ Initialize()

MAXON_METHOD Result<void> Initialize	(	const DataDictionaryObjectRef &	request,
		Int	numThreads
	)

Called to initialize the provider by safely extracting all data from the request. Please see the attributes in maxon::nodes::PREVIEWIMAGEREQUEST for data extraction. Safety is achieved by making this call blocking with respect to changes in the node graph and the parallel round-robin based scheduling manager. It is therefore recommended to keep this method light-weight and perform heavier computations during the first call to @ComputeIteration.

Parameters

[in]	request	The request containing information about how to bake or render which node.
[in]	numThreads	The recommended maximum number of threads to use during @ComputeIteration.

Returns: OK on success.

◆ ComputeIteration()

MAXON_METHOD Result<void> ComputeIteration ( const JobRef & parentThread )

Called asynchronously to indicate the desire to proceed with node preview computation. The execution of this function blocks one spot in the parallel round-robin based scheduling manager. The asynchronous nature of this call makes this unsafe to access the original node graph. Instead, a copy should be made during @Initialize.

It is guaranteed the the time windows of calls to @Initialize, @ComputeIteration, @GetOutput never overlap. Iterations are called one after another, with possible breaks in between to switch computation efforts to other previews.

Note that ComputeIteration may be again after being cancelled in a prior call, fulfilling the use case of pause and resume.

Parameters

[in] parentThread Query the caller for cancellation state.

Returns: OK on success.

◆ TakeOutput()

MAXON_METHOD Result<PreviewImageProviderOutput> TakeOutput ( )

Called when performing a successful iteration. The caller assumes shared ownership of immutable data. It is therefore prohibited to change the contents of the attaches SamplesFloat32Linear buffers after return. In case progressively refined results are provided, we recommend to copy over data from previous iterations that have been returned earlier.

Returns: The preview image result that is dispatched to listeners.