User Tools

Site Tools


reference_guide:math_expression_language:functions_variables:variables_functions_mel

Global

Constants, Variables and Functions

General information about multi Threading vs Single Thread

In a particle simulation, the single thread mode and multi-threading mode refer to how the simulation is processed.

  • Single thread mode: In this mode, the simulation is processed sequentially, with all calculations being performed in a single thread of execution. This means that only one calculation is performed at a time and the simulation may be slower, especially for larger simulations.
  • Multi-threading mode: In this mode, the simulation is processed in parallel, with calculations being performed simultaneously in multiple threads of execution. This can significantly speed up the simulation, especially for larger simulations, as multiple calculations can be performed at the same time.

With the ExpressionME-L Node the mode of execution is determined by the order of the inputs, with the first input being processed in multi-threading mode and all subsequent inputs being processed in single thread mode. This means you must decide which input should be processed in multi-threading mode based on which input will be most valuable to be processed in parallel.

In addition to the order of inputs, the type of input can determine the mode in which the simulation is processed. For example:

  • If the first input is an OpenVDB grid, the expression will go through all grid Voxels in parallel.
  • If the first input is a particle group (PGroup), the expression will iterate over all particles in the group in parallel.
  • If the first input is a generator, the expression will iterate over all particle IDs generated by the generator in parallel.
  • If the first input is an object list, the expression will iterate over all vertices of all objects in the list in parallel (this is the default behavior). You can also specify the mode using a function in the expression.

Other inputs, such as scalars, vectors, or particles, will result in single calls with no parallel iterations.

Virtual ME-L Groups

ME-L groups behave similarly to thinkingParticles' own particle groups, with the exception that they do not have a hierarchy. The same particle can be in several groups. Virtual ME-L groups are accessible throughout multiple ME-L nodes, either in one or many DynamicSets. Accessing virtual ME-L Groups between multiple nodes is done via a strict naming convention. By using the identical name in every ME-L Node, the same group properties will be shared as well.

As with any Node input, when the first input is an ME-L group, the data stored within will be processed in a multi-threaded parallel manner.  

User Interface and Connector Functions

ME-L allows you to programmatically create, rename and move Input and Output connections. You may create various input types like Scalar, Vector etc…

exp_desc

This function allows you to set the name and color of the ME-L node itself.

Call:

exp_desc(in_name, in_exp_param, in_exp_param_value,....);

//set the expression name and color
exp_desc('Hello World', exp_color, 1,1,1);


//example for an Iterative call of the ME-L Node running this script

// IO Block 
   input_desc('iterations',port_scalar,port_r_integer,port_p_min,1);
/IO Block End

exp_desc('My Script', exp_iteration, 'iterations_in'); // the input sets the amount of iterations.

 

Parameters:

Parameter Description
in_name The name of the Node to be displayed in the UI (empty string will not change the name and keep current name).
in_exp_param For possible options check the exparam table below.
in_exp_param_valueThis represent the value to be set by the previous in_exp_param.

exp_param options:

Parameter Description
exp_color This is used to set/change the color of the Node in thinkingParticles. When selected, it must be followed by 3 Scalar values (R,G,B)
exp_iterationthis is used to set an amount of iterations to call the ME-L Node. This can be used as a shortcut, instead of setting up an extra Iterator Node within thinkingParticles.
This option must be followed by a string to define the name of the Scalar Input setting the amount of iterations.

input_desc

this function is used to programmatically create an input port for the ME-L node.
Note, Group inputs automatically offer a drop down list of particle groups, including a checkbox for subgroups in the Parameters Rollout section.

Call:

//create a input port
    input_desc(in_name, in_port_type, in_port_param, port_param_value,....)

//create a scalar input port
    input_desc('scalar', port_scalar);

//create a scalar input port and set the min and max and default value
    input_desc('scalar', port_scalar, port_p_min, 0, port_p_max, 10, port_p_default, 5);
    
    //create a vector input port
    input_desc('vector', port_vector);

//create a vector input port with default values
    input_desc('vector', port_vector, port_p_default, 1,1,1);

//create a pgroup input port and set use sub groups
    input_desc('group', port_group, port_p_usesub, true);

//create a scalar input with a dropdown resource this list is zero based (Item1=0)
    input_desc('scalar', port_scalar, port_r_dropdown, 'Item1,Item2,...');

//Example: create a check box
    input_desc('scalar', port_scalar, port_r_checkbox);

//Multi ME-L Node range Groups. Create a virtual ME-L group input which can not be connected, port  name is the group access name!
    input_desc('mgroup_name', port_mgroup);

//add or change the particle color for a virtual ME-L group in the viewport, this will add color swatch resource to the parameter rollout                 R G B  
    input_desc('mgroup_name', port_mgroup, port_p_color, 1,0,0);

//To clear a ME-L group before the expression is called, "pre clear" to start with an empty group
    input_desc('mgroup_name', port_mgroup, port_p_clear, true);

//create a Text Separator in the rollout
input_desc('New Parameter', port_separator);

// Create rollout menue
input_desc('New Parameter', port_separator, port_r_rollout);

Parameters:

Parameter Description
in_name The name of the input to be displayed in the UI 
in_port_type sets the port type; see table Port Types below
in_port_param port parameter (e.g. Min, Max, Default …) must be followed by a value. See table Port Parameters
in_port_param_valuemust be preceded by in_port_param, sets the value of the parameter.

 Port Types

Parameter Description
port_scalar scalar port
port_vector vector[3] port
port_particle particle port
port_group particle group port
port_mgroup create a vritual ME-L particle group that can be shared with all ME-L nodes
port_objects object list port
port_shaper shaper port
port_shapes shapes port
port_texmap texture map port
port_force force port
port_collision collision port
port_function function port
port_generator generator port
port_lights lights port
port_memory memory port
port_vdb_distance vdb distance field
port_vdb_fog vdb fog field
port_vdb_scalar vdb scalar field
port_vdb_vdata vdb vdata field
port_vdb_vector vdb vector field
port_vdb_velocity vdb velocity field
port_vdb_position vdb position field
port_vdb_alphamaskvdb alphamask field
port_separator depending on the resoruce type, this either creates a text separator in a rollout menu or it creates a separate inidivudally named rollout menu (port_r_rollout).
All following inputs will collected inside this rollout until the next rollout command appears.

Port Parameters

Parameter Description
port_p_min min value for scalar and vector inputs, scalar has one value vector three values
port_p_max max value
port_p_default default value, used when the input is not connected
port_p_usesub use sub groups for PGroup inputs
port_p_resourceresource type to use in the rollup to edit the parameter when the input is not connected. See Table Port Resource Types for possible options.
port_p_color sets a color for a Virtual ME-L Group, must be followed by a RGB value (e.g. 1,0,0)
port_p_clear clears a virtual ME-L Group, must be followed bei a TRUE value

  Port Resource Types

Parameter Description
port_r_generic this is the default, no units pure value (scalar and vector)
port_r_world world unit
port_r_object object unit (visualization is the same as world)
port_r_percent percent, only visualization, internal 100% will be converted to 1.0
port_r_angle angle in degrees, only visualization, internal converted to radians
port_r_second scalar marked as second
port_r_time max time, with frames or SMPTE or frame and ticks (Max Time Display) expression internal converted to seconds
port_r_frame integer marked as frames
port_r_integer integer
port_r_dropdowncreates a drop down menu with a list of items extracted out of a string. (Needs to be scalar input e.g. 0,1,2…)
port_r_checkboxcreates a checkbox (Scalar 0 or 1)
port_r_rgb vector marked as R,G,B
port_r_color vector will show as Color Swatch
port_r_rollout this only works with a separator port, when set a rollout menu will be created collecting all following inputs.

output_desc

This function enables the creation of output ports for the ME-L node. It is essential to understand that since the software supports multi-threading and processes data in parallel, each output port can only hold a single “final” value. Therefore, it is necessary to determine whether the output should be an average, weighted average, minimum or maximum value, using designated flags. These flags will indicate what type of output the software should produce. One output value is created per full evaluation of the ME-L script. 

Example: Lets assume the first input is a particle group with 1000 particles, then the ME-L script is evaluated 1000 times and after this, one value is available at its output port.

Call:

//create a output port
    output_desc(in_name, in_port_type, in_port_param, port_param_value,....)

//create a scalar input port
    output_desc('scalar', port_scalar); // by default, it will output the average value

//scalar output, this outputs the average of all values (can be omitted)
    output_desc('scalar', port_scalar, port_out_average);

//scalar output, sets the minimum value as output
    output_desc('scalar', port_scalar, port_out_min);

//create a scalar output, set the max as output of all values set to the scalar_out
    output_desc('scalar', port_scalar, port_out_max);

//create a vector input port
    output_desc('vector', port_vector);

/create a vector output, make a average of all vector set to the vector_out (that is also the default when no port_out parameter is set)
    output_desc('vector', port_vector, port_out_average);

//create a vector  output, set the min length vector as output of all values set to the vector_out
    output_desc('vector', port_vector, port_out_min);

//create a vector  output, set the max length vector as output of all values set to the vector_out
    output_desc('vector', port_vector, port_out_max);

//create a vector  output, set the min per vector component as output of all values set to the vector_out, vector.x = min x, vector.y = min y, vector.z = min z 
    output_desc('vector', port_vector, port_out_cmin);

//create a vector  output, set the max per vector component as output of all values set to the vector_out, vector.x = max x, vector.y = max y, vector.z = max z 
    output_desc('vector', port_vector, port_out_cmax);

Parameters:

Parameter Description
in_name The name of the ouput to be displayed in the UI 
in_port_type sets the port type; see table Port Types below
in_port_param port parameter (e.g. Min, Max, Default …) must be followed by a value. See table Port Parameters
in_port_param_valuemust be preceeded by in_port_param, sets the value of the parameter.

Port Types

Parameter Description
port_scalar scalar port
port_vector vector[3] port
port_vdb_distance vdb distance field
port_vdb_fog vdb fog field
port_vdb_scalar vdb scalar field
port_vdb_vdata vdb vdata field
port_vdb_vector vdb vector field
port_vdb_velocity vdb velocity field
port_vdb_position vdb position field
port_vdb_alphamaskvdb alphamask field

Port Parameters

Parameter Description
port_out_average calculates the average of all values
port_out_min calculates the minimum of all values
port_out_max calculates the maximum of all values
port_out_cmin calculates the average of all component values (minimum x, minum y, minimum z)
port_out_cmax calculates the average of all component values (minimum x, minum y, minimum z)
port_p_copyfrom_topo (used with VDB grids) to copy the input field data (strcuture only) to the output before executing the script
port_p_copyfrom_values(used with VDB grids) to copy the input field data (full data) to the output before executing the script

Ouput Example Script:

input_desc('pgroup',port_group);\\
output_desc('avgspeed',port_scalar,port_out_average);\\
\\
var mass = get_pdata(pid, data_mass); %%//%%get the mass of the particle\\
\\
avgspeed_out = get_pdata(pid, data_vel) * mass;  %%//%%set the speed weighted with the mass\\
avgspeed_out_avg_weight = mass;  %%//%%weight for the average creation (default is 1, when not set)

In the example above, we collect all particle velocities (with get_pdata). Then, we weight the velocities by the individual particle mass (get_pdata). the scalar_out_avg_weight variable defines the weight factor for the average velocity calculation. Heavier particles have more influence than lighter ones.

Example 2:

// io block start
input_desc('group',port_group);
input_desc('fog',port_vdb_fog);

output_desc('fog',port_vdb_fog,port_p_copyfrom_values,'fog_in'); // this is our copy from
// io block end

var psize=0;
get_pdata(pid,data_size,psize);
fog_out_wraster(1, wp, psize*0.5, 1, set_max, true);

In this example, particle data is used to transfer data into a fog field, before particle evaluation takes place. The current value is copied to the output fog field. Then, the particles are evaluated and the new fog value is set to the max value for each voxel.

Global (virtual) Memory Function

mem_desc  

This function is used to create a new named memory value, each value is visible throughout all MEL operators. If you use multiple ME-L Nodes in a thinkingParticles setup, the memory slots will be accessible throughout regardless of DynamicSet. Keep in mind; to actually publish the memory slot throughout the ME-L Nodes in tP, press the Compile button.

Note: To create 3 virtual memory slots you would use the following calls. Those memory slots will be shown (highlighted) in the ME-L editor as: value1_m, value2_m and value3_m.

mem_desc('value1', port_scalar);
mem_desc('value2', port_scalar);
mem_desc('value3', port_scalar);

To store a value in a previously created memory slot you would use the following calls:

mem_set(pid, value1_m, 1); // setting 1 as value    
mem_set(pid, value2_m, 10);// setting 10 as value
mem_set(pid, value3_m, 23);// setting 23 as value    

To read the values form the memory slots you would use the following calls:

var myvalue;
mem_get(pid, value3_m, myvalue); // myvalue will hold now 23

 

Call:

//make a scalar value
    mem_desc('name', port_scalar);

//create a scalar value with a depth of 1, the default depth is 0, 1 means two values, one value in depth (level) 0 and one in depth 1
    mem_desc('name', port_scalar, port_mem_depth, 1);

//create a scalar value and set the default value to -1, without this parameter the default value is 0
    mem_desc('name', port_scalar, port_p_default, -1);

//create a scalar value and set default value to -1 and min -1 max 10 clamp value
    mem_desc('name', port_scalar, port_p_default, -1, port_p_min, -1, port_p_max, 10);

//create a vector[3] value
    mem_desc('name', port_vector);

//create a vector value with a depth of 1, the default depth is 0, 1 means two values, one value in depth (level) 0 and one in depth 1
    mem_desc('name', port_vector, port_mem_depth, 1);

//create a vector value and set the default to value[0] = -1, value[1] = 0, value[2] = 0, with out this parameter the default values are all 0
    mem_desc('name', port_vector, port_p_default, -1, 0, 0);

//create a vector value and set the default value to -1 and min -1 max 10 clamp value
    mem_desc('name', port_scalar, port_p_default, -1, -1, -1, port_p_min, -1, -1, -1, port_p_max, 10, 10, 10);

Parameters:

Parameter Description
in_name The name of the virtual memory slot 
in_port_type port_scalar and port_vector are the only possible options 
port_mem_depthsets the amount of cells in a memory slot (depth), each memory slot can hold multiple values starting with depth 0. For example depth 1 will create the option to hold 2 values in the same memory slot (value at depth 0 and 1).
port_p_defaultsets the default value when the memory slot is accessed for the first time and no value has been set before.
port_p_min sets the minimum value, values outside min max will be clamped to this value
port_p_max sets the maximum value 

mem_set  

This function is used to set a value to a previously created memory slot.    Call:

// set a scalar memory value (in depth 0)
    mem_set(in_pid, name_m, in_scalar);   
    mem_set(in_pid, name_m, in_scalar, 0); // default is 0 anyway so can be omitted

//set a scalar memory value in depth 1
    mem_set(in_pid, name_m, in_scalar, 1);

Parameters:

Parameter Description
in_pid        particle ID to set the value from, a value of -1 indicates a global memory (independent of particle)
name_m automatically created system constant, to address the memory slot
in_scalar sets a scalar value
in_vector[3] vector to set
in_depth sets the memory depth to set, when not set the default is 0

Return

ValueDescription
0Failed
1Success

mem_get 

This function is used to get a value to a previously created memory slot. 

Call:

// set a scalar memory value (in depth 0)
    mem_get(in_pid, name_m, out_scalar);   
    mem_get(in_pid, name_m, out_scalar, 0); // default is 0 anyway so can be omitted

// get a scalar memory value in depth 1
    mem_get(in_pid, name_m, out_scalar, 1);

Parameters:

Parameter Description
in_pid        particle ID to get the value from, a value of -1 indicates a global memory (independent of particle)
name_m automatically created system constant, to address the memory slot
out_scalar gets a scalar value
out_vector[3] vector to get
in_depth set the memory depth to get, when not set the default is 0

Return

ValueDescription
0Failed
1Success

Constants and Variables

Constant Description
t Current animation time in seconds.
dt Delta time from one sub-sample to the next in seconds.
valueoff Value used to turn off a value (e.g. removing a Voxel).
frame_ Current animation time in frames
frame_t_ Current frame in subframe notation e.g. “Frame 10.2”
frame_dt_ Current frame delta time 
frame_changed_A boolean; 1: when a frame changed 0 when no frame change is happening
sim_start_ This boolean output toggeles true when the simulation resets (start), while running it is set to 0.
sim_debug_ Boolean, 1: Debug window is open 0:Debug Window is closed
fps_ holds the current frames per second settings of 3ds Max.

The ExpressionVDB Node uses a strict order methodology, the first input determines the type of object that the expression will iterate over. If the first input is a group of particles, for example, the expression will execute for each particle in the group in parallel.

Variable Description
pid the global particle id for the particle being evaluated by the expression
vp The particle's position in Voxel Space. vp[0] represents the x coordinate, vp[1] represents the y coordinate, and vp[2] represents the z coordinate.
op The particle's or Voxel's position in object (particle) space.
wp The particle's or Voxel's world position
bp Vector position relative to bounding box space, with x, y, and z normalized to values between 0 and 1. 0,0,0 represents the bottom left corner.
cbp Vector position in the center of the bounding box space, with x, y, and z values of 0 representing the center. Positive values extend to 1 in each dimension, and negative values extend to -1 in each dimension.
   
nid_ In a particle simulation, the variables nid_ and id_ are available during certain types of iterations, such as when iterating over a particle group or a volume represented by an OpenVDB grid.

The number of iterations. For example, if the first input is a particle group with 100 particles, nid_ will be 100. If the first input is an OpenVDB grid, nid_ will be the number of voxels in the grid to iterate through.
id_ The iteration index, or the current call counter. For example, if the first input is a particle group with 100 particles and id_ is 50, this indicates that the current iteration is the 50th iteration out of 100 total iterations.
oid_ Only valid when first input is ObjectList. Current evaluated object ID 
fid_ Only valid when first input is ObjectList. Current evaluated face ID
fbc_ Only valid when first input is ObjectList. Current Barycentric Coordinates of evaluated object
vid_ Only valid when first input is ObjectList. Current evaluated vertex ID
eid_ Edge ID, Only valid when first input is ObjectList. Current evaluated edges ID
erpos_Relativeposition on edge (0-1), only valid when first input is ObjectList. Current evaluated edge position.

Perlin Noise and Random Number Functions

noise(x, y, z)
3D Perlin noise function. x, y, and z represent 3D coordinates.

noise(x, y)
2D Perlin noise function. x and y represent 2D coordinates.

ncellular(x, y, z)
3D cellular noise function. x, y, and z represent 3D coordinates.

nchip(x, y, z)
3D cellular noise function in chip mode. x, y, and z represent 3D coordinates.

nvoronoi(x, y, z)
3D Voronoi noise function. x, y, and z represent 3D coordinates.

nturbulence(position_in, size_in, shift_in, frequency_in, turb_out)
This function computes a 3D vector turbulence field based on the specified parameters. The inputs include the position_in, size_in, shift_in, and frequency_in, each contributing to the generation of turbulence. The resulting turbulence vector is stored in the turb_out variable. By leveraging this function, users can introduce controlled perturbations into their simulations, effectively simulating turbulent behaviors within three-dimensional space. The function serves as a valuable tool for achieving realistic and dynamic effects in visual simulations by providing a flexible means to manipulate the turbulence characteristics.

Parameters:

Parameter Description
position_in vector[3] input position
size_in vector[3] noise structure size factor
shift_in vector[3] noise structure position shift
frequency_in scalar automatic time noise shift frequency
turb_out vector[3] turbulence value out, in range of -1 to 1 for x,y,z

rndseed(s) 
Sets the random seed.

rnd01()
Returns a random value between 0.0 and 1.0.

rnd11()
Returns a random value between -1.0 and 1.0.

rndxx(x, y)
Returns a random value between x and y.

Particle Based Random Number Generator Functions

prnd01()
Per particle random function that returns a repeatable series of random values between 0.0 and 1.0.

prnd11() 
Per particle random function that returns a repeatable series of random values between -1.0 and 1.0.

prndxx()
Per particle random function that returns a repeatable series of random values between a specified range.

nrndseed(in_generator_id, in_seed)
Initializes the random generator with a specified seed. The input generator id can be 0 or 1, with 0 being the standard generator and 1 being a more regular generator. The input seed is a random seed value. Returns 0 on failure and 1 on success.

nrnd01(in_generator_id) 
Returns a random value between 0.0 and 1.0 using the specified generator id (0 or 1).

pnrnd01(in_generator_id)
Per particle variant of the nrnd01 function, returns a repeatable series of random values between 0.0 and 1.0 using the specified generator id (0 or 1).

nrnd11(in_generator_id)
Returns a random value between -1.0 and 1.0 using the specified generator id (0 or 1).

pnrnd11(in_generator_id)
Per particle variant of the nrnd11 function, returns a repeatable series of random values between -1.0 and 1.0 using the specified generator id (0 or 1).

nrndxx(in_generator_id, in_from_value, in_to_value)
Returns a random value between a specified range (in_from_value and in_to_value) using the specified generator id (0 or 1).

pnrndxx(in_generator_id,in_from_value,in_to_value) 
Per particle variant of the nrndxx function, returns a repeatable series of random values between a specified range (in_from_value and in_to_value) using the specified generator id (0 or 1).

System & Debug Functions

dprint

Prints information or data to the standard thinkingParticles Debug window. The window must be open for the function to work.

Call:

dprint(string,string/vector/scalar, ... up to 8 values);

dprint(color{3}, string,string/vector/scalar, ... up to 8 values); %%//%% RGB color of text

dprint(color{3}); // sets the RGB color of text for the next print commands

dprint(scalar); // boolean 1: turns dprint on (default), 0: turns dprint off

dprint(scalar,color[3]); // boolean 1: turns dprint on (default), 0: turns dprint off. And RGB color!

Formatting options:

Parameter Description
$w calculates generic units into world units, with the corresponding unit characters
$a angle, calculates radian to degree, with a “°” postfix
$p percent, converts any 0-1 value to 0-100 and adds a “%” postfix
$f frames, values will be shown with a “F” postfix
$s second, values will be shown with a “sec.” postfix
$c color, if vector values will postfix with “R” “G” “B”, when scalar a “V” indicates Value

Return: 1: when the function was successful, 0: when the function did not print out something (e.g debug window closed)

Example:
Print debug information

dprint('hello world'); // prints out Hello World

dprint('Size: ',7); // prints out "Size: 7"

dprint('World Position: ', wp, 'Time: ', t); // prints out "World Position: v[0}= 1 v[1}= 4 v[2}= -2 Time: 1.2"

var red[3] = {1,0,0}; // RGB

dprint(red,'This text is in RED'); // this prints out in red color: "This text is in RED"

dprint('Position$w', pos[3]); // shows the position value in world scale units e.g [ 2.54mm # 22mm # 78mm ]

dprint('$c',color[3]); // shows the value as RGB e.g [ 0.54R # 0.22G # 0.78B ]



dmarker

The dmarker function introduces a dynamic marker into the 3ds Max viewport, allowing users to enhance visualization with selectable color, shape and customizable lifespan (stayframes).
This function empowers users to dynamically visualize specific points in the 3ds Max viewport, adding a layer of clarity and precision to the overall visualization process.

Call:

 dmarker(type_in, worldposition_in, color_in or intensity_in, stayframes_in)

Parameters

Parameter Description
type_in scalar type value, see table Marker Type below
worldposition_in vector[3] position of the marker
color_in vector[3] color of the marker
intensity_in or a scalar grayscale value between 0-1
stayframes_in frames how long the marker will visible

Marker Type (style)

Type Description
0 Ticks
1 Dot1
2 Dot2
3 Dot3
4 Dot4
5 Dot5
6 Dot6
7 Dot7

Example:

// create a ticks marker in yellow
var color[3]= {1,1,0};// Yellow
var pos[3]= {0,0,50}; //Place 50 above ground

dmarker(0, pos, color, 30); // Keep the marker visible for 30 frames

// Place a marker at an exact particle position (using global variable wp)
dmarker(0, wp, color, 0); // Keep the marker visible for one frame

dline

This function introduces a streamlined approach to draw lines in the 3ds Max viewport, offering flexibility in type, color, and duration.

Call:

 
 dline(type_in, color_in or intensity_in, stayframe_in, worldposion_in, nextworldposion_in, ...)
 

Parameters

Parameter Description
type_in scalar type value see table Line Types below
color_in vector[3] color of the line
intensity_in or a scalar grayscale value between 0-1
stayframes_in frames how long the line will visible
worldposition_in vector[3] line start world position
nextworldposion_in vector[3] comma separated list of positions to create the line

Line Types

Type Description
0Polyline
1Closed Polyline connected end points

Example:

 
// create a line from origin to Z-Up position
var pos_o[3]={0,0,0}; // origin
var pos_up[3]={0,0,50}; // Z-up end point
var color[3]={0,0,1}; // blue color

dline(0, color, 0, pos_o, pos_up); // draw the line form 0,0,0 to 0,0,50
 
 

dtext

This function empowers users to display text dynamically in the 3ds Max viewport, offering versatile options for color, size, and content.

Call:

 
 dtext(type_in, worldposition_in, color_in, textsize_in, stayframes_in, string scalar or string_in, ...) 
 

Parameters:

Parameter Description
type_in scalar text type, for now type 0
worldposition_in vector[3] denoting the world position for text display.
color_in vector[3] for a color or scalar for a grayscale value
textsize_in scalar 0-10 were size 1.0 is default, any value acts as a multiplier for the size (Max 2023 and up)
stayframes_in frames to stay in the viewport
string_in string to draw (can combined with a format character for the nex value)
scalar_in scalar value to draw
vector_in vector with any length, to draw
 
// draw the scalar length value formatted to world units, 
// internally, 3ds Max is always using generic units
var pos[3];
var col[3];
var len;
	
dtext(0, pos, col, 2, 0, 'Length$w', len)
  

Dedicated  Helper  Functions

lowhighcut(v, low, high)
Converts the range between low and high to a range between 0.0 and 1.0.

ndistance(vector pos1, vector pos2, norm_radius)
Returns the distance between pos1 and pos2, normalized by dividing by norm_radius.

distance(vector pos1, vector pos2)
Returns the distance between pos1 and pos2.

dir_length(invector, outdirection)
Calculates the length of the input vector and stores the resulting direction in outdirection. This returns a normalized vector with a length of 1. This factually represents a normalize vector function.

sqrdistance(vector pos1, vectorpos2)
Returns the squared distance between pos1 and pos2.

Note: Positions can be 1D, 2D, 3D, or higher-dimensional. For example:

  • pos1[1] is 1D
  • pos1[2] is 2D
  • pos1[3] is 3D

Vector Functions

length_(vector_in)
calculates the length of a given vector (vector_in).  √(x*x+y*y+z*z)

sqr_length_(vector_in)
calculates the length of a vector as a  square of its length. (x*x+y*y+z*z)

angle_axis_rotate(in_angle, in_axis[3], in_out_vector[3]) Rotates a vector around a specified axis by a specified angle (in radian (use deg2rad() to specify in degrees). The input vector is modified and returned.

angle_axis_rotate(in_angle, in_axis[3], in_vector[3], out_vector[3]) Rotates a vector around a specified axis by a specified angle (use deg2rad() to specify in degrees). The input vector is not modified and the rotated vector is returned.

dir_variation(in_angle, in_out_vector[3]) Randomly varies a vector by a specified angle (use deg2rad() to specify in degrees). The input vector is modified and returned.

dir_variation(in_angle, in_vector[3], out_vector[3]) Randomly varies a vector by a specified angle (use deg2rad() to specify in degrees). The input vector is not modified and the varied vector is returned.

dir_variation(in_angle1, in_angle1, in_out_vector[3]) Randomly varies a vector between 2 angles (min and max) by a specified amount (use deg2rad() to specify in degrees). The input vector is modified and returned.

dir_variation(in_angle1, in_angle2, in_vector[3], out_vector[3]) Randomly varies a vector between 2 angles by a specified amount (use deg2rad() to specify in degrees). The input vector is not modified and the varied vector is returned.

Note: The input angle parameter is the angle of variation or rotation in radians. The input axis parameter is a 3-element array representing the axis of rotation. The input/output vector parameters are 3-element arrays representing the vectors to be rotated or varied. 

pos_variation(in_distance, in_out_vector[3]) Randomly varies a position by a specified distance. The input vector is modified and returned.

pos_variation(in_distance, in_vector[3], out_vector[3]) Randomly varies a vector by a specified distance. The input vector is not modified and the varied vector is returned.

crossprod(in_vector1[3], in_vector2[3], out_vector[3]) Calculates the cross product between 2 vectors. The Result is returned in the out_vector. Basic vector math function :)

Return: The functions returns 0 on failure and 1 on success.`

slerp(in_t_scalar, in_to_vector[3], in_out_from_vector[3])
slerp(in_t_scalar, in_to_vector[3], in_from_vector[3], out_vector[3])
These two functions facilitate Spherical Linear Interpolation, where rotation occurs from the “from vector” to the “to vector” with a transition weight “t,” where “t” ranges between 0 and 1. A value of 1 signifies the utilization of 100% of the “to vector.”
The second variation of this function not only performs the Spherical Linear Interpolation but also writes the interpolated vector (result) into a separate variable, enhancing flexibility and control in your scripting endeavors. These additions to the ME-L scripting language expand the toolkit for 3D artists, providing precise control over rotations and enabling the creation of dynamic and sophisticated visual effects.

cgradient (min_in, vlaue_in, max_in, color_in, …., color_out)
Interpolates a color between two values from a list of colors. This function takes parameters including min_in (scalar minimum value), value_in (scalar value), max_in (scalar maximum value), color_in (a comma-separated list of vector[3] colors), and outputs the interpolated color in color_out. The resulting color is determined based on the scalar value relative to the specified minimum and maximum values, creating a smooth color transition within the defined color range.

Parameters:

Parameter Description
min_in scalar minimum value
value_in scalar value
max_in scalar maximum value
color_in vector[3] color, comma separated list of colors
color_out vector[3] interpolated color, value ⇐ min returns first color and value >=max returns last color

 

Rate Function

rate(in_rate_per_second)
Returns a constant rate, used for generating particles at a specified rate per second. The internal time and delta time are used.

rate(in_rate_per_secund, in_time, in_delta_time)
Returns a constant rate, used for generating particles at a specified rate per second. The input time and delta time are used instead of the internal values.

Parameters:

Parameter Description
in_rate_per_second The rate to generate particles per second.
in_time (optional) The current time.
in_delta_time (optional)The delta time from one sub-sample to the next.

Return: The function returns the rate between time - delta_time and time. The sum of all rates in one second should equal the specified rate per second (in_rate_per_secound).

Example:
To create 50 particles per second, the following code can be used:

var born;

if(born = rate(50))
{
  for(var i = 0; i < born; i+=1)
  {
   group_in_create(pos, vel);
  }
}

get_pdata 

retrieves data for a specific particle id. The data can either be returned as a direct return value or supplied variable in the call itself.

Call Example:

get_pdata(pid, data_type, ret_value, optional dt) // return via ret_value

return = get_pdata(pid, data_type) %%//%% Direct Return Mode

// use transformation calls
// transform world to particle
get_pdata(pid, data_ptransform, world2object, in_point[3], out_point[3]);
get_pdata(pid, data_ptransform, world2object, in_out_point[3]); // return to the same variable

//transform a vector without scale and translation, only the rotation is being computed
//the vector keeps its length, there is a direction change, only
get_pdata(pid_in, data_dtransform, object2world, vector_in_out); 
get_pdata(pid_in, data_dtransform, object2world, vector_in, vector_out); 

//special transformation for normals, no translation is being computed
//a normal is orthogonal to a face therefore a special transformation to keep its direction, is needed
get_pdata(pid_in, data_ntransform, object2world, vector_in_out); 
get_pdata(pid_in, data_ntransform, object2world, vector_in, vector_out); 

//transform a point without scale but with translation and rotation
//the vector keeps its length, there is a direction change, only
get_pdata(pid_in, data_trtransform, object2world, vector_in_out); 
get_pdata(pid_in, data_trtransform, object2world, vector_in, vector_out); 

This function takes the following parameters:

Parameter Description
pid the particle id to retrieve data for
data_type the type of data to retrieve (see full liste HERE)
ret_value the variable to store the data in, either a scalar or a vector[3]
dt (optional)the delta time for position or alignment; the position will be shifted by ret_value = position + velocity*dt, or the alignment will be shifted by ret_value = alignment + spin*dt

Return -
The function returns a scalar value, with 0 indicating no access to the particle (in which case the ret_value will not be set) and 1 indicating success (in which case the ret_value will be set to the data).
When this function is called in a direct return mode (return is assigned to a variable) the actual value will be stored/returned.

Code Example:
// get the mass of particle with pid 10
var mass = 1;
get_pdata(10, data_mass, mass);

// get the color data channel 1 of the local iterate particle
var color[3];
get_pdata(pid, data_dchan+1, color);

// get the speed of the particle
var speed = 0;%%//%%no vector only a scalar the function evaluate the velocity vector length for a scalar return value\\
get_pdata(pid, data_vel, speed);

// get the velocity of the particle
var velocity[3];
get_pdata(pid, data_vel, velocity);

// Direct Mode method
// get the velocity of the particle
var speed;
speed=get_pdata(pid, data_vel);


if(get_pdata(pid,data_genter))
{
  // Do something when particle enters the group
}

set_pdata

used to set standard particle data for a specific particle id

Call Example: <coce> set_pdata(pid, data_type, value) </code>      

Parameter Description
pid specifies the particle id
data_typedefines the data type (see full liste HERE)
value the variable to set data, a scalar or a vector[3]
dt optional delta time for position or alignment, the position will shift ret_value = position + velosity*dt or the alignment ret_value = alignment + spin*dt

Return: 
(Scalar) 0 indicates no access to the particle (ret_value will be not valid), 1 indicates success and ret_value is set to the requested data

Examples:

// Set the velocity of the particle with pid 10 to 0 
vel = [0, 0, 0] set_pdata(10, 'data_vel', vel) 

// Set the color red into the data channel 1 of the local iterate particle color = [1, 0, 0] set_pdata(pid, 'data_dchan+1', color)

 

set_palignment

This function is used to align the specified axis of a particle with a given position, direction, or rotation.

Call Example:

// align the particle x axis to world position
set_palignment(pid_in, x_axis_, align_topos, position_in, optional laziness_in)

//align the particle y axis to world position
set_palignment(pid_in, y_axis_, align_topos, position_in, optional laziness_in)

//align the particle z axis to world  position
set_palignment(pid_in, z_axis_, align_topos, position_in, optional laziness_in)    

//align the particle x axis to world direction    
set_palignment(pid_in, x_axis_, align_dir, direction_in, optional laziness_in)

//align the particle y axis to world direction
set_palignment(pid_in, y_axis_, align_dir, direction_in, optional laziness_in)

//align the particle z axis to world direction
set_palignment(pid_in, z_axis_, align_dir, direction_in, optional  laziness_in)

//align the particle x axis to travel direction (velocity direction)
set_palignment(pid_in, x_axis_, align_travel, optional laziness_in)

// align the particle y axis to travel direction 
set_palignment(pid_in, y_axis_, align_travel, optional laziness_in)

//align the particle z axis to travel direction
set_palignment(pid_in, z_axis_, align_travel, optional laziness_in)

// rotate around the x axis amount of rotation in radians use deg2rad() to use degrees 
set_palignment(pid_in, x_axis_, align_rotate, radians_in)

// rotate around the y axis amount of rotation in radians
set_palignment(pid_in, y_axis_, align_rotate, radians_in)

// rotate around the z axis amount of rotation in radians
set_palignment(pid_in, z_axis_, align_rotate, radians_in)

// rotate around a user axis amount of rotation in radians
set_palignment(pid_in, user_axis_, user_axis_in, align_rotate, radians_in)

//copy the alignment from the in_from_pid particle
    set_palignment(in_pid, from_pid_axis_, in_from_pid);

Parameters

Parameter Type Description
pid_in Integer The particle id to affect
axis_ String The axis of the particle to affect (see axis types)
align_ String The method to align the particle (see align types)
position_in Vector[3]World position (used for align_topos)
direction_inVector[3]World direction (used for align_dir)
laziness_in Scalar Scalar value to delay the alignment
radians_in Scalar Rotation value in radians (used for align_rotate)
user_axis_inVector[3]User-defined axis (used for user_axis_)

Axis Types

Axis Type Description
x_axis_ X axis of the particle
y_axis_ Y axis of the particle
z_axis_ Z axis of the particle
inv_x_axis_ Inverse X axis
inv_y_axis_ Inverse Y axis
inv_z_axis_ Inverse Z axis
user_axis_ User-defined axis
from_pid_axis_Copy all axis from given PID (particle)

Align Types

Align Type Description
align_topos Align to world position
align_dir Align to world direction
align_travel Align to travel direction (velocity direction)
align_rotationRotate around axis

Return

ValueDescription
0Failed
1Success

 

Particle Shape Access

To access and work with mesh based functions, the function get_pdata must be first called to check if a particle has a mesh attached to it or not. To initiate this check do the following:

get_pdata(in_pid, data_shape)

When this function returns a value of 1 the probed particle (in_pid) holds mesh data.

 

pshape_surface_point

Used to get a point on the surface of the mesh.

Calls:

pshape_surface_point(in_surface_relative) \\
pshape_surface_point(in_surface_relative, in_mtl_id)

Parameters:

Parameter Description
in_surface_relativeA scalar surface position relative between 0-1.
in_mtl_id Only on these material id.

Output:

Return Description
scalar0: failed, 1: success

pshape_closest_point

Get the closest point on the pshape surface to the specified position in world space.

Calls:

pshape_closest_point(pos)
pshape_closest_point(pos, mtl_id)

 

Parameter Type Description
pos vector[3]World position from where to find the closest point
mtl_idinteger Restrict the function to the specified material id

Output:

Return Description
scalar0: failed, 1: success

 

pshape_point

This function is used to get surface point data.
Note point data can only be accessed after the function surface_point or closest_point return with a value of 1.

Calls:

pshape_point(point_data, out_scalar)\\
pshape_point(point_data, out_vector[3])\\
pshape_point(point_uvw, in_chan, out_uvw_vector[3])

Parameters:

Parameter Description
point_data Point data to get.
out_scalar Scalar for scalar data.
out_vector Vector for vector data.
point_uvw The point UVW.
in_chan The channel.
out_uvw_vectorThe UVW vector.

Point Data:

Point Data Description
point_pos The world space position of the point.  (scalar)
point_opos The object space position of the point. (vector)
point_norm The world space normal of the point. (vector)
point_onorm The object space normal of the point. (vector)
point_gnorm The geometry normal of the point. (vector)
point_ognormThe object space geometry normal of the point. (vector)
point_uvw The UVW coordinates of the point. (vector)
point_vel The velocity of the point. (vector)
point_pid The particle id belonging to the position/point, if the object is a particle. Otherwise, -1.
point_fid The face id of the point. (scalar)
point_dist The distance from the point to the surface of the object. (vector)
point_dir The direction from the point to the surface of the object. (vector)
point_mtlid The material id of the point. (scalar)
point_color The color of the point. (vector)
point_bc The barycentric coordinates of the point/position. (vector)
point_centerThe world coordinate center of the object/mesh (vector)

Output:

Return Description
scalar0: failed, 1: success

 

Code Example: 

// Get 10 random points on the mesh of the current particle

var pos[3];

if(get_pdata(pid, data_shape))
{
  for(var i = 0; i < 10; i +=1)
  {
   if(pshape_surface_point(rnd01()))
   {
     pshape_point(point_pos, pos);
               
         ...do anything with the position, e.g. create a new particle\\
   };
  }
};

 

pshape_geom

The pshape_geom function allows you to access geometry specific data of a mesh. There are several variations of this function, depending on the type of data you want to retrieve and the format of the output. Check out the possible function calls shown below. Alos note, new functionalities allow users to manage vertex colors more effectively, aligning with 3ds Max conventions. Additionally, a method has been incorporated to access vertex colors in a manner consistent with 3ds Max, addressing the specific way colors are stored in Vertex Color Channels. Explore the expanded capabilities of pshape_geom to refine your control over mesh-specific data retrieval.

Calls:

pshape_geom(geom_data, out_scalar)

pshape_geom(geom_data, out_vector)

pshape_geom(face_data, in_face_id, out_scalar)
pshape_geom(face_data, in_face_id, out_vector)    
pshape_geom(vert_data, in_vertex_id, out_vector) 

// get one of the three face vertex positions
// vert have the range 0-2    
pshape_geom(face_vpos, face_id, vert, vertex_pos_out)

// get the interpolated position on a face
// bc are the barycentric oordinates of the position on the face
pshape_geom(face_pos, face_id, bc, pos[3]_out)

//get the interpolated normal on a face
//bc are the barycentric oordinates of the position on the face
pshape_geom(face_norm, face_id, bc, norm[3]_out)
    
// query face selection state returns 0 if not selected 1 if selected.
return = pshape_geom(face_selected, face_id)

pshape_geom(tface_data, in_map_channnel,in_tface_id, out_scalar)

pshape_geom(tface_data, in_map_channnel, in_tface_id, out_vector)
pshape_geom(tface_data, in_map_channnel, in_tface_id, in_barycentric, out_vector)
pshape_geom(tface_uvw, in_map_channnel, in_tface_id, in_barycentric, out_uvw)

pshape_geom(tvert_data, in_map_channel, in_tvertex_id, out_uvw)

pshape_geom(edge_data, edge_id, scalar_out)
pshape_geom(edge_data, edge_id, vector_out)

//this is the velocity of the particle
pshape_geom(geom_vel, out_velocity[3]);        
    
//this is the velocity on the world position including spin (rotation) of the particle
pshape_in_geom(geom_vel, in_world_position[3], out_velocity[3]); 


//get the two edge face index
//the index range is 0 >= id < nfaces, value of -1 mean undefined
pshape_geom(edge_fid, edge_id, vector[2]_out)

//get the two edge vertex index
//the index range is 0 >= id < nverts
pshape_geom(edge_vid, edge_id, vector[2]_out)

//is edge selected, returns 0 if not selected 1 if selected.
return = pshape_geom(edge_selected, edge_id) 
    
//is edge visible, returns 0 if not visible 1 if visible.
return = pshape_geom(edge_visible, edge_id) 
  
//is edge open, returns 0 if not open1 if open.
return = pshape_geom(edge_open, edge_id) 

//the supplied material id, defines the open edge status (a change of mat id = open)
//mtl_id, range 1 - max material id of 3ds Max.
return = pshape_geom(edge_open, edge_id, mtl_id) 

//get an interpolated position on the edge
//rel_pos, range between 0 - 1
pshape_geom(edge_pos, edge_id, rel_pos, pos[3]_out)


//get an interpolated normal on the edge
//rel_pos, range between 0 - 1
pshape_geom(edge_norm, edge_id, rel_pos, norm[3]_out

// copy particle alignment from this particle to another particle
pshape_geom(geom_palign,in_to_pid); 

// get the number of edges which share the vertex with the id "vid" 
pshape_geom(vert_nedges, vid); 

//get the real edge id from the vertex
pshape_geom(vert_edge, vid, i); 

// get the number of faces sharing the vertex with the id "vid" 
pshape_geom(vert_nfaces, vid); 

//get the real face id from the vertex
pshape_geom(vert_face, vid, i); 

//to get the face vertex color
pshape_geom(face_vcol, in_fid, in_vid, out_color[3])

//interpolated vertex color on the face
pshape_geom(face_vcol_bz, in_fid, in_bc[3], out_color[3])

//get the vertex color of the vertex, this represents the average across all faces connected to this vertex
pshape_geom(vert_vcol, in_vid, color_out[3])

// get the vertex color of the vertex, get from all the faces the vertex color connected 
// to the vertex  and returns the average
pshape_geom(vert_vcol, in_vid, color_out[3])

// you can use any vertex color channel by specifying it as an argument
// 3ds Max supports channles 0-99, thinkingParticles uses channel 0 for original object coordinates (3D-UVW Texture).
pshape_geom(vert_vcol, in_vid, map_channel_in, color_out[3])

Function Call for Geom Data Type:

parameter description
geom_data For information about geom_data click HERE
out_scalarused to get scalar values
out_vectorused to get vector[3] values
in_to_pid the particle ID recieving the alignment information

Function Call for Face Data

parameter description
face_data For information about face_data click HERE
in_face_idfrom a specific face ID
in_map_channelused set Color UWV Vertex Channel
out_scalarused to get scalar values
out_vectorused to get vector[3] values

Function Call for Texture Face Data

parameter description
tface_data For information about tface_data click HERE
in_tface_id from a specific texture face ID
in_map_channelform a specific mapping channel
out_scalar used to get scalar values
out_vector used to get vector[3] values

Function Call for Vertex Data

parameter description
vert_data For information about vert_data click HERE
in_vertex_id from a specific vertex ID
in_map_channelfrom a specific mapping channel
out_vector used to get vector[3] values

 

Function Call for Texture Vertex Data

parameter description
tvert_data For information about vert_data click HERE
in_tvertex_id from a specific texture vertex ID
in_map_channelfrom a specific mapping channel
out_vector used to get vector[3] values

Function Call for Edge Data

parameter description
edge_data For information about edge_data click HERE
edge_id from a specific edge ID
out_scalarused to get a scalar value
out_vectorused to get vector[2] or vector[3] values (see samples above)

Output:

Return Description
scalar0: failed, 1: success

Example:
This code example shows how to get all face centers of a mesh.

    var nfaces;
    var center[3];
        
        if(get_pdata(pid, data_shape))
        {
            if(pshape_geom(geom_nfaces, nfaces))
            {
                for(var i = 0; i < nfaces; i += 1)
                {
                    pshape_geom(face_center, i, center);                  
                  ...do anything\\
                }
            };    
        };

pshape_geom_set

This function sets particle shape mesh data. It can be used to access and interact with face centers, material ID, vertex positions, and vertex indices of a face, as well as the position, color, and UVW coordinates of a vertex.

Calls:

// Geom Initialize Vertex Color

     // initializes the vertex color for a a specified vertex color channel (UVW Channel 0-99). Default 0.
     pshape_geom_set(geom_init_vcol, uvw_channel_in,  fcol_in[3]);
     pshape_geom_set(geom_init_vcol, uvw_channel_in); // uses color 0,0,0 (Black)
     pshape_geom_set(geom_init_vcol ); // uses uvw channel 0 and color 0,0,0 (Black)
     pshape_geom_set(geom_init_vcol, fcol_in[3]); // uses uvw channel 0 

//face data

    //set the world space center of a face, this automatically changes the 3 vertex positions
    pshape_geom_set(face_center, face_id_in, center[3]_in)
    pshape_geom_set(face_ocenter, face_id_in, center[3]_in) //the same in object space
    
    //set the face material id
    pshape_geom_set(face_mtlid, face_id, mtilid_in)
  
    //set one of the three vertex position from the face, vid_in = 0,1,2
    pshape_geom_set(face_vpos, face_id_in, vid_in, position[3]_in)
    pshape_geom_set(face_ovpos, face_id_in, vid_in, position[3]_in) //in object space     

    //set the three vertex index's from the face
    pshape_geom_set(face_vid, face_id_in, vid[3]_in)

//vertex data
    
    //set the world space position of a vertex
    pshape_geom_set(vert_pos  , vert_id_in, position[3]_in)
    pshape_geom_set(vert_opos, vert_id_in, position[3]_in) //the same in object space
    
    //set the vertex color
    pshape_geom_set(vert_col  , vert_id_in, color[3]_in)     

//texture face data

    //set one of the three texture vertex uvw from the texture face, vid_in = 0,1,2
    pshape_geom_set(tface_vpos, face_id_in, vid_in, uvw[3]_in)
    
    //set the three vertex index's from the texture face
    pshape_geom_set(tface_vid, face_id_in, vid[3]_in)

//texture vertex data
    
    //set the texture vertex uvw, chan_id is the mapping channel id 0 - 99
    pshape_geom_set(tvert_uvw, tvert_id_in, chan_id_in, uvw[3]_in)


//Set Individual Vertex Colors

	//set each of the three vertex colors of a face
	pshape_geom_set(face_vcol, in_fid, in_vid, in_color[3])

        //extrapolate vertex color on the face
	pshape_geom_set(face_vcol_bc, in_fid, in_bc[3], in_color[3])

        //set the vertex channel color(selected by vertex ID; in_vid), all connected faces to this vertex will receive the 
        interpolated color.
	pshape_geom(vert_vcol, in_vid, in_color[3])

Function for Geom Data Types

parameter description
geom_init_vcol initialize a vertex color channel 

Function Call for Face Data

parameter description
face_data used to set face data 
in_face_idfrom a specific face ID
in_scalar used to set scalar values
in_vector used to set vector[3] values

face_data Types:

Data Type Description
face_mtlid The material ID of a specific face.
face_center The center of a specific face.
face_ocenter the face center in Object Space
face_vid The vertex IDs of a specific face.
face_vpos The positions of each of the three vertices (0,1,2) of a specific face.
face_ovpos The positions of the vertices of a specific face in Object Space

Function Call for Texture Face Data

parameter description
tface_data used to set texture face data 
in_tface_id from a specific texture face ID
in_map_channelform a specific mapping channel
in_scalar used to set scalar values
in_vector used to set vector[3] values

tface_data Types

Data Type Description
tface_vpos The texture vertex UVW coordinate
tface_vid The three texture vertex IDs (Vector)

Function Call for Vertex Data

parameter description
vert_data used to set vertex data 
in_vertex_id from a specific vertex ID
in_map_channelform a specific mapping channel
in_vector used to set vector[3] values

vert_data Types:

Data Type Description
vert_pos The position of a specific vertex.
vert_opos The vertex position in Object Space
vert_col The Vertex Color

tvert_data Types:

Data Type Description
tvert_uvw Sets the UVW for a specific channel and texture vertex id

Output:

Return Description
scalar0: failed, 1: success

pshape_edge_point

Get a point on the pshape edges at the specified relative position along the edge's length between 0-1

Calls:

pshape_closest_point(pos)
pshape_closest_point(pos, mtl_id)

 

Parameter Type Description
edgelength_relativescalar Edge's position relative between 0-1 along the edge's length
mtl_id integerSpecify a material ID to restrict face edges to this material id

Output:

Return Description
scalar0: failed, 1: success

Particle Reference Access

Here we describe workinh with particle references. Please note, this section is just for “readability and ease of use” as there are functions are no special functions to handle references. They are the same get_padata and set_pdatafunctions as described before.

get_pdata

Retrieves reference data from a particle

Calls:

get_pdata(in_pid, data_type, out_value)
get_pdata(in_pid, data_type, in_ref_id, out_value)

Parameters:

Name Description
in_pid The particle id to get the data from.
data_typeThe type of data to retrieve. See the data_type table below for possible values.
out_valueThe value to store the retrieved data.
in_ref_idThe reference id. This parameter is only used when data_type is data_ref_from or data_ref_to.

data_type values:

Value Description
data_nrefs Get the number of “from” and “to” references.
data_nrefs_fromGet the number of “from” references.
data_nrefs_to Get the number of “to” references.
data_ref_from Get the reference particle id (from pid to this particle).
data_ref_to Get the reference particle id (to pid from this particle).

Output:

Return Description
scalar0: failed, 1: success

set_pdata

Sets reference data for a particle

Calls:

set_pdata(in_pid, data_type, in_pid_to_set)
set_pdata(in_pid, data_type, usage_type, in_ref_id)

Parameters:

Name Description
in_pid The particle id to set the data.
data_type The type of data to set. See the data_type table below for possible values.
in_pid_to_setThe particle id to set a reference to or from. This parameter is only used when usage_type is usage_set.
usage_type The type of operation to perform. See the usage_type table below for possible values.
in_ref_id The reference id. This parameter is only used when usage_type is usage_unset.

data_type values:

Value Description
data_ref_fromSet a reference from in_pid to in_pid_to_set.
data_ref_to Set a reference to in_pid from in_pid_to_set.

usage_type values:

Value Description
usage_set Set a reference.
usage_unsetUnset the n-th reference. If in_ref_id is less than zero, all references will be unset.

Output:

Return Description
scalar0: failed, 1: success

Example 1:

 // create 20 particles and set references to them

var ppos1[3];
var pvel1[3];
        for(var i = 0; i < 20; i += 1)
        {
            pid1 = group2_create(ppos1, ppvel1);
            if(pid1 >= 0)
            {
                // set a reference from the current pid to the new particle pid1
                set_pdata(pid, data_ref_from, pid1); // or set_pdata(pid, data_ref_from, usage_set, pid1);
            };
        };

Example 2:

// Go through all "FROM" references

var nrefs;
var pid1;

get_pdata(pid, data_nrefs_from, nrefs);
       for(var i = 0; i < nrefs; i += 1)
        {
            if(get_pdata(pid, data_ref_from, i, pid1))
            {
                ..... do anything with pid1 the to particle    
                        
            }
        } 

Flag Functions    

The following functions are used to store within one scalar a flag field with a maximum of 32-Bit. Flags are memory efficient methods to control program flow.

Example: You can use one scalar to switch between multiple conditions based on a simple ON/OFF list of flags 

var myflags; //all flags are 0 

flags_set(myflags,0); // set flag 0 to 1. flags_set always sets to 1
flags_set(myflags,3); // set flag 3 to 1. flags_set always sets to 1
flags_set(myflags,0,3); // alternativle we can write this to set 2 or more flags in one go
flags_set(myflags); // set all 32 flags to 1

if(flags_test(myflags,0) > 0); // is flag 0 set to 1?
if(flags_test(myflags,0,3) > 0); // is flag 0 and flag 3 set to 1? Up to 32 flags in one call
if(flags_test(myflags,0)> 0 & flags_test(myflags,3)==0); // is flag 0 set to 1 and flag 3 set to 0?
if(flags_test(myflags) > 0); %%//%% is any flag set to 1?

flags_clear(myflags,0); // set flag 0 to 0
flags_clear(myflags,3); // set flag 3 to 0
flags_clear(myflags,0,3); // set flag 3 and 0 to 0. Up to 32 flags in one call
flags_clear(myflags); // set all flags to 0

 

flags_set

Checks if a Flag is set to 1.

Calls:

flags_set(scalar);
flags_set(scalar,flag, ...)

Parameters:

Name Description
scalarthe variable to use to store the flags
flag (0,…31) flag field

Output:

Return Description
scalar0: failed, 1: success

flags_test

Checks if a Flag is set to 1.

Calls:

flags_test(scalar); 
flags_test(****scalar,flag, ...)

Parameters:

Name Description
scalarthe variable to use to store the flags
flag (0,…31) flag field

Output:

Return Description
scalar0: flag is not set, 1: flag is set

flags_clear

Sets a Flag to 0.

Calls:

flags_clear(scalar); 
flags_clear(scalar,flag, ...)

Parameters:

Name Description
scalarthe variable to use to store the flags
flag (0,…31) flag field

Output:

Return Description
scalar0: failed, 1: success

Summary of all Data Types

 

Particle Data Types

Used exclusively by:

get_pdata
set_pdata

Data Type Type Description
data_pos Vector Particle position.
data_vel Vector Velocity, if the out is a Scalar value, the Speed will be available
data_force Vector Force to add to particle velocity.
data_spin Vector Spin (angular velocity). If the out is a Scalar value, the Angular speed will be available
data_mass Scalar Mass.
data_size Scalar Size.
data_scale Vector Scale.
data_xalign Vector Alignment along x-axis (only available for get_pdata, not for set_pdata).
data_yalign Vector Alignment along y-axis (only available for get_pdata, not for set_pdata).
data_zalign Vector Alignment along z-axis (only available for get_pdata, not for set_pdata).
data_dchan Scalar or VectorData channel 0 (to access data channel 1, use data_chan + 1, etc.).
data_age Scalar Age in seconds.
data_life Scalar Lifespan in seconds.
data_fage Scalar Age in frames.
data_flife Scalar Lifespan in frames.
data_age_rel Scalar Age relative to lifespan.
data_rseed Scalar Random seed.
data_alive Scalar Whether the particle is alive (only available for get_pdata).
data_born Scalar Whether the particle is born (only available for get_pdata).
data_genter Scalar Whether the particle is new in the group (entered group) (only available for get_pdata).
data_die N/A Setting this data type will cause the particle to die (only available for set_pdata).
data_group Group Change the particle group (only input groups can be set; set_pdata(pid, data_group, group2_in_id)).
data_shape N/A Check if there is a shape on the particle.
data_nrefs Scalar Number of from and to references.
data_nrefs_fromScalar Number of from references.
data_ptransform Vector transforms a point see table below for fromto_transform_types
data_vtransform Vector transforms a vector see table below for fromto_transform_types
data_dtransform Vector direction transformation, no scale, no translation is being computed fromto_transform_types
data_ntransform Vector transforms a normal without translation fromto_transform_types
data_trtransform Vector transforms a point with translation and rotation (no scale) fromto_transform_types

Find Data Types

Used exclusively by: 

group_in_find

Data Type Description
find_pid Return the Particle id that was found
find_dist2Square distance
find_dist Distance
find_dif Difference Vector from search position to found particle position
find_dir Direction to find particle position
find_mcenter Calculates the Center of Mass of particles found
find_vel_average Calculates the average velocity of particles found
find_vel_maverage Calculates the average velocity weighted by mass of particles found

Point Data Types

used by: 

Data Type Description
point_pid scalar particle id
point_pos vector[3] world position
point_opos vector[3] object position
point_dist vector[3] hit distance (pgroup_isect_data)
point_dir vector[3] direction to point in world space
point_dot scalar the dot product is the cosine of the hit angle to the normal (pgroup_isect_data)
point_back scalar is a backside hit (pgroup_in_isect_data)
point_norm vector[3] world surface normal
point_onorm vector[3] object surface normal
point_gnorm vector[3] world geometry normal
point_ognorm vector[3] object geometry normal
point_uvw vector[3] uvw coordinates
point_mtlid scalar material id (scalar)
point_fid scalar face id
point_bc vector[3] barycentric coordinates
point_col vector[3] material color (shaded color on point)
point_vel vector[3] world particle velocity on the hit point (include spinning)
point_center vector[3] world center of the particle
point_oid scalar object id (objects_in_point)
point_tang vector[3] world space tangent
point_otang vector[3] object space tangent
point_cid scalar curve id (used in shapes_in_point)
point_scid scalar sub curve id (used in shapes_in_point)
point_cpos scalar curve position relative (used in shapes_in_point)
point_scpos scalar sub curve position relative (used in shapes_in_point)
point_edge_id     scalar    point on edge, returns the edge index
point_edge_rpos    scalar    point on edge, the relative position on the edge range 0-1

Geom Data Type:

Data Type Description
geom_nfaces scalar number of faces
geom_nverts scalar number of vertices
geom_nedges scalar number of edges
geom_nmaps scalar number of UVW mapping channels
geom_map_usedscalar mapping channel used, 1 for used 0 for not used
geom_ntverts scalar number of texture vertices in the mapping channel
geom_pid scalar particle id when the object is a particle, otherwise -1
geom_surface scalar surface area of the object
geom_volume scalar volume of the object
geom_center scalar center of the object in world space
geom_xalign vector[3-4]x alignment axis of the object transform matrix, when the output vector is set to vector[4] then vector [3] contains the scale of the axis
geom_yalign vector[3-4]y alignment axis of the object transform matrix, when the output vector is set to vector[4] then vector [3] contains the scale of the axis
geom_zalign vector[3-4]z alignment axis of the object transform matrix, when the output vector is set to vector[4] then vector [3] contains the scale of the axis
geom_vel vector[3] velocity of the object
geom_palign scalar aligns a particle to an object (copy object alignment to the particle)
geom_init_vcol scalar initializes the vertex color channel (pshape_geom_set)
face_mtlid scalar face material id
face_norm vector[3] interpolated normal on face in world space
face_onorm vector[3] interpolated normal on face in object space
face_gnorm vector[3] face geometry normal in world space
face_ognorm vector[3] face geometry normal in object space
face_center vector[3] face center in world space
face_ocenter vector[3] face center in object space
face_pos vector[3] interpolated position on face in world space
face_opos vector[3] interpolated position on face in object space
face_vid vector[3] the three face vertex ids
face_vpos vector[3] face vertex position in world space
face_ovpos vector[3] face vertex position in object space
face_selected scalar is the face selected 0 Not selected, 1 selected
face_nfid vector[3] three neighbor faces indexes, range 0 >= id < nfaces, an index of -1 means not defined (no neighbor face)    
face_eid vector[3] three edge indexes of the face, range 0 >= id < nedges
face_vcol vector[3] returns the vertex colors at the face' vertex
face_vcol_bc vector[3] returns the interpolated vertex color on the face
vert_pos vector[3] vertex position in world space
vert_opos vector[3] vertex position in object space
vert_norm vector[3] vertex normal in world space
vert_onorm vector[3] vertex normal in object space
vert_col vector[3] shaded color at vertex position
vert_nedges scalar number of edges at vertex
vert_edge scalar get real edge ID form vertex
vert_vcol vector[3] get the vertex color (average of all colors at face)
tface_center vector[3] texture face center uvw coordinates
tface_vid vector[3] texture face vertex ids (vector[3] for the three tvert indexes)
tface_vuvw vector[3] texture face vertex uvw
tface_uvw vector[3] interpolate uvw coordinates on texture face
tvert_uvw vector[3] texture vertex uvw coordinates
edge_vid vector[2] The two vertex IDs of the edge, 0 to nverts
edge_fid vector[2] The two face IDs of the edge, 0 to nfaces. A value of -1 means undefined.
edge_vpos vector[3] Vertex position of one of the two edge vertices
edge_ovpos vector[3] Vertex position of one of the two edge vertices in object space
edge_center vector[3] Center position of the edge
edge_ocenter vector[3] Center position of the edge in object space
edge_open scalar Edge is open (0 = no, 1 = yes)
edge_visible scalar Edge is visible (0 = no, 1 = yes)
edge_selectedscalar Edge is selected (0 = no, 1 = yes)
edge_length scalar Length of the edge in world space
edge_angle scalar Angle in radians between the two edge faces
edge_pos vector[3] Interpolated position on the edge
edge_opos vector[3] Interpolated position on the edge in object space
edge_norm vector[3] Interpolated normal on the edge
edge_onorm vector[3] Interpolated normal on the edge in object space
edge_gnorm vector[3] Geometry normal on the edge
edge_ognorm vector[3] Geometry normal on the edge in object space
edge_dir vector[3] Direction of the edge (tangent)
edge_odir vector[3] Direction of the edge (tangent) in object space
edge_vcol vector[3] Interpolated Vertex-Color at the edge

Memory Info Data Types

used by the following function: memory_in_info()

Value Description
mem_info_num_in Number of inputs.
mem_info_num_out Number of outputs.
mem_info_out_type Output type. Possible values: vtype_none, vtype_scalar, vtype_vector.
mem_info_in_type Input type. Possible values: vtype_none, vtype_scalar, vtype_vector.
mem_info_out_depthOutput depth.
mem_info_in_depth Input depth.

Value Types for memory_in_info

Data Description
vtype_none unknown value type
vtype_scalarscalar value type
vtype_vectorvector value type

Set Types for Field Out Functions

used by the following functions:

 

Data Description
set_replace replace the value
set_add add to the existing value
set_subtractsubtract from the existing value
set_multiplymultiply the existing value
set_divide divide the existing value
set_min set the minima value
set_max set the maxima value
set_average set the average of all incoming values

 

Transform Types for Fields, Object

Used by:

Name Description
transform_pointwill do a full transformation (Rotation,Scale,Translation)
transform_vectorwill do a transformation (Rotation,Scale)
transform_directionwill do a rotatioon transformation, only
transform_normalwill do a transformation (Rotation,Scale)
transform_transrotwill do a transformation (Rotation,Translation)

From To Types for Fields, Objects, Particles

Used by:

Name Description
object2worldwill convert the point/vector from object to world coordinates
world2objectwill convert the point/vector from world to object coordinates
voxel2world will convert the point/vector from voxel to world coordinates
world2voxel will convert the point/vector from world to voxel coordinates
voxel2objectwill convert the point/vector from voxel to object coordinates
object2voxelwill convert the point/vector from object to voxel coordinates

 

Parallel Types

used exclusively by: 

objects_in_parallel

Data Description
objects_use multi-threading to process all objects in the object list
face_ use multi-threading to process all faces
vertex_ use multi-threading to process all vertex
edge_ uses the center of the edge to process all edges
surface_use multi-threading to process random points on faces
esurface_ use multi-threading to process random points on edges

 

Rate Types

used by: 

 objects_in_parallel

Data Description
rate_per_subsample_with every subsample the number of points are processed
rate_per_second_ every second the amount of points are being processed 

 

Evaluation types for Scalar and Vector

used by:

Evaluation Type Description
evaltype_averageAll values are combined to create an average
evaltype_min Outputs the minimum value, or if the output is a vector, outputs the vector with the shortest length
evaltype_max Outputs the maximum value, or if the output is a vector, outputs the vector with the longest length
evaltype_cmin For scalars, it behaves the same as evaltype_min. For vectors, it outputs the minimum value for each component (x, y, z) separately
evaltype_cmax For scalars, it behaves the same as evaltype_max. For vectors, it outputs the maximum value for each component (x, y, z) separately

Light Illumination Data

used by: lights_in_illum_result 

Parameter Description
lights_illum_pos Returns the position of the illuminated point (world position)
lights_illum_norm Returns the normal of the illuminated point (world normal)
lights_illum_dir    Returns the direction towards the light as seen from the illuminated point (world normal)
lights_illum_dot    Returns the dot product of the normal and the direction (the angle between normal and light)
lights_illum_col Returns the color of the illuminated point 

 

Light Info Data

used by:

lights_in_info

Parameter Description
lights_info_posGets the world position of the light (vector)
lights_info_dirGet the light's direction (vector)
lights_info_colGets the color of the light color (vector for color or scalar for intensity …)

SplinePool Data Types

used by:

 

Parameter Description
spool_nsplines number of splines in the pool
spool_nknots number of knots in the spline
spool_length length of a spline in generic absolute     
spool_knot_pid particle id of a knot
spool_knot_type knot type (corner, spline or auto)
spool_knot_uvw texmap uvw coordinates of the knot
spool_knot_vcol vertex color of the knot
spool_knot_spos retrieves a position on the spline (scalar, length)
spool_knot_rel_sposretrieves relative position on the spline (between 0-1)
spool_knot_tangent retrieves the tangent of the knot (orientation), returns a vector
spool_pid2spline particle to spline, returns the spline id when the particle is a knot 
spool_lead_pid the leader particle id of the spline
spool_sid last created spline index
spool_kid last created knot index
spool_pos retrieves the 3D world coordinate on the spline
spool_out_tangent retrieves an interpolated tangent anywhere on the spline
spool_out_vel retrieves the interpolated the interpolated velocity anywhere on the spline


knot_types:

used in:

Parameter Description
knot_type_corner creates a corner knot type (straight line)
knot_type_spline creates a bezier spline type
knot_type_auto    creates an automatic type of spline (smooth)

 

 

©2024, cebas Visual Technology Inc.

reference_guide/math_expression_language/functions_variables/variables_functions_mel.txt · Last modified: 2024/03/04 22:09 by edwin

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki