> # NAME

> cgConnectParameter - connect two parameters

> # SYNOPSIS

>       #include <Cg/cg.h>

>       void cgConnectParameter( CGparameter from,
>                                CGparameter to );

> # PARAMETERS

> from

>   The source parameter.

> to

>   The destination parameter.

> # RETURN VALUES

> None.

> # DESCRIPTION

> cgConnectParameter connects a source (from) parameter to a destination (to) parameter. The resulting connection forces the value and variability of the destination parameter to be identical to the source parameter. A source parameter may be connected to multiple destination parameters but there may only be one source parameter per destination parameter.

> cgConnectParameter may be used to create an arbitrarily deep tree. A runtime error will be thrown if a cycle is inadvertently created. For example, the following code snipped would generate a CG_BIND_CREATES_CYCLE_ERROR :

>       CGcontext context = cgCreateContext();
>       CGparameter Param1 = cgCreateParameter(context, CG_FLOAT);
>       CGparameter Param2 = cgCreateParameter(context, CG_FLOAT);
>       CGparameter Param3 = cgCreateParameter(context, CG_FLOAT);

>       cgConnectParameter(Param1, Param2);
>       cgConnectParameter(Param2, Param3);
>       cgConnectParameter(Param3, Param1); /* This will generate the error */

> If the source type is a complex type (e.g., struct, or array) the topology and member types of both parameters must be identical. Each correlating member parameter will be connected.

> Both parameters must be of the same type unless the source parameter is a struct type, the destination parameter is an interface type, and the struct type implements the interface type. In such a case, a copy of the parameter tree under the source parameter will be duplicated, linked to the orignal tree, and placed under the destination parameter.

> If a an array parameter is connected to a resizable array parameter the destination parameter array will automatically be resized to match the source array.

> The source parameter may not be a program parameter. Also the variability of the parameters may not be CG_VARYING.

> # EXAMPLES

>       CGparameter TimeParam1 = cgGetNamedParameter(program1, "time");
>       CGparameter TimeParam2 = cgGetNamedParameter(program2, "time");
>       CGparameter SharedTime = cgCreateParameter(context,
>                                                  cgGetParameterType(TimeParam1));

>       cgConnectParameter(SharedTime, TimeParam1);
>       cgConnectParameter(SharedTime, TimeParam2);

>       cgSetParameter1f(SharedTime, 2.0);

> # ERRORS

> CG_INVALID_PARAM_HANDLE_ERROR is generated if either of the from or to parameters are invalid handles.

> CG_PARAMETER_IS_NOT_SHARED is generated if the source parameter is a program parameter.

> CG_BIND_CREATES_CYCLE_ERROR is generated if the connection will result in a cycle.

> CG_PARAMETERS_DO_NOT_MATCH_ERROR is generated if the parameters do not have the same type or the topologies do not match.

> CG_ARRAY_TYPES_DO_NOT_MATCH_ERROR is generated if the type of two arrays being connected do not match.

> CG_ARRAY_DIMENSIONS_DO_NOT_MATCH_ERROR is generated if the dimensions of two arrays being connected do not match.

> # HISTORY

> cgConnectParameter was introduced in Cg 1.2.

> # SEE ALSO

> cgGetConnectedParameter, cgGetConnectedToParameter, cgDisconnectParameter