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

> ## Name

> cgCreateState - create a state definition

> ## Synopsis

>     #include <Cg/cg.h>

>     CGstate cgCreateState( CGcontext context,
>                            const char * name,
>                            CGtype type );

> ## Parameters

> context
>   The context in which to define the new state.
> name
>   The name of the new state.
> type
>   The type of the new state.

> ## Return Values

> Returns a handle to the newly created CGstate.

> Returns NULL if there is an error.

> ## Description

> cgCreateState adds a new state definition to the context. When a CgFX file is added to the context, all state assignments in the file must have already been defined via a call to cgCreateState or cgCreateArrayState.

> Applications will typically call cgSetStateCallbacks shortly after creating a new state with cgCreateState.

> ## Examples

> Example callback functions for a state to register:

>     CGbool foo_set( CGstateassignment sa )
>     {
>       int nVals = 0;
>       const CGbool *val = cgGetBoolStateAssignmentValues( sa, &nVals );
>       printf( "\nFooState set called with value %d.\n", *val );
>       return CG_TRUE;
>     }

>     CGbool foo_reset( CGstateassignment sa )
>     {
>       printf( "\nFooState reset called.\n" );
>       return CG_TRUE;
>     }

>     CGbool foo_validate( CGstateassignment sa )
>     {
>       printf( "FooState validate called.\n" );
>       return CG_TRUE;
>     }

> Registering the state:

>     // Create and register new state FooState
>     CGstate fooState = cgCreateState( myCgContext, "FooState", CG_BOOL );
>     cgSetStateCallbacks( fooState, foo_set, foo_reset, foo_validate );

> ## Errors

> CG_INVALID_CONTEXT_HANDLE_ERROR is generated if context is not a valid context.

> CG_INVALID_PARAMETER_ERROR is generated if name is NULL or not a valid identifier, or if type is not a simple scalar, vector, or matrix-type. Array-typed state should be created with cgCreateArrayState.

> ## History

> cgCreateState was introduced in Cg 1.4.

> ## See Also

> cgCreateArrayState, cgGetStateContext, cgGetStateName, cgGetStateType, cgIsState, cgSetStateCallbacks, cgGLRegisterStates, cgD3D9RegisterStates, cgCreateContext