| Previous Topic (None) | Up (Contents) | Next Topic (PRT Loader MAXScript Exposure) |
MaxScript Access
- 1 MaxScript Access
Introduction
Krakatoa is a hybrid C++/MAXScript system designed to use the best sides of the 3ds Max SDK and the MAXScript language.
As a result, almost the whole User Interface of Krakatoa Renderer and the Particle Loader objects has been implemented using MAXScript.
Logically, anyone with enough scripting knowledge could interact with Krakatoa and even add or replace UI-level functionality.
Krakatoa Components
The plug-in files are:
Krakatoa consists of a single C++ DLL developed using the 3ds Max SDK:
- The MaxKrakatoa.dlr implements
- The Krakatoa Renderer plug-in
- The Krakatoa Particle Loader geometry plug-in low-level functionality.
- The Krakatoa File Birth operator in Particle Flow
- The Krakatoa File Update operator in Particle Flow
- The Krakatoa Options operator in Particle Flow
- The Krakatoa ID Test operator in Particle Flow
- The Krakatoa Geometry Test operator in Particle Flow
All other components of Krakatoa are implemented as MAXScripts building upon the objects and interfaces implemented by the above plug-in. The source files of these scripts are provided unprotected - you can use them to learn how Krakatoa can be controlled using MAXScript.
The script files are:
- KrakatoaStartup.ms - this script is located in the same folder as the two plug-ins and is loaded by 3ds Max as a plug-in file (MAXScript source files are loaded like plug-ins since 3ds Max R3 if they are placed in a folder listed in the Plugins paths). This script contains startup code which loads all other scripts in a well-defined order and also ensures that MacroScript icons are up-to-date.
- KrakatoaGUI.ms - this script implements the complete Krakatoa GUI Floater and all its rollouts.
- KrakatoaPRTLoader.ms - this script implements a scripted geometry plug-in which extends the one implemented by MaxKrakatoa.dlr. The SDK plug-in does not provide ANY User Interface and exposes only very few properties. The scripted plug-in is what is shown in the Command Panel and can also be dissected for learning purposes, or modified at your own risk to provide a different controls layout or even additional functionality.
- Krakatoa_PRTLoader_FileMan_AX.ms and Krakatoa_PRTLoader_FileMan_DM.ms - the first file is loaded conditionally when 3ds Max 8 is detected, the latter is used in 3ds Max 9 and higher. They are responsible for loading the multiple components of the File Manager dialog opened by the Edit... button in the Particle Loader's User Interface. The former uses an ActiveX ListView control, the latter implements the same functionality using a DotNet ListView control.
- Krakatoa_PRTLoader_FileMan_01.ms and Krakatoa_PRTLoader_FileMan_03.ms - these are the version-independent components of the File Manager.
- Krakatoa_PRTLoader_FileMan_02_AX.ms and Krakatoa_PRTLoader_FileMan_02_DN.ms - these files are the version-dependent ActiveX and DotNet components of the File Manager loaded by the main file.
- Krakatoa_Shadows_Utility.ms - this file implements the Shadows Utility used to apply Krakatoa shadows in another Renderer.
- Krakatoa_PRTScanner_Utility.ms - this file implements the Particle Analysis Utility.
- KrakatoaPartitionTasksOnDeadline.ms - this file is used to calculate Partitions on Deadline in "One Partition Per Task" mode.
- KrakatoaToolbar.ms - this file implements the Krakatoa Toolbar MacroScripts.
- Krakatoa_PRTChannel_Modifier.ms - this file contains the Krakatoa Camera modifier and will be used to introduce a PRT Channel Modifier in a future release.
- Krakatoa_PFlowOperators_ChannelSelectorDialog.ms - this file implements the User Interface Floater found in the Krakatoa File Update PFlow Operator via its Channel Setup button.
- Krakatoa_PRTloader_Manipulator.ms - this file implements the PRT Loader Manipulator helper.
Frantic Particles Interface
The Krakatoa Renderer does NOT use Parameter Blocks to store its settings, but a custom string-based system developed by Frantic Films Software and employed in various products including the Amaretto Renderer. Thus, using the standard showProperties() MAXScript inspector methods would return little information.
For example:
renderers.current Krakatoa:Krakatoa showProperties renderers.current false showInterfaces renderers.current OK
The Krakatoa Renderer exposes a Function Publishing Interface called "FranticParticles" which can be used to communicate with the renderer.
Interface: FranticParticles
Properties:
.RenderOutputFiles : value : Read
Returns the render output file based on the file name specified in the 3ds Max Render Scene Dialog.
.Version : value : Read
Returns the version string of the current Krakatoa plug-in, for example "1.1.0.31392" The first digit is the major release number, followed by a minor version number and update number. The last 5 digit number is the internal version control system iteration. This iteration number is shared among all Frantic applications, so based on it is possible to tell whether a version of Krakatoa was built before or after a specific version of Deadline for example.
.KrakatoaHome : value : Read
Returns the home (installation) directory of Krakatoa, for example
"C:\Program Files (x86)\Frantic Films\Krakatoa\"
NOTE: The home directory of Krakatoa is resolved by the MaxKrakatoa.dlr plug-in as follows:
The plug-in queries the path it was loaded from, then moves up two folders and returns the result as the KrakatoaHome path. So if the plug-in was loaded from "C:\Program Files (x86)\Frantic Films\Krakatoa\3dsMax9\x64", the path is resolved as the root of this path minus the last two folders, "C:\Program Files (x86)\Frantic Films\Krakatoa\".
If you want to move your Krakatoa installation into another directory structure, you should still make sure that the MaxKrakatoa.dlr file is located two directories deeper than the folder containing the Icons and Scripts sub-folders!
.PopupLogWindowOnMessage : bool : Read|Write
Get/set whether the Log Window will automatically pop up when a message is output to it. Default is false.
.LogWindowVisible : bool : Read|Write
Get/set whether the Log Window is currently open. Default is false. Setting this property to true opens the Log Window, setting it to false closes it.
Methods:
<void>AcquireLicense()
This method forces Krakatoa to acquire a license from FlexLM (if available).
<void>ReleaseLicense()
This method forces Krakatoa to release the license and enter Evaluation mode.
<bool>HasValidLicense()
This method returns true if Krakatoa is running in Licensed mode and false if it is in Evaluation mode.
<void>AddProperty <value>PropertyName <value>Value
This method adds a new property with the given name and initial value to the Krakatoa Renderer. You can add any number of uniquely named properties to the Krakatoa Renderer, even if the Renderer itself would not understand them. These properties can contain arbitrary values and will be stored in the Renderer object with the Max scene.
<void>SetProperty <value>PropertyName <value>Value
This method sets the value of an already defined property with the given name to the specified value. The value will be converted to a string internally.
<value>GetProperty <value>PropertyName
This method returns the value stored in the given named property as a string.
For example:
FranticParticles.getProperty "MotionBlurSegments" "3" FranticParticles.getProperty "UseDepthMaps" "true"
<integer>GetIntProperty <value>PropertyName
This method returns the value stored in the given named property as an integer, assuming the value stored in it was an integer. If the value was not an integer, a runtime error will be reported.
For example:
FranticParticles.getIntProperty "MotionBlurSegments" 3 FranticParticles.getIntProperty "UseDepthMaps" -- Runtime error: Integer Property "UseDepthMaps" had invalid value "true"
<float>GetFloatProperty <value>PropertyName
This method returns the value stored in the given named property as a float. If the stored value is an integer, it will be converted and returned as float. If it was not an integer or a float, a runtime error will be reported.
For example:
FranticParticles.getFloatProperty "DepthOfFieldSampleRate" --this is a float value 0.1 FranticParticles.getFloatProperty "MotionBlurSegments" --this is an integer value 3.0 FranticParticles.getFloatProperty "UseDepthMaps" --this is a boolean value -- Runtime error: Float Property "UseDepthMaps" had invalid value "true"
<bool>GetBoolProperty <value>PropertyName
This method returns the value stored in the given named property as a boolean value, assuming the value stored in the property is a boolean value. Otherwise, a runtime error will be reported.
For example:
FranticParticles.getBoolProperty "UseDepthMaps" true FranticParticles.getBoolProperty "MotionBlurSegments" -- Runtime error: Bool Property "MotionBlurSegments" had invalid value "3"
<bool>HasProperty <value>PropertyName
This method returns true if the given named property exists in the renderer.
<void>SaveMatteObjectsToFileSequence <value>Filename <value>ObjectArray <integer>StartFrame <integer>EndFrame
This method performs Matte Objects file generation for use in the stand-alone version of Krakatoa. It expects a filename string, an array of objects to save, a start frame and end frame value as arguments. NOTE: This functionality is deprecated. It is not exposed in the Krakatoa GUI anymore.
<void>InvalidateParticleCache()
This method invalidates the Particle Cache and the Lighting Cache and releases the memory used by both.
<void>InvalidateLightingCache()
This method clears the Lighting Cache only. The memory is not released because the Particle Cache always allocates both caches.
<float>GetCacheSize()
This method returns the Particle Cache size in Megabytes.
<value>ReplaceSequenceNumberWithHashes <value>FileName
This method replaces a sequence number with #### in the file name passed as argument and returns a new file name.
For example:
FranticParticles.ReplaceSequenceNumberWithHashes "c:\\temp\\test0001.tga"
"c:\temp\test####.tga"
<value>ReplaceSequenceNumber <value>FileName <integer>Frame
This method replaces a sequence number with the correct sequence number based on the given frame and returns a new file name. If the file does not contain a frame number yet, it will be added. If it contains an existing frame number, the existing format will be preserved.
For example:
FranticParticles.ReplaceSequenceNumber "c:\\temp\\test0001.tga" 4 "c:\temp\test0004.tga" FranticParticles.ReplaceSequenceNumber "c:\\temp\\test_.prt" 42 "c:\temp\test_0042.prt" FranticParticles.ReplaceSequenceNumber "c:\\temp\\test_00000.bin" 123 "c:\temp\test_00123.bin"
<value>MakePartitionFilename <value>Filename <integer>Index <integer>Count
This method adds the Particle Partition signature used by Krakatoa to the filename provided as first argument. The second argument is the partition number, the third argument is the total partitions count.
For example:
FranticParticles.MakePartitionFilename "c:\\temp\\test0001.tga" 3 10
"c:\temp\test_part3of10_0001.tga"
<int array>GetPartitionFromFilename <value>Filename
This method returns a two-element array containing the partition number and the total partitions count according to the Particle Partition signature in the file name. If the signature is missing, the array will contain two zero values.
For example:
FranticParticles.GetPartitionFromFilename "c:\\temp\\test_part3of10_0001.tga" #(3, 10) FranticParticles.GetPartitionFromFilename "c:\\temp\\test0001.tga" #(0, 0)
<value>ReplacePartitionInFilename <value>Filename <integer>Index
This method replaces the partition number in the file name signature with a new number, provided the Partition signature exists. Otherwise, the file name will not be modified.
For example:
FranticParticles.ReplacePartitionInFilename "c:\\temp\\test_part3of10_0001.tga" 5 "c:\temp\test_part5of10_0001.tga" FranticParticles.ReplacePartitionInFilename "c:\\temp\\test0001.tga" 5 "c:\temp\test0001.tga"
<value>GetFileParticleChannels <value>File
This method returns all channels saved in the specified particle file (PRT, CSV or BIN file).
<value>GetFileParticleCount <value>File
Returns the number of particles saved in the given file. Returns -1 if the file is of CSV type since the count cannot be queried directly. Returns undefined if the file cannot be read or does not exist.
For example:
FranticParticles.GetFileParticleCount "c:\\temp\\nonexistentfile.prt" undefined FranticParticles.GetFileParticleCount "c:\\temp\\test100K_0001.prt" 100000 FranticParticles.GetFileParticleCount "c:\\temp\\test10K_00001.bin" 10000 FranticParticles.GetFileParticleCount "c:\\temp\\test10K_0001.csv" -1
<value>GetRenderParticleChannels()
This method returns the particle channels currently required by the Renderer to perform the desired rendering operations as an array of arrays where each sub-array consists of the channel name, type and arity.
For example:
franticParticles.GetRenderParticleChannels()
#(#("Position", "float32", 3), #("Color", "float16", 3),
#("Lighting", "float16", 3), #("Density", "float16", 1))
<value>GetCachedParticleChannels()
This method returns the particle channels currently in the particle cache as an array of arrays where each sub-array consists of the channel name, type and arity. If a channel returned by GetRenderParticleChannels() is NOT in the resulting array, Krakatoa will have to rebuild the cache even if it is enabled (yellow state)
<integer>GetCachedParticleCount()
This method returns the number of particles currently in the cache.
<void>LogError <value>Msg
Outputs the message string given as argument as an Error to the Krakatoa Log Window.
<void>LogWarning <value>Msg
Outputs the message string given as argument as a Warning to the Krakatoa Log Window.
<void>LogProgress <value>Msg
Outputs the message string given as argument as a Progress info to the Krakatoa Log Window.
<void>LogStats <value>Msg
Outputs the message string given as argument as a Statistics entry to the Krakatoa Log Window.
<void>LogDebug <value>Msg
Outputs the message string given as argument as a Debug message to the Krakatoa Log Window.
The FranticParticleRenderMXS Struct
The file KrakatoaGUI.ms creates a MAXScript struct containing functions called by the renderer itself and used to manage the User Interface.
The FranticParticleRenderMXS struct is an instance of the following struct definition:
#Struct:FranticParticleRenderMXSStruct( convertToHMS:<fn>, SetDropDownValue:<fn>, loadSaveDialogOpen:<fn>, DeadlineDetected:<data>, InitTreeView:<fn>, fillInTreeView:<fn>, compareFN:<fn>, DetectDeadline:<fn>, addChildren:<fn>, openGUI:<fn>, InitRenderer:<fn>, saveCustomProperty:<fn>, GetEarliestBirthFrame:<fn>, fixTimeString:<fn>, GetDeadlineNetworkRoot:<fn>, CancelGUI:<fn>, loadSaveButtonPressed:<fn>, saveCustomDefaults:<fn>, PostLoadEvent:<fn>, saveRolloutPreset:<fn>, tagCounter:<data>, savePresetAll:<fn>, CloseGUI:<fn>, framePreRender:<fn>, increasePFlowSystemLimits:<fn>, presetToLoadDDLSelected:<fn>, lastFrameRenderStartTime:<data>, initDefaultSetting:<fn>, saveSceneInfo:<fn>, loadPresetAll:<fn>, displaySavePresetDialog:<fn>, loadRolloutPreset:<fn>, sortFilesByDate:<fn>, compareSettings:<fn>, LeadingZeros:<fn>, GlobalRefreshGUI:<fn>, saveRenderHistory:<fn>)
Variables:
lastFrameRenderStartTime integer, default:0
Used by #preRenderFrame callbacks to store the rendering start time for measuring the render time that is stored in History files.
DeadlineDetected boolean, default:false
Contains true when Deadline Network Manager was detected on the computer, false when it is not installed. Set by the function FranticParticleRenderMXS.DetectDeadline()
tagCounter integer, default:0
Used internally for TreeView controls generation.
Functions:
User Interface Startup, Open and Close Functions
DetectDeadline()
This function detects the Frantic Films Deadline Network Manager on the system Krakatoa is running on and sets the FranticParticleRenderMXS.DeadlineDetected variable to true of false.
OpenGUI()
This function is being called by the Krakatoa Renderer>Open Scripted GUI button, but can be used by any script to open the Krakatoa GUI. It is also being used by the KrakatoaGUI MacroScript defined in the KrakatoaGUI.ms file.
CancelGUI()
This function is being called by the Krakatoa Renderer, but is not implementing any functionality at this moment.
CloseGUI()
This function is being called by the Krakatoa Renderer, but is not implementing any functionality at this moment.
Render Initialization, Defaults and Preferences
InitRenderer()
This function is called when a new instance of the Krakatoa renderer is created. It adds every property currently implemented in Krakatoa using a factory default or loads the default values stored as User Defaults to INI file (if available) by calling the initDefaultSetting() function described below.
initDefaultSetting <string>theKey <string>theDefault
This function is used to initialize the Krakatoa values to defaults when a new instance of the Krakatoa Renderer is being created. Krakatoa provides two levels of defaults - factory defaults and user defaults. The factory defaults are hard-coded in the KrakatoaGUI.ms file and applied to the renderer if no user defaults exist for the respective property. The user defaults are stored locally in an INI file and will be used if a key with the given name exists in the INI file. The function is called with two arguments - the first argument is the key name which is both the internal property name used by the AddProperty/GetProperty/SetProperty methods and the name of the INI file entry. If the given key exists in the [Defaults] category of the INI file, its value will be used. If no such key exists, the second argument will be used as the default value. Then the function calls the AddProperty method and sets the initial value of the property to the default value.
saveCustomProperty <string>Key
This function saves the given property to a Key with the same name in the [Defaults] category of the \KrakatoaDefaults.ini file.
PostLoadEvent()
This function is called after a new file is loaded. It can be used to add compatibility patches to adjust settings in files saved using older versions of Krakatoa. Currently, no such patches are defined, but the function invokes a global UI refresh to update the Krakatoa GUI after a MAX file has been loaded.
GetDeadlineNetworkRoot()
This function returns the network root (location of the Deadline Repository) if Deadline is installed on the machine/network. Otherwise returns empty string ""
increasePFlowSystemLimits()
This function increases the system limit of all scene Particle Flow emitters to 100 million if they are not already set to a higher value. Note that the PFlow GUI will show only values up to 10 million, but internally the limit can be higher.
GlobalRefreshGUI()
This function calls the refresh_GUI() function in all rollouts of the Krakatoa GUI.
Render History Functions
InitTreeView <treeView> dotnet:<bool>
This function is being used to initialize a TreeView control.addChildren <treeView> <tvNode> <children> <parent> dotnet:<bool>
- <treeView> is an ActiveX or DotNet TreeView control.
- The optional keyword dotnet: is false by default and assumes the TreeView is an ActiveX control. When set to true, the TreeView will be assumed to be a DotNet control.
This function is being used to add children to a TreeView node.fillInTreeView <treeView> dotnet:<bool>
- <treeView> is an ActiveX or DotNet TreeView control.
- <tvNode> is the TreeView node to add the children to.
- <Children> is the array of UI controls and rollouts to be added to the TreeView.
- <Parent> is the Parent object of the children being added, for example the rollout the UI controls belong to.
- The optional keyword dotnet: is false by default and assumes the TreeView is an ActiveX control. When set to true, the TreeView will be assumed to be a DotNet control.
This function is being used to populate a TreeView control.compareFN <index>valueIndex1 <index>valueIndex2 <array>valueArray
- <treeView> is an ActiveX or DotNet TreeView control.
- The optional keyword dotnet: is false by default and assumes the TreeView is an ActiveX control. When set to true, the TreeView will be assumed to be a DotNet control.
Used by the QuickSort function for indexed sort.
framePreRender()
Called by a FramePreRender Callback, stores the current time in the struct property lastFrameRenderStartTime which is then used to calculate the actual render or save time for the last frame.
sortFilesByDate <array>theFiles feedback:(#none|#history)
Sorts the files in the provided array by creation date. If the optional feedback: parameter is set to #history, the function will also update the History feedback dialog. Default is #none.
loadPresetAll <filename>presetFile
Loads the given preset file.
saveRenderHistory()
This function is called by the PostRender callback registered by Krakatoa and stores a Render History file for the last rendering performed (only if the Krakatoa Scripted GUI is open and the Save Render History option is checked. It is called by both image rendering and particle saving operations. In the former case, it also saves the last rendered image to disk.
saveCustomDefaults()
This function saves all current settings from the Krakatoa Scripted GUI to an INI file which are used to initialize new instances of the Krakatoa Renderer.
presetToLoadDDLSelected <index>selectedListItem
This function is used to initialize the TreeView with the preset selected in the drop-down list at the bottom of the Load/Save Preset dialog.
displaySavePresetDialog()
This function implements the Load/Save dialog for both Max 8 (using ActiveX Treeview control) and Max 9 and higher (using DotNet Treeview control).
loadRolloutPreset <rollout>rollout <filename>presetFile
This function loads the settings of the given rollout from the given preset file.
saveRolloutPreset <rollout>rollout <filename>presetFile
This function saves the settings of the given rollout to the given preset file.
loadSaveDialogOpen()
This function performs the opening of the load or save version of the dialog.
compareSettings <filename>File1 <filename>File2
This function performs the comparison of all settings in the two given files and returns an array of all difference including the category, key name, the value in the first file and the value in the second file.
loadSaveButtonPressed()
This function is called when the Load or Save button is pressed in the Load/Save Dialog. It performs all operations necessary to load and save each rollout in the UI.
saveSceneInfo <filename>presetFile
This function saves information about the current 3ds Max scene to the given preset file. The info includes object counts, particle counts, scene name and path and last particle rendering/saving time.
SetDropDownValue <control>dropDownList <string>value
This function sets the dropdown selection value to the item which matches the given string input. The purpose of this is to store all drop down list items as text labels instead of integers, so the ordering and content of drop-down lists can be changed without breaking compatibility. Wherever the internal name has to be replaced with a more descriptive name, KrakatoaGUI.ms performs remapping of the internal and UI names.
savePresetAll <filename>presetFile
This function loops through all rollouts scheduled for saving and calls the saveRolloutPreset function of each one of them.
Utility Functions
GetEarliestBirthFrame()
Returns the frame with the least Particle Flow particles. Used when submitting multiple partition jobs to Deadline since saving files on a later frame would cause multiple and slow PFlow updates.
fixTimeString <string>timeString
Replaces all delimiters like : and / in a time string with underscores for use in file names.
--For example theTime = localtime "6/15/2007 2:45:28 PM" FranticParticleRenderMXS.fixTimeString theTime "6_15_2007_2_45_28_PM"
LeadingZeros <integer>value <integer>count
Returns a string of leading zeroes for the given value. The second parameter defines the total length of the resulting number,
--For example theValue = 123 123 theZeros = FranticParticleRenderMXS.LeadingZeros theValue 5 "00" theZeros + theValue as string "00123"
convertToHMS <integer>TimeInSeconds
Converts the time in seconds to hours:minutes:seconds format.
--For example FranticParticleRenderMXS.convertToHMS 123 "00:02:03"
User-Defined Partitioning MAXScript Functions
- When performing partitioning, Krakatoa uses built-in MAXScript functions to increment the Random Seeds of specified supported particle systems and their operators.
- In order to allow users to perform arbitrary operations in addition to the automatic Random Seed incrementation, Krakatoa supports a user-defined global function Krakatoa_SeedIncrement_UserFunction() and a global variable Krakatoa_SeedIncrement_LastValue.
- By default, both the function and the global variable are undefined, but pre-declared by Krakatoa. Thus, defining and redefining the function after Krakatoa has been initialized will work as expected.
- The function can be defined by 3rd party scripts and will be called each time the seed increment function is called, thus allowing 3rd party tools to alter other aspects of the flow currently unsupported by Krakatoa.
- The function will be sent one parameter which will be the seed increment value.
- The global variable will also be set to the last increment value in case 3rd party scripts want to query the value without using the callback function method.
For example: fn Krakatoa_SeedIncrement_UserFunction theVal = format "Seed Increment: %\n" theVal --this will print the seed increment and decrement value to the Listener --each time a partition is created