3ds Max C++ API Reference
Translator Class Referenceabstract

Base class for a translator. More...

#include <Translator.h>

+ Inheritance diagram for Translator:

Public Types

typedef std::set< TimeValueKeyframeList
 

Public Member Functions

 Translator (TranslatorGraphNode &graphNode)
 The constructor expects a reference to a TranslatorGraphNode. More...
 
virtual ~Translator ()
 
virtual TranslationResult Translate (const TimeValue translationTime, Interval &newValidity, ITranslationProgress &translationProgress, KeyframeList &keyframesNeeded)=0
 Performs the translation for which this class is responsible. More...
 
virtual TranslationResult TranslateKeyframe (const TimeValue frame_time, const TimeValue keyframe_time, ITranslationProgress &translationProgress)=0
 Performs translation for a single keyframe. More...
 
virtual void PreTranslate (const TimeValue translationTime, Interval &validity)=0
 Called just before Translate() to enable pre-processing of any kind. More...
 
virtual void PostTranslate (const TimeValue translationTime, Interval &validity)=0
 Called just after Translate() to enable post-processing of any kind. More...
 
virtual void AccumulateStatistics (TranslatorStatistics &stats) const =0
 Called by the system to accumulate statistics on the translated scene. More...
 
void AccumulateGraphStatistics (TranslatorStatistics &statistics) const
 Accumulates statistics on the whole translate graph, starting at this translation node. More...
 
virtual Interval CheckValidity (const TimeValue t, const Interval &previous_validity) const =0
 Deferred checks whether this translator should be invalidated. More...
 
virtual MSTR GetTimingCategory () const =0
 Returns the string label to be used by the time reporting mechanism. More...
 
TranslatorGraphNode & GetGraphNode () const
 For internal use. More...
 

Protected Member Functions

template<typename TranslatorType >
const TranslatorType * AcquireChildTranslator (const TranslatorKey &key, const TimeValue t, ITranslationProgress &translation_progress, TranslationResult &result)
 Acquires a dependency to a another translator and its outputs. More...
 
void Invalidate (const bool defer_invalidation_check=false)
 Invalidates this translator, typically as a result of a change notification callback. More...
 
void InvalidateParents ()
 Invalidates all parents of this translator. More...
 
void TranslatedObjectDeleted ()
 Flags the objects/inputs, being translated by this translated, as having been deleted. More...
 
IRenderSessionContextGetRenderSessionContext ()
 Returns the render session context for which this translator was created. More...
 
const IRenderSessionContextGetRenderSessionContext () const
 Returns the render session context for which this translator was created. More...
 
Translator Outputs
size_t GetNumOutputs () const
 Returns the number of outputs that are present on this translator. More...
 
template<typename OutputType >
std::shared_ptr< const OutputType > GetOutput (const size_t index) const
 Returns the output at the given index, dynamically cast to the given sub-class of ITranslatorOutput. More...
 
void SetNumOutputs (const size_t num)
 Initializes the size of the internal array, used to store the outputs. More...
 
void SetOutput (const size_t index, std::shared_ptr< const ITranslatorOutput > output)
 Initializes the output, at the given index, to the given value. More...
 
void ResetOutput (const size_t index)
 Deletes the output at the given index, such that GetOutput() will henceforth return null. More...
 
void ResetAllOutputs ()
 Deletes all outputs. More...
 
template<typename SimpleValueType >
void SetOutput_SimpleValue (const size_t output_index, const SimpleValueType &value)
 Shortcut method to initialize outputs which map to simple types that require no external cleanup code. More...
 
template<typename SimpleValueType >
SimpleValueType GetOutput_SimpleValue (const size_t output_index, const SimpleValueType &default_value) const
 Returns an output initialized using SetOutput_SimpleValue(). More...
 
- Protected Member Functions inherited from Noncopyable
 Noncopyable ()
 
 ~Noncopyable ()
 

Additional Inherited Members

- Static Public Member Functions inherited from MaxHeapOperators
static UtilExport voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e)
 Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new (size_t size, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new (size_t size, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport void operator delete (void *ptr)
 Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete (void *ptr, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, void *placement_ptr)
 Placement new operator. More...
 
static UtilExport void operator delete (void *ptr, void *placement_ptr)
 Placement delete operator. More...
 
static UtilExport voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary. More...
 
static UtilExport voidaligned_realloc (void *ptr, size_t size, size_t alignment)
 Reallocates memory on a specified alignment boundary. More...
 
static UtilExport void aligned_free (void *ptr)
 Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...
 

Detailed Description

Base class for a translator.

Translators are responsible for translating a set of inputs (classes TranslatorKey and IRenderSessionContext) into one or more outputs (class TranslatorOutput). Together, the translators form a translation graph that is anchored around the scene's root translator. Each Translator is entirely self-contained, such that it may be garbage collected once no longer used by the scene's translation graph.

Member Typedef Documentation

◆ KeyframeList

typedef std::set<TimeValue> KeyframeList

Constructor & Destructor Documentation

◆ Translator()

Translator ( TranslatorGraphNode &  graphNode)
explicit

The constructor expects a reference to a TranslatorGraphNode.

TranslatorGraphNode is internal to the system; the public API merely forward declares it. There is a one-to-one relationship between classes Translator and TranslatorGraphNode, with Translator taking charge of the plugin-side translation task, whereas TransaltorGraphNode is responsible for the system-side management of the translation graph. This relationship is akin to the Pimpl pattern.

◆ ~Translator()

virtual ~Translator ( )
virtual

Member Function Documentation

◆ Translate()

virtual TranslationResult Translate ( const TimeValue  translationTime,
Interval newValidity,
ITranslationProgress translationProgress,
KeyframeList keyframesNeeded 
)
pure virtual

Performs the translation for which this class is responsible.

This method must be implemented to translate the translator's inputs (formed by the TranslatorKey and, possibly, the IRenderSessionContext) into a set of outputs (formed by TranslatorOutput). This method may be called to perform the initial translation of the inputs, or to re-perform the translation because the translator has been invalidated.

Remarks
Whenever this method is called, all outputs that have been acquired from dependencies must be re-acquired. That is, all child translators must be acquired. The outputs should never be cached in any way. This is necessary because all the child dependencies are re-set when a translator is re-translated. This ensures that the graph is continuously up-to-date, with any dangling translator being immediately garbage collected.
Parameters
translationTimeThe time at which the scene is being translated.
[in,out]newValidityThe validity of the translator, to be intersected with the input value. The translator will be re-translated whenever the current time value falls outside of this validity.
translationProgressThe interface through which translation progress is to be reported (optionally).
[out]keyframesNeededOptional set of keyframe time values for which TranslateKeyframe() should be called following the call to Translate().
Returns
The (success) state of the translation process.

◆ TranslateKeyframe()

virtual TranslationResult TranslateKeyframe ( const TimeValue  frame_time,
const TimeValue  keyframe_time,
ITranslationProgress translationProgress 
)
pure virtual

Performs translation for a single keyframe.

This method is designed to optimize the translation of keyframe data for use with motion blur. If an object must be evaluated at various time values (keyframes) in order to generate motion blur data (i.e. motion transforms, motion vectors, etc.), then it may be problematic to generate all that data within the implementation of Translate(). Evaluating an object at various time values, within each call to Translate(), can cause a ping-pong effect if various scene objects were dependent on each other: the object being depended on would be re-evaluated for every keyframe of every dependent object - for example, if three objects were dependent on a fourth, and each had to be evaluated at 4 keyframes for purposes of motion blur, then the fourth object would be fully evaluated a total of 16 times during scene translation. To avoid this problem, it makes sense to serialize the evaluation of keyframes, such that all objects are first evaluate at the first keyframe, then the second, and so on. This way, the fourth object ends up being evaluated only five times (once at time t, then once for each keyframe). When dependencies exist on complex objects, this can have a major impact on overall translation time.

Remarks
AcquireChildTranslator() may not be called from this method (it will always return null). Child translators must be acquired in Translate(), and cached locally if needed by TranslateKeyframe().
It is possible for this method to set translator outputs; if this happens, then the parent translators would be invalidated, and re-translated once all keyframes have been processed. This allows parent translators to have dependencies on outputs that are created as a result of translating the keyframes. But in such a case, of course, the parent translator would have to understand that, the first time gets translated, the outputs of its child translator will not exist yet... and it should not fail in that case, but simply knowlingly wait for the second translation to be successful.
Parameters
frame_timeThe time value at which the scene is being translated - equal to the 't' argument passed to Translate().
keyframe_timeThe time value at which the current keyframe is to be evaluated. This is one of the values returned through the keyframesNeeded argument of Translate(); TranslateKeyframe() will be called once for each keyframe returned through keyframesNeeded, in ascending order.
translationProgressThe interface through which translation progress is to be reported (optionally).
Returns
The (success) state of the translation process.

◆ PreTranslate()

virtual void PreTranslate ( const TimeValue  translationTime,
Interval validity 
)
pure virtual

Called just before Translate() to enable pre-processing of any kind.

This method is to be used to perform per-processing that needs to happen before Translate() is called. A separate method is needed in case the class hierarchy results in a sub-classes Translate() being called before this class. Example uses of this method include calling IRenderSessionContext::CallRenderBegin() or MtlBase::Update().

Parameters
translationTimeThe time at which Translate() is about to be called.
[in,out]validityThe validity of the translator, to be intersected with the input value. The translator will be re-translated whenever the current time value falls outside of this validity.

Implemented in BaseTranslator_ReferenceTarget, BaseTranslator_Object, BaseTranslator_MtlBase, BaseTranslator_INode, and BaseTranslator_Camera.

◆ PostTranslate()

virtual void PostTranslate ( const TimeValue  translationTime,
Interval validity 
)
pure virtual

Called just after Translate() to enable post-processing of any kind.

The principle is identical to that of PreTranslate(), except that this method is called immediately after the call to Translate().

Parameters
translationTimeThe time at which Translate() was just called.
[in,out]validityThe validity of the translator, to be intersected with the input value. The translator will be re-translated whenever the current time value falls outside of this validity.
Remarks
This method is called regardless of the return value of Translate().

Implemented in BaseTranslator_ReferenceTarget, BaseTranslator_Object, BaseTranslator_INode, and BaseTranslator_Camera.

◆ AccumulateStatistics()

virtual void AccumulateStatistics ( TranslatorStatistics stats) const
pure virtual

Called by the system to accumulate statistics on the translated scene.

The implementation may add to the statistics, if this translator outputs anything that is relevant to them.

Parameters
statsThe interface with which statistics may be recorded.

◆ AccumulateGraphStatistics()

void AccumulateGraphStatistics ( TranslatorStatistics statistics) const

Accumulates statistics on the whole translate graph, starting at this translation node.

Included in the traversal are this translator, and all descendant translators. This method would normally be called on a scene root translator.

Parameters
[out]statisticsThe interface with which statistics are recorded.

◆ CheckValidity()

virtual Interval CheckValidity ( const TimeValue  t,
const Interval previous_validity 
) const
pure virtual

Deferred checks whether this translator should be invalidated.

Used in combination with a call to Invalidate(true), this method is called when checking the scene validity to see if this translator should be deferred invalidated. Deferred invalidation is necessary if the translator requires access to the scene to determine if it is in fact invalid. Accessing the scene within notification callbacks is generally unsafe, as some notifications are sent while the scene is in an intermediate state.

Parameters
tThe time at which the validity check is performed.
previous_validityThe current validity interval interval of the translator.
Returns
The new validity interval of the translator; empty if the translator is to be invalidated outright. Return previous_validity to leave the translator's validity as-is.

Implemented in BaseTranslator_ReferenceTarget, BaseTranslator_Object, BaseTranslator_INode, and BaseTranslator_Camera.

◆ GetTimingCategory()

virtual MSTR GetTimingCategory ( ) const
pure virtual

Returns the string label to be used by the time reporting mechanism.

The translation system automatically times every translator for reporting, to the log, a categorized table that shows where translation time is spent. This method returns the label under which this translator's time is reported. Multiple translator classes can use the same label, resulting in their time being added up to a common total. Returning an empty string causes this translator's time to be reported under a "miscellaneous" category.

Implemented in BaseTranslator_MtlBase, BaseTranslator_Environment, and BaseTranslator_Camera.

◆ GetGraphNode()

TranslatorGraphNode& GetGraphNode ( ) const

For internal use.


Returns the TranslatorGraphNode associated with this translator, a private class used by the system as a sort of Pimpl pattern.

◆ AcquireChildTranslator()

const TranslatorType * AcquireChildTranslator ( const TranslatorKey key,
const TimeValue  t,
ITranslationProgress translation_progress,
TranslationResult result 
)
protected

Acquires a dependency to a another translator and its outputs.

This method acquires a dependency to the translator that matches the given TranslatorKey. An existing translator will be re-used, if one exists for the given key - otherwise a new one will be created. The acquired translator is automatically translated as/if necessary and its outputs are automatically acquired by the current translator, such that they will not be garbage collected so long as they are in use.

Parameters
keyThe key that uniquely identifies the translator to be acquired.
tThe time at which the acquired translator will be translated.
translation_progressThe progress interface that was passed to the call to Translate().
resultStores the result of the translation of the child translator.
Returns
The acquired child translator, dynamically cast to the given template type. Returns null if and only the tranlsation did not succeed (result != TranslationResult::Success).
49 {
50  const Translator* translator = AcquireChildTranslatorInternal(key, t, translationProgress, result);
51  const TranslatorType* cast_translator = dynamic_cast<const TranslatorType*>(translator);
52  DbgAssert(translator == cast_translator); // check that cast was valid
53  return cast_translator;
54 }
Translator(TranslatorGraphNode &graphNode)
The constructor expects a reference to a TranslatorGraphNode.
#define DbgAssert(expr)
Definition: assert1.h:82

◆ Invalidate()

void Invalidate ( const bool  defer_invalidation_check = false)
protected

Invalidates this translator, typically as a result of a change notification callback.

Parameters
defer_invalidation_checkIf set to true, then the translator is not immediately invalidated. Instead, upon next checking whether the scene requires an update, CheckValidity() will be called to assess the translator's validity. Deferred invalidation is necessary if the translator requires accessing the scene to assess its validity; accessing the scene within a change notification callback is generally unsafe as these notifications are sometimes send out while the scene is in an intermediate state.

◆ InvalidateParents()

void InvalidateParents ( )
protected

Invalidates all parents of this translator.

Invalidation of the parent translators forces them to be re-translated on the next scene update. This may be necessary if the outputs of the translator change. Normally, changing the outputs of the translator using the SetOutput() method automatically invalidates the parents. But there may be cases where this mechanism is insufficient, e.g. if a scene change would require a translator to be discarded and re-created from scratch (as the TranslatorKey could end up creating a translator of a different class).

◆ TranslatedObjectDeleted()

void TranslatedObjectDeleted ( )
protected

Flags the objects/inputs, being translated by this translated, as having been deleted.

This method is to be called when a change notification callback notifies us that whatever this translator translates has been deleted. For example, if this translator were to translate an INode, and that INode were to be deleted from the scene, then the change notification callback should call this method. The system will always ignore translators that have been flagged this way, to avoid accessing dangling pointers. But should this translator be re-acquired by another one, then this flag is cleared and the translator is allowed to proceed as normal - the rationale being that the object is assumed to have been un-deleted (through an undo operation).

◆ GetNumOutputs()

size_t GetNumOutputs ( ) const
protected

Returns the number of outputs that are present on this translator.

◆ GetOutput()

std::shared_ptr< const OutputType > GetOutput ( const size_t  index) const
protected

Returns the output at the given index, dynamically cast to the given sub-class of ITranslatorOutput.

Remarks
Translator outputs are automatically acquired (through the system) by dependent translators, such that outputs will get garbage collected only once they are no longer referenced by anyone.
This outputs returned by this method are flagged const, such that they may not be modified once installed. Modifying an output value can only be done by replacing that output - i.e. calling SetOutput(). This allows the system to catch all changes in output values, and automatically notify / invalidate all dependent translators which then need to be updated to take the new output value into account.
Will return null if the given output has not been initialized.
58 {
59  const std::shared_ptr<const ITranslatorOutput> output = GetOutputInternal(index);
60  const std::shared_ptr<const OutputType> cast_output = std::dynamic_pointer_cast<const OutputType>(GetOutputInternal(index));
61  DbgAssert(output == cast_output); // check that cast was valid
62  return cast_output;
63 }

◆ SetNumOutputs()

void SetNumOutputs ( const size_t  num)
protected

Initializes the size of the internal array, used to store the outputs.

GetNumOutputs() will henceforth return the value passed here.

Remarks
This method is a mere convenience and does not need to be called; SetOutput() will automatically increase the size of the array as necessary.

◆ SetOutput()

void SetOutput ( const size_t  index,
std::shared_ptr< const ITranslatorOutput output 
)
protected

Initializes the output, at the given index, to the given value.

Remarks
The array, used internally to store the outputs, is automatically increased in size if needed.

◆ ResetOutput()

void ResetOutput ( const size_t  index)
inlineprotected

Deletes the output at the given index, such that GetOutput() will henceforth return null.

66 {
67  SetOutput(output_index, std::shared_ptr<ITranslatorOutput>());
68 }
void SetOutput(const size_t index, std::shared_ptr< const ITranslatorOutput > output)
Initializes the output, at the given index, to the given value.

◆ ResetAllOutputs()

void ResetAllOutputs ( )
inlineprotected

Deletes all outputs.

71 {
72  SetNumOutputs(0);
73 }
void SetNumOutputs(const size_t num)
Initializes the size of the internal array, used to store the outputs.

◆ SetOutput_SimpleValue()

void SetOutput_SimpleValue ( const size_t  output_index,
const SimpleValueType &  value 
)
protected

Shortcut method to initialize outputs which map to simple types that require no external cleanup code.

The output mechanism is primarily meant to store interfaces that encapsulates handles or pointers to internal data structures, which may need special cleanup code when the output is destroyed. But if the output value has no cleanup code, or if this cleanup code is encapsulated within the output type's own destructor, then this method may be used to avoid the hassle of implementing a custom ITranslatorOutput.

Remarks
The output value will be copied, making this method generally non-suitable for any data types that hold references which must be destroyed by the destructor.
77 {
78  // Check if the value is different before setting it (to avoid invalidating the translation graph if the value doesn't change)
79  const auto output = GetOutput<SimpleValueTranslatorOutput<SimpleValueType>>(output_index);
80  if((output == nullptr) || (output->get_value() != value))
81  {
82  SetOutput(output_index, std::shared_ptr<SimpleValueTranslatorOutput<SimpleValueType>>(new SimpleValueTranslatorOutput<SimpleValueType>(value)));
83  }
84 }

◆ GetOutput_SimpleValue()

SimpleValueType GetOutput_SimpleValue ( const size_t  output_index,
const SimpleValueType &  default_value 
) const
protected

Returns an output initialized using SetOutput_SimpleValue().

Parameters
output_indexThe index of the output to be fetched.
default_valueThe value to be returned, if the output should be missing or uninitialized.
See also
SetOutput_SimpleValue().
88 {
89  const auto output = GetOutput<SimpleValueTranslatorOutput<SimpleValueType>>(output_index);
90  return (output != nullptr) ? output->get_value() : default_value;
91 }

◆ GetRenderSessionContext() [1/2]

IRenderSessionContext& GetRenderSessionContext ( )
protected

Returns the render session context for which this translator was created.

◆ GetRenderSessionContext() [2/2]

const IRenderSessionContext& GetRenderSessionContext ( ) const
protected

Returns the render session context for which this translator was created.