OMset_array

Synopsis

int OMset_array (
OMobj_id object_id,
int type,
char *array_pointer,
int size,
int mode );

int OMXobj::set_array (
int type,
char *array_pointer,
int size,
int mode = OM_SET_ARRAY_COPY )

Description

OMset_array sets the value of an array object; i.e., all elements in the array.

This routine cannot be used for objects of type string or ptr.

You use OMset_array when the calling process has already created an array and needs to set the array object to that array. If the dimensions of the array are defined before you need to access the array, you may find it easier to use the routines: OMret_array_ptr , OMret_typed_array_ptr or OMget_array . These routines can be used to get a pointer to the array which you can then read, write or read and write. The OMset_array routine can only be used for write-only operations.

Arguments

object_id

The id of an array object.

type

The integer code for the array's data type. type must be compatible with the object's type. For example, if the object is integer, then the array could be any numeric type; AVS/Express performs any necessary conversion.

AVS/Express provides the following symbolic constants, defined in <avs/om.h>:

Type	Meaning
OM_TYPE_CHAR	Character
OM_TYPE_BYTE	Byte
OM_TYPE_SHORT	Short integer
OM_TYPE_INT	Integer
OM_TYPE_FLOAT	Single-precision floating-point
OM_TYPE_DOUBLE	Double-precision floating-point

array_pointer

The address of the array being written.

size

The total number of values in the array.

The array's length should equal the size of the array object. In the following example, object myarray's size is 300, the product of each dimension, so the array that is written should contain 300 values and length should equal 300:

int myarray[20][5][3];

The target object can have at most one dimension that does not specify a size. For example, if myarray is defined as follows:

int myarray[];

then the array can be any size.

If the target object is multidimensional and one of the dimensions does not specify a size, then the array's total size must be a multiple of the sizes specified. For example, if myarray is defined as follows:

int myarray[3][2][];

then the array's size must be a multiple of 6.

mode

How AVS/Express should set the array. Specify one of the following symbolic constants:

Mode	Meaning
OM_SET_ARRAY_COPY	Copy the specified array into the Object Manager. The array defined by the array_pointer argument is not touched by AVS/Express and continues to be valid after the call.
OM_SET_ARRAY_STATIC	If possible, do not copy the array. Instead, set the object's array pointer to array_pointer . AVS/Express copies the array anyway if the function is running in an external process or if data-type conversion is required. AVS/Express does not manage the array. You must ensure that the array is valid for the life of the object or until the object replaces the array with another call to OMset_array. AVS/Express will not free the array in this case.
OM_SET_ARRAY_FREE	If possible, do not copy the array. Instead, set the object's array pointer to array_pointer . AVS/Express copies the array anyway if the function is running in an external process or if data-type conversion is required. AVS/Express manages the array, and will determine when the array can be freed. You should not free the array yourself. The array will not be valid after this call unless you allocate it with ARRalloc and use the routine ARRincr_refcnt on the result before calling OMset_array. You must allocate the array either with the C library routine malloc or the AVS/Express routine ARRalloc.

Returned value

The status code (see Return Status ).