cgGetParameterValue(3)

NAME
cgGetParameterValue - get the value of any numeric parameter

SYNOPSIS
  #include <Cg/cg.h>
  /* TYPE is int, float, or double */
  int cgGetParameterValue{ifd}{rc}( CGparameter param,
                                    int nelements,
                                    TYPE * v );

PARAMETERS
The program parameter whose value will be retrieved. The number of elements in array v. Destination buffer to which the parameter values will be written.

RETURN VALUES
Returns the total number of values written to v.

DESCRIPTION
The cgGetParameterValue functions allow the application to get the value(s) from any numeric parameter or parameter array. The value(s) are returned in v.

The given parameter must be a scalar, vector, matrix, or a (possibly multidimensional) array of scalars, vectors, or matrices.

There are versions of each function that return int, float or double values signified by i, f or d in the function name.

There are versions of each function that will cause any matrices referenced by param to be copied in either row-major or column-major order, as signified by the r or c in the function name.

For example, cgGetParameterValueic retrieves the values of the given parameter using the supplied array of integer data, and copies matrix data in column-major order.

The size of v is passed as nelements. If v is smaller than the total number of values in the given source parameter, CG_NOT_ENOUGH_DATA_ERROR is generated.

The total number of values in a parameter, ntotal, may be computed as follow:

    int nrows = cgGetParameterRows(param);
    int ncols = cgGetParameterColumns(param);
    int asize = cgGetArrayTotalSize(param);
    int ntotal = nrows*ncols;
    if (asize > 0) ntotal *= asize;

Note: Previous releases of Cg allowed you to store more values in a parameter than indicated by the parameter's type. For example, one could use cgGLSetParameter4f to store four values into a parameter of type CG_FLOAT (not CG_FLOAT4). All four values could later be retrieved using a get call which requested more than one value. However, this feature conflicts with the GLSL approach and also leads to issues with parameters mapped into BUFFERS. Therefore, beginning with Cg 2.0 any components beyond the number indicated by the parameter type are ignored.

EXAMPLES
to-be-written

ERRORS
CG_INVALID_PARAM_HANDLE_ERROR is generated if param is not a valid parameter.

CG_INVALID_POINTER_ERROR is generated if v is NULL.

CG_NOT_ENOUGH_DATA_ERROR is generated if nelements is less than the total size of param.

CG_NON_NUMERIC_PARAMETER_ERROR is generated if param is of a non-numeric type.

HISTORY
The cgGetParameterValue functions were introduced in Cg 1.4.

SEE ALSO
cgGetParameterRows, cgGetParameterColumns, cgGetArrayTotalSize, cgGetParameterDefaultValue, cgSetParameterValue, cgGetParameterValuedc, cgGetParameterValuedr, cgGetParameterValuefc, cgGetParameterValuefr, cgGetParameterValueic, cgGetParameterValueir