Common Datatypes

From The Foundry MODO SDK wiki
Jump to: navigation, search

Commands and other aspects of modo use datatypes to represent different kinds of values. In the SDK, these are wrapped in an Value interface. When scripting, the datatypes are referenced by name. Datatypes include conversion to and from strings, and both "nice" (with units) and raw (without units) parsers. These datatypes define what kinds of values can be used in a particular context, and include integers, distances, colors, character strings and so on.

Simple Datatypes

The following are some common simple datatypes.

integer

Integers are simple non-fractional numbers, positive and negative. These are commonly used for on/off switches and choices.

float

Floats are double-precision floating-point numbers, which for scripting means they have can be fractional, like 3.1415. Due to rounding and general imprecision, these are generally accurate to about seven significant figures when converting to and from strings.

boolean

Booleans have only two states, on and off'. This is represented as an integer value of 1 or 0, and can generally be treated as integers. There isn't a unit mode, but text hints are provided for on, off, yes, no, true and false.

percent

Percents are floats with a percent sign attached. The raw value is 1/100th of the units value: 0.1 is equal to 10%. There is also a global preference to allow you to always work with percentages as floats without units, in which case there is no difference between the two modes.

distance

Distances are floats with distance units attached, such as meters and feet. When used in "raw" mode (ie: without square braces), they represent meters.

angle

Angles are floats with angular units. When used with commands as strings, these are always in degrees. Raw mode omits the degree symbol. When scripting, it is possible to force angles to be treated as radians. When used from SDK, the float representing the angle is in radians.

axis

Axis represents X, Y and Z axes. Similar to booleans, this is represented as an integer value of 1, 2 or 3. There is no units mode, but text hints are available for x, y and z.

uvcoord

UV Coordinates are single floats representing part of a UV coordinate. There are no modes that support units.

time

Times are used to represent durations. In raw mode they are floats representing seconds. When used with units, the time unit system preference is used to determine how the value is represented, but this can be overridden depending on the formatting of the string. If a colon (:) is present, timecode is assumed and more colons are searched for, such as 01:00:05:16. If a plus (+) is found, film footage plus frames is assumed in the form of 12+8. If there is an "s", such as 2.3s, then the time is interpreted as seconds. An "f" can be used to interpret as frames, like 10f. Except for seconds, these interpretations are based on the current frame rate and time unit system; seconds are completely independent of the system settings and are preferred for scripting and for plug-in development.

color

Colors in raw mode are three floats. When used with units, they can be three floats, three integers, three percents or three HTML-style hexadecimal numbers, depending on the current color system. Integer values are clipped to 0 the range of 255. In the SDK, colors and all other array types are tread as a Value Array.

light

Light Intensity describes the amount of illumination thrown off by a light. The raw units are in terms of radiance, or W/srm2 (Watts per steradian per square meter). Unit mode can use either this radiance representation or photometric luminance units of cd/m2 (candela per square meter).

memory

Memory is used to describe storage capacity in memory or on disk, and is represented by a float. The raw mode is an integer representing the number of bytes. The unit mode will display kilobytes, megabytes and gigabytes. The standard conversion is used, with 1024 bytes to a kilobyte, 1024 kilobytes to a megabyte and 1024 megabytes to a gigabyte.

pixel

Pixels are simple integers used to represent positions and sizes in screen coordinates. The unit mode has the word pixels added after the integer.

string

Strings are simple character strings. There is no special mode with units.

filepath

File paths are identical to strings, but they indicate that this is a path to a file or directory on disk. There is no special mode with units.


Simple Datatype Examples

The table below lists the names of the various datatypes and example values for the raw modes and when using units.

Datatype Description Raw Examples Unit Examples
angle Angle 90, 23.4, 180 90 °, 23.4 °, 180 °
axis 3D Axis 0, 1, 2 x, y, z
boolean Boolean 0, 1 on, off, yes, no, true, false
color Color [1.0, 0.5, 1.0] [1.0, 0.5, 1.0], #FF77FF, [255, 128, 255], [100.0%, 50.0%, 100.0%]
distance Distance 1.0, -3.4, 100.2 1.0 m, 1’ 24", 6 km
filepath File Path C:\Path (no units)
float Decimal Number 1.0, 3.6, -28.2, 0.04 (no units)
integer Integer Number 1, 18, -6, 0, 1048 (no units)
light Light Intensity 3.0, 0.5 3.0 W/srm2, 89.5 cd/m2
memory Memory 65536, 1073741824 64 KB, 1 GB, 128.42 MB
percent Percentage 0.152, 1.0, -0.3 15.2%, 100%, -30%
pixel Pixel 128, 20, 8000 128 pixels, 20 pixels
string String Everyone loves modo! (no units)
time Time 4.0, 0.333, 12.0 5 s, 20 f, 01:00:10:13, 120+12
uvcoord UV Coordinate 0.4, 0.7, 0,2 0.1, 0.9, 0.004

Complex Datatypes

There is also a special class of complex datatypes. These start with an ampersand (&), such as &item or &attribute. Each has its own specific format, often an index, name or path to a specific element. For example, &item types use the item reference, which is described as a hexadecimal number such as 0x10000001. The &attribute type describes the path to a form or control, such as formHash/controlIndex or 75478769354:sheet/1. These datatypes are often used by the various selection commands. They are also referred to as pointer datatypes, as they often resolve to pointers to objects.

SDK Declarations

The common datatypes are defined in the value header using macros like these:

#define LXsTYPE_FLOAT     "float"
#define LXsTYPE_DISTANCE  "distance"