14 Properties, Attributes, Primitives, and Functions
This chapter provides reference information for the following AVS/Express components:
- Base types (examples: int, float, macro)
- Properties (examples: NEbackgroundPixmap, need_cxx)
- Attributes (examples: read, notify)
- Built-in functions (examples: cos, merge)
It contains the following sections:
Base types-primitives and others-are the fundamental building blocks of AVS/Express.
Table N-1
|
|
|
boolean byte char double enum float int short string ptr prim
|
Boolean integer (0 or 1 only). One-byte integer object. One-byte object that can hold a single character. Double-precision floating point object. Enumerated data type. Single-precision floating point object. Integer object. Short integer object. NULL-terminated character string object. Pointer data object that points to a user data structure. Object with unset data type (used for any one of the above).
|
|
|
Defines an object with subobjects.
|
|
|
Creates a library of objects. Creates a library of objects whose V-code definition is stored in a V file.
|
|
|
Hold a combinations of modules, macros, and connections.
|
|
|
Holds parameters and methods to implement objects that interface to C or C++ code.
|
method omethod cmethod cxxmethod
|
Interface directly to a C function or C++ method.
|
|
|
Route connections, often into or out of a macro or application object.
|
14.2 Properties and Attributes
A property is a name-value association placed on an object that defines a characteristic of that object; for example:
- Its x,y placement in the Network Editor
- Its number of levels of exported ports
- Its dimensionality
Property names are usually defined by the system (though you can create your own) and relate to a specific aspect of object behavior. In V code, properties appear after the object name, delimited by the less-than (<) and greater-than (>) characters.
An attribute is a Boolean characteristic that you can apply to an object to modify its behavior. AVS/Express defines a fixed set of these characteristics.
A simple way to access many of the properties and attributes of an AVS/Express object is through the Properties Editor in the Network Editor. The Properties Editor provides a Property Group options menu from which you can open a Properties Editor page containing either all or a subset of the properties and attributes accessible in the Network Editor. Note that not all properties and attributes are accessible in the Network Editor; some are accessible only when you are working in the object's V file.
For information on accessing properties and attributes in V, see Using the Properties Editor on page 5-47 and Chapter 7, V and the V Command Processor.
Properties and attributes can be classified as:
- General properties and attributes
- Network Editor properties and attributes
- Module control properties
- Code management properties
- C++ interface properties
The following sections describe the members of these groups.
General Properties and Attributes
This table describes miscellaneous properties and attributes.
Table N-1
|
|
|
|
|
|
Default: "dictionary_name"
|
The name of a dictionary file to be loaded into a translation table for localization. The OM loads the dictionary from a file with the following relative pathname:
runtime/nls/<locale_name>/<dictionary_name>
|
|
|
|
If set, declares an object as an array and sets the dimensions of that array.
|
|
|
|
If set (to 1) on any hierarchical object, neither that object nor any of its children are not included in any compile operation. (A hierarchical object is a library, macro, group, or module.)
|
|
|
Default: 0 or 1, depending on the object's state
|
Changes the instanced state of an object:
-- If set to 0 on an instanced object, that object and all of its subobjects are deinstanced (all deinstanced methods are called).
-- If set to 1 on a deinstanced object, that object and all of its subobjects are instanced (all instance functions are called).
|
|
|
|
The .v file to associate with an flibrary object. If the specified file name does not include a .v suffix, AVS/Express adds one and generates a binary .vo file to make subsequent loads of the flibrary faster.
|
|
|
|
Can be used with the libfile property or with the file library syntax:
It indicates that the library is to be loaded immediately when it is encountered, rather than waiting for some reference to objects in the library to force it to be loaded. You need this property when you define any objects with virtual data.
|
|
|
|
If set to 1, the object's subobjects cannot be added or removed.
|
|
|
Default: " virt_name1 virt_name2"
|
Defines a dependency between an object or library and one or more pieces of virtual data. When this object or library is needed for a project, all objects that define virtual data are also added to this project.
|
|
|
|
If set, the object is not saved with the rest of the application state.
|
|
|
|
If set, warnings normally generated if the object is not immediately resolvable are suppressed.
|
|
|
|
If set, makes connections to an object read only.
|
|
|
Default: depends on object (usually "^")
|
The object's reference mode; that is, whether it is a pointer ("*"), a reference ("&"), or an actual value object ("^"). Reference mode is an intrinsic property of an object, so you should treat ref_mode as read only and not use it to set a value.
|
|
|
|
Performs a trace on the object.
|
|
|
|
If set to 0 on a DefaultApplication object, prevents UImod_panel objects instantiated in the application or its children from creating and displaying their own shells.
|
|
|
|
If set to 1 for an object in a library on which user_library is set to 0, forces the object to be derived from when copies are made.
|
|
|
|
If set to 0 on a library, indicates that the objects in this library cannot not be derived from.
|
|
|
|
An alternate name for the object to display in the Network Editor.
|
|
|
|
Sets an explicit value state for the object for save and restore operations.
|
|
|
|
If set, specifies that the object is virtual.
|
Network Editor Properties
This table describes Network Editor properties, which affect the object's appearance in the Network Editor.
Table N-2
|
|
|
|
|
|
|
The name of an AVS image file that contains the definition of a pixmap to be displayed in the background of the subwindow of an open macro object.
You can specify an absolute or a relative pathname. If you specify a relative pathname, AVs/Express searches for the file in the following directories:
-- The directory specified by the XP_PIXMAP_PATH environment variable (if set)
-- The runtime/pixmaps subdirectory of each component of the XP_PATH variable, defined in either the environment or your avsenv file
|
NEcolor0 NEcolor1 NEcolor2 NEcolor3 NEcolor4 NEcolor5
|
|
The value of the ith color of an object's port. Specify the value as a hexadecimal number of the form 0xrrggbb, where rr, gg, and bb are the RGB components of the color; for example:
The number of colors is specified using the NEnumColors property. Each color occupies an equal portion of the port.
|
|
|
Allowed values: "closed" "open" "maximized"
|
A value indicating whether the object is closed, open, or maximized. Display mode is normally controlled by popup commands, hence this property does not appear in the Properties Editor. However, it is included in an object's V definition when you save it to a file.
|
|
|
|
A flag indicating whether the following is allowed:
--Adding subobjects to or deleting them from the object
-- Editing characteristics of the subobjects
-- Destroying the subobject
|
|
|
|
The size (in pixels) of the grid to which all subobjects of a macro are snapped when positioning them.
|
|
|
|
The height (in pixels) of an open object when displayed inside an open macro object.
|
|
|
|
The HyperHelp context ID associated with the the object's online help.
This property is provided for developers who have obtained a license from Bristol Technologies Inc. for developing their own online help.
|
|
|
|
The name of the HyperHelp .hlp file that contains the object's online help.
You can specify an absolute or relative pathname. If you specify a relative pathname, AVS/Express searches for the file in the runtime subdirectory of each component of the XP_PATH variable, defined in either the environment or your avsenv file.
This property is provided for developers who have obtained a license from Bristol Technologies Inc. for developing their own online help.
|
|
|
|
The HyperHelp topic associated with the object's online help.
This property is provided for developers who have obtained a license from Bristol Technologies Inc. for developing their own online help.
|
|
|
Default: "pixmap_and_text"
Allowed values: "pixmap" "text" "pixmap_and_text"
|
A value that indicates whether a pixmap, text, or both are displayed in an object's icon.
|
|
|
|
The name of the file that contains the pixmap that is displayed when the value of the NEpixmapMode property is "large".
You can specify an absolute or a relative pathname. If you specify a relative pathname, AVs/Express searches for the file in the following directories:
-- The directory specified by the XP_PIXMAP_PATH environment variable (if set)
-- The runtime/pixmaps subdirectory of each component of the XP_PATH variable, defined in either the environment or your avsenv file
|
|
|
Allowed values: "avs_image" "x_bitmap" "bmx"
|
The format of the file containing the pixmap that is displayed when the value of the NEpixmapMode property is "large". The allowed values indicate the following file formats:
-- "avs_image" is an AVS image format.
-- "x_bitmap" is the standard monochrome X bitmap format.
-- "bmx" is BMX format, an AVS/Express format derived from the Windows BMP format.
|
|
|
|
The number of colors used when drawing the object's port. The maximum is 6. To specify individual colors, use the properties NEcolor0 through NEcolor5.
|
|
|
|
A flag that indicates whether the object can be opened in the Network Editor. Use this property to prevent users from viewing and modifying certain components.
This property does not appear in the Properties Editor.
|
|
|
Allowed values: "small" "large"
|
A value indicating the layout of the pixmap and text in the object icon.
-- If the value is "small", the pixmap is displayed at the left side of the icon and the text is displayed to the right of the pixmap.
-- If the value is "large", the pixmap is displayed above the text and both the pixmap and the text are horizontally centered.
Note that "small" pixmap mode is always used when an object is open.
|
|
|
Default: "Templates. NE_MACROS. NEobjPopupMenu"
|
The pathname of the temporary object that is used for displaying the popup menu for an object. The default version of the popup menu is defined in ne_macro.v and the components of the menu are defined in ne.v. To customize the popup menu for your objects, specify the pathname of your own popup menu.
|
|
|
|
The extent to which the input and output ports of an object are exposed. The first integer controls the input port, and the second controls the output port. Port level values have the following meanings
-- 0: The port is not exposed.
-- 1: The object is exposed to the level of the object's siblings.
-- 2: The object is exposed to the level of both the object's siblings and the siblings of the object's parent.
-- Greater than 2: The object is exposed further.
|
|
|
|
The scaling (zoom) factor for objects in the subwindow of an open macro object. Zooming is normally controlled by the mouse or popup menu, hence this property does not appear in the Properties Editor . However, it is included in an object's V definition when you save it to a file.
|
|
|
|
The name of the file containing the pixmap displayed when the value of the NEpixmapMode property is "small".
You can specify an absolute or a relative pathname. If you specify a relative pathname, AVs/Express searches for the file in the following directories:
-- The directory specified by the XP_PIXMAP_PATH environment variable (if set)
-- The runtime/pixmaps subdirectory of each component of the XP_PATH variable, defined in either the environment or your avsenv file
|
|
|
Allowed values: "avs_image" "x_bitmap" "bmx"
|
The format of the file containing the pixmap that is displayed when the value of the NEpixmapMode property is "small". The allowed values indicate the following file formats:
-- "avs_image" is an AVS image format.
-- "x_bitmap" is the standard monochrome X bitmap format.
-- "bmx" is BMX format, an AVS/Express format derived from the Windows BMP format.
|
|
|
|
A flag that prevents AVS/Express from considering the object's port when it executes the Arrange Icons popup command for an open macro object.
|
|
|
|
A flag indicating whether an object is displayed in the Network Editor. Use this property to hide objects from end users.
|
|
|
|
The width (in pixels) of an open object when displayed inside an open macro object.
|
|
|
|
The X and Y position (in pixels) of an object when displayed inside an open macro object.
|
|
|
|
The X and Y panning offset (in pixels) of all children of a macro object. Panning is normally controlled by the mouse, hence this property does not appear in the Properties Editor. However, it is included in an object's V definition when you save it to a file.
|
Module-Control Properties and Attributes
This table describes module-control properties and attributes, which specify the information necessary to determine the behavior of a module's methods and parameters.
For more details, see Chapter 8, Developing Modules.
Table N-3
|
|
|
|
|
|
|
If set to 1, enables the following behavior: if an object with an update method is instanced, and a new subobject is added whose "notify" attribute is set, the update method fire in responses to a change in the value of the new subobject.
|
|
|
|
If set on a parameter, specifies that the module does not affect that parameter or its subobjects in any way. Setting this property is equivalent to setting nonotify+noread+nowrite on a parameter.
|
|
|
|
If set, forces the notify attribute off even if the inherited value is on.
|
|
|
|
If set, forces the read attribute off, even if the inherited value is on.
|
|
|
|
Specifies that all of an object's methods are invoked when the value of the subobject on which this attribute is set changes.
|
|
|
|
If set for a method subobject, specifies that method is invoked when the object is instantiated
|
|
|
|
If set for a method subobject, specifies that method is invoked when the object is destroyed
|
|
|
|
If set, forces the write attribute off, even if the inherited value is on.
|
|
|
|
Helps to determine the conditions for invoking an update method. Also, specifies that the object is optional for the purposes of object matching
|
|
|
|
If set on the subobject of a module, causes AVS/Express to generate code that makes it easier to get the value of that subobject inside a method. For C, it will generates the code to get the method; for OMX, it will generate a comment that notes that the variable is exported and available
|
|
|
|
If set on the subobject of a module, tells AVS/Express not to fire any method that reads this subobject unless it has a defined value
|
|
|
|
If set, specifies the order in which a set of methods all responding to the same event are called. If unset, the order is undefined.
|
|
|
|
If set on the a subobject of a module, tells AVS/Express to export that subobject for writing; that is, generate code in methods of the module to make it easier to set the value of this subobject.
|
Code Management Properties
This table describes code management properties, which are used when compiling projects. These properties generally apply only to modules and libraries, and therefore appear in the Properties Editor only for these objects.
For more details, see Providing Code Management Information on page 8-28.
Table N-4
|
|
|
|
|
|
|
A make command to execute. The command is performed in the build directory (see build_dir, elsewhere in this table). For example:
|
|
|
|
|
|
|
Default: "my_hdr1.h my_hdr2.h"
|
C header files that AVS/Express includes in the code it generates as part of encapsulating a structure or function. The specified header files must be in the header directories (see hdr_dirs, elsewhere in this table).
|
|
|
|
A list of C source files to be compiled. You can specify an absolute pathname or a pathname relative to the build directory (see build_dir, elsewhere in this table). For example:
c_src_files="src1.c src2.c"
See also src_file, elsewhere in this table.
|
|
|
|
If set to 0, specifies that the object and objects below it in the object hierarchy are never compiled.
You use this property for efficiency. For example, a macro object typically consists of objects defined elsewhere, so does not itself need to be compiled. If you have a large library of such objects, you can spare AVS/Express the effort of searching the library. You typically insert this property into the library:
|
|
|
Default: "my_hdr1.hxx my_hdr2.hxx"
|
C++ header files that AVS/Express includes in the code it generates as part of encapsulating a structure or function. These header files must be in the header directories (see hdr_dirs, elsewhere in this table).
|
|
|
Default: "src1.cxx src2.cxx"
|
A list of C++ source files to be compiled. You can specify an absolute pathname or a pathname relative to the build directory (see build_dir, elsewhere in this table). The default make rules can compile only C++ source files that have the .cxx suffix. For example:
cxx_src_files="src1.cxx src2.cxx"
|
|
|
|
The declaration of a function called in the line of C code specified by the init_code property (elsewhere in this table). For example:
hdr_code="int FLD_METHinit();" init_code=FLD_METHinit();"
|
|
|
|
A list of directories to search for header files (equivalent to a compiler's -I option). You can specify an absolute pathname or a pathname relative to the build directory (see build_dir, elsewhere in this table).
|
|
|
|
A line of C code to execute when the process starts. If the C code calls a function that is not declared, use the hdr_code property (elsewhere in this table) to declare the function. For example:
hdr_code="int FLD_METHinit();" init_code=FLD_METHinit();"
|
|
|
|
The language of a method's function, either C or C++. The default language is C, so you need to specify this property only when the language is C++. Unlike the other process properties, lang is not inherited. You need to specify this property only when the OM cannot determine the language itself, for example, when a C module calls a C++ function.
Note that you use the string "cxx" rather than "c++".
|
|
|
|
The names of other AVS/Express libraries that must be included in each process in which this object is placed. You can use this property to specify dependencies in code that are not expressed in the dependencies between the AVS/Express objects themselves. Any link files associated with the specified libraries are included in any process in which this object is used. For example:
|
|
|
Default: "-lmy_lib1 libmy_lib2.a my_obj1.o my_obj2.o"
|
Text to pass to the linker (without interpretation, in the linker line), typically object (.o) files and object libraries. This property is useful for specifying library paths, libraries, and/or object files to link in, and so on. Use it instead of (or in addition to) the c_src_files and cxx_src_files properties (elsewhere in this table) when you use your own make file compile your source. For example:
link_files="-L /my_lib_dir -lmods -lmutil"
|
|
|
|
If set to 1, specifies that the C++ linker is required for this process. AVS/Express can generally determine whether the C++ linker is required by observing whether any method object specifies lang="cxx" or has a cxxmethod subobject.You use this property when it cannot determine this. For example, if a method calls a C function and that function in turn calls a C++ function, AVS/Express does not know about the C++ function and therefore not know that the C++ linker is required.
|
|
|
|
The path names of other AVS/Express objects created dynamically by this module. You use this property to ensure that these objects are included in a compiled project that contains your modules. For example:
need_objs = "UIbutton MODS.clamp"
|
|
|
|
If set to 1 on any object included in a process, AVS/Express does not link a "main()" function into the process. In this case, you must supply your own "main()" function using a cxx_src_file, c_src_file, or link_files property (described elsewhere in this table).
|
|
|
|
The name of a header file that contains automatically generated header definitions for this object and its subobjects. Do not edit this header file; it is maintained by AVS/Express relative to the current build directory (build_dir, elsewhere in this table). This header file includes the declaration of any methods and definitions for OMX and UCI objects. If you do not specify a value for this property for an object or its ancestor, definitions are placed in processname.h. For example:
out_hdr_file="uci_gmod.h"
|
|
|
|
The name of a source file that contains automatically generated source code for this object and its subobjects. Do not edit this source file; it is maintained by AVS/Express relative to the current build directory (build_dir, elsewhere in this table). This source file includes code to support OMX and UCI objects. Specify the file name without a suffix so that the system can append a .c or .cxx suffix depending upon whether it includes C++ definitions. If you do not specify a value for this property for an object or its ancestor, definitions are placed in processname.[c|cxx]. For example:
|
|
|
|
A line of C code to execute before templates are loaded. If the C code calls a function that is not declared, use the hdr_code property to declare it.
|
|
|
|
The process to which the object belongs. For example:
|
|
|
|
A file into which to generate prototype source code for the object. If the generated code is C, any existing source code is not overwritten and must be explicitly deleted each time new code is to be generated. If it is C++, the existing source code is not changed, but any methods to be generated that are not already defined in the existing code are added to the end. This property is also used in conjunction with the Project ->Edit Source pull-down command. For example:
|
|
|
|
If set to 0, disables the generation of prototype source for an object and its subobjects. For C++ only, use this property if you do not want AVS/Express to maintain the correspondence between the source file (src_file, elsewhere in this table) and the methods in these objects.
|
This table describes C++ interface properties, which are used by objects with C++ methods (cxxmethod subobject). These properties control the interface between objects and C++ code.
For details, see C API Usage Notes on page 9-16.
Table N-5
|
|
|
|
|
|
|
If set, prevents AVS/Express from generating a constructor call for an abstract class.
|
|
|
|
The name of a C++ class with which to associate the object. When the object is instanced, an instance of the class is created; when the object is deinstanced, the class instance is also deinstanced. When a cxxmethod subobject is called, a pointer to the C++ class instance can be obtained. Set the cxx_hdr_files and cxx_src_files properties to include the source files that define the C++ class to be thus imported.
See also cxx_class_args, cxx_abstract, cxx_src_files, and cxx_hdr_files, elsewhere in this table.
|
|
|
Default: "arg1,arg2,arg3"
|
Used in conjunction with the cxx_class property to specify the parameters (if any) to the constructor for an imported C++ class. Place the specified string between the parentheses in the generated call to the class's constructor.
|
|
|
Default: "my_hdr1.hxx my_hdr2.hxx"
|
C++ header files that AVS/Express includes in the code it generates as part of encapsulating a structure or function. The header files specified must be in the header directories (see hdr_dirs, in the table in Code Management Properties on page 14-13).
|
|
|
|
Defines additional members in an exported C++ class. For example:
cxx_members="char *my_ptr;"
The text string is inserted directly into the class definition, so it must have correct C++ syntax. Note that you can make the member private:
cxx_members="private: char *my_ptr;"
Normally, the only class members are the exported objects in the object hierarchy.
See cxx_members_constr, elsewhere in this table.
|
|
|
|
Code with which to construct new C++ class members added using the cxx_members property. The specified string is added to a comma-separated list after the class constructor. For example:
cxx_members_constr="my_ptr(0)"
See cxx_members, elsewhere in this table.
|
|
|
|
A name to use for the object in generated C++ code.
|
|
|
Default: "src1.cxx src2.cxx"
|
A list of C++ source files to be compiled. You can specify an absolute pathname or a pathname relative to the build directory (see build_dir, in the table in Code Management Properties on page 14-13). The default make rules can compile only C++ source files with the .cxx suffix. For example:
cxx_src_files="src1.cxx src2.cxx"
|
|
|
|
Specifies how many levels up the object hierarchy to export an object. For example:
-- A value of 0 means that the object should not be exported.
-- A value of 1 exports the subobject to its parent.
-- A value of 2 exports the subobject to its parent's parent.
This is useful for fine-tuning the exporting of individual subobjects in an exported object hierarchy.
See export_cxx, elsewhere in this table.
|
|
|
|
Controls how Express generates C++ code for an object. The allowed values are as follows:
-- 0: Do not generate a C++ class for this object.
-- 1: Generate a C++ member for each AVS/Express subobject unless its export property is set to 0. This is the default for any module with a cxxmethod subobject.
-- 2: Generate a C++ member only for AVS/Express subobjects whose NEportLevels or export property is set to 2 or higher; that is, they export themselves at least to their parent object.
-- 3: Generate a C++ member for each subobject whose NEportLevels or export property is set to export itself to the current object's level.
See export, elsewhere in this table.
|
|
|
|
If set, specifies that by default, all subobjects are exported.
|
|
|
|
If set, specifies that subobjects are exported.
|
14.3 Defining Combinations of Properties and Attributes
Some objects in AVS/Express are defined solely to manage common combinations of properties and attributes so that V language definitions of objects can utilize a short-hand representation for referring to this group of attributes. In order to understand how these objects work, it is important to understand the general concepts behind the merge operation.
The merge operation that applies to groups, modules, and macros applies to other objects as well but it behaves somewhat differently.
In general, you can merge the definition of any template object into a compatible destination object. All information in the template object is added to the destination including properties, attributes, dimensions, data type, subobjects and value. When the destination object already has a conflicting definition of a particular piece of information, it is replaced by the new definition from the template object.
The objects involved in the merge operation must be compatible base types. You cannot merge a primitive data object into a group for example. If the objects involved in the operation are groups, modules, or macros, the template object is added to the derivation hierarchy of the destination object. If the object is not a group, module, or macro, the merge operation represents a one-time exchange of information. Future changes to the template are not propagated to the destination object as will happen with groups, modules, and macros.
Maintaining Properties and Attributes
The atts base type maintains properties and attributes. It can be merged into all different types of objects. When it is merged into a destination object, it simply copies the properties and attributes defined on it into the destination object. If the first type in a V construct is an attribute (such as the "read" attribute), the atts base type is implied. The following represent some standard AVS/Express V definitions of atts objects:
atts Port<NEportLevels=1>;
atts IPort<NEportLevels={1,0}>;
atts OPort<NEportLevels={0,2}>;
read+req+IPort2 Iparam; // here "atts" is implied.
These objects can be used when defining V descriptions of modules as short-hand for setting the NEportLevels property and the read, req attributes. You use these atts objects particularly when you are defining objects in V.
For example:
int+IPort foo;
Field+Iparam bar;
AVS/Express defines a collection of these atts objects that you can use:
|
|
|
|
|
|
|
|
sets NEportLevels = {1,0}
|
|
|
sets NEportLevels = {0,1}
|
|
|
|
|
|
sets NEportLevels = {2,0}
|
|
|
sets NEportLevels = {0,2}
|
|
|
|
|
|
|
|
|
|
|
|
sets NEportLevels={2,0}, read, req
|
|
|
sets NEportLevels={0,2}, write, nonotify
|
AVS/Express supplies a large number of built-in functions. These functions can be classified as follows: mathematical, logical, array, and miscellaneous- index_of, merge, name_of, str_array, and str_format, and switch. A value expression can contain built-in functions.
For more information on these functions as expressed in V, see V Functions on page 7-46
The following table summarizes the AVS/Express mathematical functions.
Table N-1
|
|
|
|
|
|
|
|
Arc cosine of arg, expressed in radians.
|
|
|
Addition; equivalent to arg1 + arg2 + ... .
|
|
|
Arc sine of arg, expressed in radians.
|
|
|
Arc tan of arg, expressed in radians.
|
|
|
Cosine of arg, expressed in radians.
|
|
|
Hyperbolic cosine of arg, expressed in radians.
|
|
|
Division; equivalent to arg1 / arg2 / ... .
|
|
|
e raised to the power of arg.
|
|
|
Natural logarithm of arg.
|
|
|
Base 10 logarithm of arg.
|
|
|
Modulo; equivalent to arg1 % arg2 % ... .
|
|
|
Multiplication; equivalent to arg1 * arg2 * ... .
|
|
|
arg1 raised to the power of arg2.
|
|
|
Sine of arg, expressed in radians.
|
|
|
Hyperbolic sine of arg, expressed in radians.
|
|
|
|
|
|
Subtraction; equivalent to arg1 - arg2 - ... .
|
|
|
Tan of arg, expressed in radians.
|
|
|
Hyperbolic tan of arg, expressed in radians.
|
|
|
A random scalar or array with values from 0 to range. The seed value is used as the seed for the random numbers. If no seed argument is specified, the object ID is used as the seed, and a different random array is returned for each object.
|
The following table summarizes the AVS/Express logical functions..
Table N-2
|
|
|
|
|
Logical and; equivalent to arg1 & arg2 & ...
|
|
|
Logical or; equivalent to arg1 | arg2 | ...
|
|
|
Logical exclusive or; equivalent to ((arg1 ^ arg2) ^ ...)
|
The following table summarizes the AVS/Express array functions.
Table N-3
|
|
|
|
|
Returns the total number of elements in arg.
|
|
|
Returns the dimensions of the array specified in arg.
|
|
|
Combines the arrays arg1, arg2, ... The arrays must have the same number of dimensions ( n) and the same size in the first n-1 dimensions. The function returns an n-dimension array, whose size in the first n-1 dimensions is the same as that of the source arrays, and the size of whose nth dimension is the sum of the sizes of the source arrays' nth dimensions.
|
|
|
Concatenates arg1, arg2, ... to create a single array with dimensions equal to the sum of dimensions of all the arrays.
|
|
|
Returns the index of the current object in the array of groups specified by arg. This function must be used by an object that is in a group in the array of groups specified by arg. It is used to create connections between objects in two parallel arrays of groups.
|
init_array( size,start,end)
|
Returns a one-dimensional array of size elements that range in ascending order from start to end.
|
|
|
Returns the magnitude (square root of the sum of squares) of each column in arg. The function returns an n-1 dimension array, where n is the number of dimensions in arg.
|
max_array( arg) max_array( arg, f, v)
|
Returns in a one-dimensional array the maximum value found in each column in the array arg. If the array has null values, you can include two additional arguments:
-- Set the flag f to 1 to indicate that the function should ignore null values.
-- Set v to the number that represents a null value.
By default, f is 0, meaning that the function operates on all array values.
|
min_array( arg) min_array( arg, f, v)
|
Returns in a one-dimensional array the minimum value found in each column in the array arg. If the array has null values, you can include two additional arguments:
-- Set the flag f to 1 to indicate that the function should ignore null values.
-- Set v to the number that represents a null value.
By default, f is 0, meaning that the function operates on all array values.
|
|
|
Returns the product of all of the elements in arg1, arg2, ... .
|
|
|
Returns the sum of all of the elements in arg1, arg2, ... .
|
|
|
Creates a new array, each element of which is a sum of all the previous elements in the original array.
|
Note the following:
- Usage - Functions returning a single value can be used in a scalar or array expression. Functions returning an array can be used only in an array expression.
- Arguments - Arguments are typically array expressions, such as array literals or references to array objects. But they can be scalar expressions, in which case they are treated as one-element arrays.
- Presenting scalars as an array literal - With an array literal, you can present a set of scalar expressions as a single array, which you can then use as an argument in an array function like max_array.
-> int x = 10;
-> int y = 20;
-> int z = 3;
-> int a = max_array ({x, y, z});
-> $int a
20
-> float x[2][3] = {{1,2,3},{4,5,6}};
-> float y[2][2] = {{7,8},{9,10}};
-> int a => array_size(x);
-> $int a
6
-> float a[] => combine_array(x,y);
-> $get_array a
{{1,2,3,7,8},{4,5,6,9,10}}
-> $array_dims a
ndim=2 [2][5]
-> int a1[3]={1,2,3};
-> int a2[3]={5,6,7};
-> int a3[3]={8,9,10};
-> int c[] => concat_array(a1,a2,a3);
-> $get_array c
{1,2,3,5,6,7,8,9,10}
-> float a[] => magnitude(x);
-> $get_array a
{3.74166,8.77496}
-> float a => max_array(x);
-> $real a
6.000000
-> float a => prod(x,y)
-> $real a
3628800.000000
int a[4]={1,2,3,4};
int b[] => sum_array(a);
$get_array b
{1,3,6,10}
The following table summarizes miscellaneous AVS/Express functions.
Table N-4
|
|
|
|
|
Instructs AVS/Express to cache the results of the enclosed expression so that the expression is recalculated only when necessary
|
|
|
Returns the current index of an array of groups
|
|
|
Defines an object with all the subobjects of two or more other objects
|
|
|
Returns a string value that contains the name of a referenced object
|
|
|
Returns an array of strings obtained by splitting a referenced string object into pieces
|
|
|
Provides string formatting functionality like that of the standard C routine printf
|
switch( index,arg1,arg2...)
|
Returns the argument indicated by the index argument; for example, returns arg4 if index is 4
|
The cache function instructs AVS/Express to cache the result of the enclosed expression, so that the expression is recalculated only if the objects referenced in the expression have changed.
When an object is connected to an expression, AVS/Express by default recomputes an expression whenever the object's value is requested.
Caching involves a trade-off between the time required to recalculate an expression and the space required to cache the result.
For example, you define a group whose method creates a large array of float data, stored in subobject out. You also define an object called max and connect it to the maximum value in out:
group create_data {
float+write out[];
method_upd func = "create_data";
};
float max => max_array(out);
By default, every time you request max's value, AVS/Express recalculates the expression, even if out has not changed. To prevent this, use the cache function:
float max => cache(max_array(out));
The cache function caches the result of an expression so that it is recomputed only when objects referenced by the expression have changed.
index_of (
group_array_object)
The index_of function returns the current index of an array of groups. You can use index_of in the value expression for a subobject of the array of groups.
For example:
group foo[3] {
int a=> index_of(foo);
};
!foo[0] {
$int a
0
};
!foo[1] {
$int a
1
};
merge (
object1,
object2, ...)
The merge function defines an object that has all of the subobjects of object1 combined with the subobjects of object2.... etc. This is not a static merge like the "+" operator but continues to get changes made to its object arguments.
If subobjects of the same name exist in more than one object argument, the merge object uses the subobject found in the first object in the argument list.
For example:
-> group a {
-> int sub1 = 10, sub2 = 20;
-> };
-> group b {
-> int sub2 = 30, sub3 = 40;
-> };
-> group &c => merge(a,b);
-> c {
-> $print sub1
int sub1 = 10;
-> $print sub2
int sub2 = 20;
-> $print sub3
int sub3 = 40
The name_of function returns a string value containing the name of the object object. For example:
-> group grp1 {
-> string str1 => name_of(<-);
-> $str str1
grp1
str_array(
string_object, delimiter)
The str_array function returns an array of strings that are obtained by splitting up string_object into pieces delimited by the first character of the string value of the delimiter argument.
For example:
-> string a = "One;Two;Three";
-> string b[3] = str_array(a, ";");
-> $print b
string b[3] = {"One","Two","Three"};
str_format(
format, arg1, arg2, ..., argn)
The str_format function provides string formatting functionality like the standard C routine printf. The format parameter is a string defined just like the format parameter to printf. The format parameter contains two types of objects: characters that are placed directly in the string's value, and conversion specifications of the form:
%[field width].[precision][conversion character]
The nth argument after format corresponds to the nth conversion specification in the format string. The data type of the argument is determined by the data type required by the conversion character.
If any one of the arguments after format is an array, this function provides an array of strings where the format string is applied to each value in the array individually. Otherwise, this function returns a scalar string value.
This function does not interpret the %n$ syntax of the printf function.
For example:
-> string v1 => str_format("number: %5d %s",3,"foobar");
-> $str v1
number: 3 foobar
-> string arr1[] => str_format("%10.3f",{1.2345,2.34,4.56});
-> string arr2[3] = arr1;
-> $print arr2
string arr2[3] = {" 1.234"," 2.340"," 4.560"};
switch(
index,
arg1,
arg2...)
The switch function returns one of its arguments depending on the value of index. If index is 1, switch returns the first argument. If index is 2, switch returns the second argument, and so on. If index is 0 or greater than the total number of arguments, a null value is returned.
When used as a primitive, switch's first subobject specifies the index; subsequent subobjects specify the arguments. For illustration of such usage, see the following example.
//
// Use switch as a primitive.
// Start by defining an index variable.
//
int i;
//
// Define a switch.
//
switch x {
int index => i;
int val1 = 10;
int val2 = 20;
};
// Define an integer and connect it to switch x.
//
int result => x;
