cgConnectParameter
Keywords: cgConnectParameter, NVIDIA, NVIDIA Cg Toolkit, Cg Toolkit, Shader, Shader Programming, GPU Shader Programming, GPU Program

> ## 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 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_ERROR 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