3ds Max C++ API Reference
|
Base class for a translator. More...
#include <Translator.h>
Public Types | |
typedef std::set< TimeValue > | KeyframeList |
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... | |
IRenderSessionContext & | GetRenderSessionContext () |
Returns the render session context for which this translator was created. More... | |
const IRenderSessionContext & | GetRenderSessionContext () 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 void * | operator new (size_t size) |
Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More... | |
static UtilExport void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | operator new[] (size_t size, int block_type, const char *filename, int line) |
New operator used to allocate arrays of objects. More... | |
static UtilExport void * | operator 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 void * | operator 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 void * | operator 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 void * | operator 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 void * | aligned_malloc (size_t size, size_t alignment) |
Allocates memory on a specified alignment boundary. More... | |
static UtilExport void * | aligned_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... | |
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.
typedef std::set<TimeValue> KeyframeList |
|
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.
|
virtual |
|
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.
translationTime | The time at which the scene is being translated. | |
[in,out] | newValidity | The 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. |
translationProgress | The interface through which translation progress is to be reported (optionally). | |
[out] | keyframesNeeded | Optional set of keyframe time values for which TranslateKeyframe() should be called following the call to Translate(). |
|
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.
frame_time | The time value at which the scene is being translated - equal to the 't' argument passed to Translate(). |
keyframe_time | The 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. |
translationProgress | The interface through which translation progress is to be reported (optionally). |
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().
translationTime | The time at which Translate() is about to be called. | |
[in,out] | validity | The 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.
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().
translationTime | The time at which Translate() was just called. | |
[in,out] | validity | The 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_INode, and BaseTranslator_Camera.
|
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.
stats | The interface with which statistics may be recorded. |
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.
[out] | statistics | The interface with which statistics are recorded. |
|
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.
t | The time at which the validity check is performed. |
previous_validity | The current validity interval interval of the translator. |
Implemented in BaseTranslator_ReferenceTarget, BaseTranslator_Object, BaseTranslator_INode, and BaseTranslator_Camera.
|
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.
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.
|
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.
key | The key that uniquely identifies the translator to be acquired. |
t | The time at which the acquired translator will be translated. |
translation_progress | The progress interface that was passed to the call to Translate(). |
result | Stores the result of the translation of the child translator. |
|
protected |
Invalidates this translator, typically as a result of a change notification callback.
defer_invalidation_check | If 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. |
|
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).
|
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).
|
protected |
Returns the number of outputs that are present on this translator.
|
protected |
Returns the output at the given index, dynamically cast to the given sub-class of ITranslatorOutput.
Initializes the size of the internal array, used to store the outputs.
GetNumOutputs() will henceforth return the value passed here.
|
protected |
Initializes the output, at the given index, to the given value.
Deletes the output at the given index, such that GetOutput() will henceforth return null.
|
inlineprotected |
Deletes all outputs.
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.
|
protected |
Returns an output initialized using SetOutput_SimpleValue().
output_index | The index of the output to be fetched. |
default_value | The value to be returned, if the output should be missing or uninitialized. |
|
protected |
Returns the render session context for which this translator was created.
|
protected |
Returns the render session context for which this translator was created.