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
    the cgGetConnectedParameter manpage, the cgGetConnectedToParameter
    manpage, the cgDisconnectParameter manpage

