Interface: CustomSceneStreamManager

The CustomSceneStreamManager interface is used to query, add, modify and remove CustomFileStreams in the current 3ds Max scene file. Available in 3ds Max 2019 and higher.

Flag Values

Custom file streams have three flags that determine how they are handled by the CustomFileStreamManager:

Persistence Flag

When this flag is set, the CustomSceneStreamManager writes this stream to the scene file when the scene file is saved, and reads the stream into its cache when the scene file is loaded. This flag's value is persisted across a save/load operation. This allows a CustomFileStream to be automatically persisted across multiple load/save operations. See is/setStreamPersistent().

Save Flag

This flag indicates whether the CustomFileStream is saved when the scene file is saved. Setting this flag allows you to add a non-persistent stream and have it saved on scene file save. This flag does not persist, and is cleared when the stream is read from the scene file.

No Load Flag

This flag indicates whether the CustomFileStream is loaded by the CustomSceneStreamManager when the scene file is loaded. This flag allows you to create streams that are not loaded on file load, for example for data to be consumed by an external tool or workflow. See getNoLoadOnSceneLoad() and setNoLoadOnSceneLoad().

Note: These flags are stored in a "private" 32 bit integer (private in the sense that all bits are reserved for future use by 3ds Max). The CustomSceneStreamManager interface exposes methods to get this integer value, or to get and set the individual flags in the value. There is also a "public" 32 bit integer value that you can use for defining additional custom flags.

Note: If the Save Flag is set, the Persistence Flag is not set, and the No Load Flag is not set, then the stream is persisted across a single save/load operation, since the Save Flag is cleared on load.

Notifications

Because the CustomSceneStreamManager code may be loaded and invoked at different times, depending on system configuration, the order in which it and other 3ds Max components will receive file operation notifications can be unpredictable. For this reason, you should use the interface's methods for registering callbacks if you need to operate on the CustomSceneStreamManager itself, or on the scene file (such as copying and storing it).

Properties:

.numEntries : integer : Read

The number of entries in the CustomSceneStreamManager's cache.

.locked : boolean : Read|Write

Whether the CustomSceneStreamManager is locked. When locked, the CustomSceneStreamManager does not react to any notifications from 3ds Max. This means that the manager does not automatically load or save data streams.

Methods:

<string>getStreamName <index>index

Returns the name of the stream for the specified cache entry index.

<index>getStreamByName <string>name

Returns the index of the named stream. Throws an exception if the named stream does not exist.

<boolean>doesStreamExist <value>which

Returns true if the specified stream exists. The which parameter can be either a stream name or a stream index.

<integer>getStreamFlag <value>which
    privateFlag:<boolean>
    privateFlag default value: false

<void>setStreamFlag <value>which
    <integer>value privateFlag:<boolean>
    privateFlag default value: false

Gets or sets the specified stream's public or private flags value. The "private" integer contains the persistence, save, and cache flags in the first 3 bits. The remaining bits are reserved for future use. The "public" integer can contain any flags or other data you wish. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<boolean>isStreamDataAnArray <value>which

Returns true if the specified stream's content is an array of strings. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<string>getStreamData <value>which

Returns the specified stream's content as a string. If the content is an array of strings, the first string is returned. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<string array>getStreamDataAsArray
    <value>which

Returns the specified stream's content as an array of strings. If the content is a single string, it is returned in a 1 element array. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<void>setStreamData <value>which
    <string>string

Sets the specified stream's content as a string. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<void>setStreamDataAsArray <value>which <string array>string_array
       setStreamDataAsArray - no automatic redraw after invoked

Sets the specified stream's content as an array of strings. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist. Note: if you store an empty array, isStreamDataAnArray() returns false.

<boolean>isStreamPersistent <value>which

<void>setStreamPersistent <value>which
    <boolean>persistent

Gets or sets the specified stream is flagged as persistent when written to the scene file. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<boolean>getSaveNonPersistentStream <value>which

<void>setSaveNonPersistentStream <value>which <boolean>val

Gets or sets whether the specified stream is flagged as to be written to the scene file even if not flagged as persistent file. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<boolean>getNoLoadOnSceneLoad <value>which

<void>setNoLoadOnSceneLoad <value>which <boolean>val

Gets or sets whether the specified stream is flagged as not to be loaded on scene file load when written to the scene file. The which parameter can be either a stream name or a stream index. Throws an exception if the specified stream does not exist.

<void>deleteStream <value>which

Deletes the specified stream. The which parameter can be either a stream name or a stream index.

<index> createStream <string>name
persistent:<boolean> saveNonPersistentStream:<boolean>
noLoadOnSceneLoad:<boolean>
persistent default value: true
saveNonPersistentStream default value: true
noLoadOnSceneLoad default value: false

Creates a cache entry with the specified name and flag values. The content of the entry will be an empty string. Throws an exception if a cache entry with the same name already exists.

<void>registerCallback <value>callback_fn
<value>callback_id <enum>event
event enums: {#postLoad|#preSave|#postSave}

Registers a callback function that is called when the corresponding CustomSceneStreamManager event occurs. The callback_id must be a name value. The callback function must take 2 arguments: the first argument is the file name and the second argument is the event type as a name value (#postLoad, #preSave, or #postSave). If an exception occurs while executing a callback function, that function is automatically unregistered.

<void>unregisterCallbacks callback_fn:<value>
callback_id:<value> event:<enum>
callback_fn default value: undefined
callback_id default value: undefined
event enums: {#postLoad|#preSave|#postSave}
event default value: -1

Unregisters any callback functions that match all the values specified via the keyword arguments.

<value>getCallbacks callback_fn:<value>
callback_id:<value> event:<enum>
callback_fn default value: undefined
callback_id default value: undefined
event enums: {#postLoad|#preSave|#postSave}
event default value: -1

Returns an array of all callback functions that match all the values specified via the keyword arguments.