NAME

SDL::OpenGL::Cg - SDL::OpenGL interface to the Cg shader language.


SYNOPSIS

  See the examples in 'test-scripts'.


DESCRIPTION

This module provides an interface to the nVidia Cg GL runtime. This allows a SDL::OpenGL programmer access to the shader capabilities that many new graphics card provide.

In order to use this module you will need an installation of the Cg runtime development kit, downloadable from nVidia at http://developer.nvidia.com/object/cg_toolkit.html

NAMING CONVENTION

This module provides access to functionality provided by two different libraries, Cg and CgGL. Whilst it may be important to a C programmer which of the two libraries a given call is from, it is of no real importance to users of this module.

With this in mind, and to aid people in identifying SDL::OpenGL::Cg calls, all of the methods in this module have the prefix 'cg'. As such the Cg library's cgGetProfileString() has retained it's name whilst cgGLIsProfileSupported() has become cgIsProfileSupported().

In line with this the constants this module provides have been rationalised with the common prefix CG_, thus CG_PROFILE_FP30 has retained it's name whilst CG_GL_MODELVIEW_MATRIX has become CG_MODELVIEW_MATRIX.

Apart from this simple change all method names are identical to their C counterparts, and so the documentation on the original C version of a method should be easily found in nVidia's documentation on the Cg and CgGL libraries.

cgBindProgram

 Usage     : cgBindProgram($prog) or die ("Cannot bind program");
 Purpose   : Makes a loaded program active.
 Returns   : True if the program has been successfully bound,
             and false if it was unable to do so.
        
=head2 cgCopyProgram
 Usage     : (my $prog2 = cgCopyProgram($prog1) or die "Cannot dupe";
 Purpose   : Creates a copy of a program and adds it to the same context.
 Returns   : A copy of the program on success, or undef for failure.
 Throws    : None
 Comments  :
 See Also  : cgCompileProgram, cgDestroyProgram

cgCreateContext


 Usage     : my $context = cgCreateContext() or die "Cannot create context";
 Purpose   : Obtain a Cg context that programs can be stored in.
 Returns   : An identifier for the context, or false for failure.
 Throws    : None
 Comments  :
 See Also  : DestroyContext

cgCreateProgram

 Usage     : my $program = cgCreateProgram
               ($context, $type, $program_code, $profile, $entry, $args);
             $program or die("Cannot create program");
 Purpose   : Creates a cgShader program from a string containing source. 
 Returns   : The program itself, or undef if an error has occured.
 Throws    : None
 Comments  : Context is a CGcontext returned from CreateContext,
             Type is either SDL::OpenGL::Cg::SOURCE or
               SDL::OpenGL::Cg::Object dependant upon whether the
               shader is compiled or not.
             Program_code is the entire source code for the shader, as
               a single string.
             Entry is the name of the entry point of the shader.
             Args is an array reference containing strings which
               are passed directly to the compiler (Currently
               unimplemented).
 See Also  : cgBindProgram, cgCopyProgram, cgCreateProgramFromFile,
             cgLoadProgram

cgCreateProgramFromFile

 Usage     : my $program = cgCreateProgramFromFile
               ($context, $type, $file, $profile, $entry, $args);
             $program or die("Cannot create program");
 Purpose   : Creates a cgShader program from a file.
 Returns   : The program itself, or undef if an error has occured.
 Throws    : None
 Comments  : Context is a CGcontext returned from CreateContext,
             Type is either SDL::OpenGL::Cg::SOURCE or
               SDL::OpenGL::Cg::Object dependant upon whether the
               shader is compiled or not.
             File is the name of the file containing the shader.
             Entry is the name of the entry point of the shader.
             Args is an array reference containing strings which
               are passed directly to the compiler (Currently
               unimplemented).
 See Also  : cgBindProgram, cgCopyProgram, cgCreateProgram,
             cgLoadProgram

cgDestroyContext


 Usage     : cgDestroyContext($context) or die "Cannot destroy context";
 Purpose   : Deletes a context and all of the programs it contains.
 Returns   : True if the context has been successfully deleted,
             false if it hasn't.
 Throws    : None
 Comments  :
 See Also  : cgCreateContext

cgDisableProfile

 Usage     : cgDisableProfile(PROFILE_FP20()) or die "Cannot disable FP20";
 Purpose   : Deactivate a profile
 Returns   : True if the profile is successfully disabled, false if
             it failed for some reason
 Throws    : None
 Comments  :
 See Also  : cgEnableProfile, cgIsProfileSupported, PROFILE CONSTANTS

cgEnableProfile


 Usage     : cgEnableProfile(PROFILE_FP20()) or die "Cannot enable FP20";
 Purpose   : Activate a profile
 Returns   : True if the profile is successfully enabled, false if
             it failed for some reason.
 Throws    : None
 Comments  :
 See Also  : cgDisableProfile, cgIsProfileSupported, cgGetLatestProfile
             PROFILE CONSTANTS

cgGetError

 Usage     : my $err = cgGetError();
 Purpose   : Obtaining the error code of the last error which occured. 
 Returns   : The error code.
 Throws    : None
 Comments  :
 See Also  :

cgGetLastListing


 Usage     : my $listing = cgGetLastListing($context);
 Purpose   : Obtain the results of the last listing compiled in a given
             context, often used for working out why a shader compilation
             failed.
 Returns   : The output string, or undef if no program has been compiled
             in that context.
 Throws    : None
 Comments  :
 See Also  :

cgGetLatestProfile


 Usage     : my $profile = cgGetLatestProfile(CG_VERTEX());
 Purpose   : Obtaining the profile code of the last profile of a class
             to have been enabled.
 Returns   : The profile code.
 Throws    : None
 Comments  :

 See Also  : cgEnableProfile, cgDisableProfile

=head2 cgGetNamedParameter
 Usage     : my $param = cgGetNamedParameter($program, 'paramname');
 Purpose   : Returns a handle to a shader's parameter so it can be
             manipulated.
 Throws    : None
 Comments  :
 
 See Also  : cgSetMatrixParameterc, cgSetMatrixParameterr, cgSetParameter,
             cgSetStateMatrixParameter

cgGetProfileString

 Usage     : print "FP20 is called ",cgGetProfileString(PROFILE_FP20());
 Purpose   : Obtains the profile name associated with a particular ID.
 Returns   : The name of the profile, or undef if the ID isn't known.
 Throws    : None
 Comments  :
 See Also  : PROFILE CONSTANTS

cgIsProfileSupported


 Usage     : my $can_fp20 = cgIsProfileSupported(PROFILE_FP20);
 Purpose   : Find out whether a given profile is supported.
 Returns   : True is the profile is supported, false is it
             isn't.
 Arguments : The profile ID to be checked.
 Throws    : None
 Comments  :
 See Also  : PROFILE CONSTANTS, cgDisableProfile, cgEnableProfile

cgLoadProgram

 Usage     : cgLoadProgram($prog) or die ("Cannot load program");
 Purpose   : Loads a compiled program into memory.
 Returns   : True if the program was loaded successfully, false
             if there was an error.
 Arguments : The program to be loaded.
 Throws    : None
 Comments  : Should be called after cgCompileProgram() and before
             cgBindProgram().
 SeeAlso   : cgBindProgram, cgCompileProgram

cgSetMatrixParameterc

 Usage     : cgSetMatrixParameterc ($param, @vals) or die "Error!";
 Purpose   : Sets the value of a matrix parameter
 Returns   : True if the assignment went okay, false if there
             was an error.
 Arguments : The parameter to be set, and the values to set it to.
 Throws    : None
 Comments  : Differs from cgSetMatrixParameterr in that this version
             expects the data to be in column format.
 TODO      : Currently only sets float4x4 matrices.
 SeeAlso   : cgGetNamedParameter, cgSetMatrixParameterc, cgSetParameter,
             cgSetStateMatrixParameter

cgSetMatrixParameterr

 Usage     : cgSetMatrixParameterr ($param, @vals) or die "Error!";
 Purpose   : Sets the value of a matrix parameter
 Returns   : True if the assignment went okay, false if there
             was an error.
 Arguments : The parameter to be set, and the values to set it to.
 Throws    : None
 Comments  : Differs from cgSetMatrixParameterc in that this version
             expects the data to be in row format.
 TODO      : Currently only sets float4x4 matrices.
 SeeAlso   : cgGetNamedParameter, cgSetMatrixParameterc, cgSetParameter,
             cgSetStateMatrixParameter

cgSetStateMatrixParameter

 Usage     : cgSetStateMatrixParameter($param,
              CG_MODELVIEW_PROJECTION_MATRIX(), CG_MATRIX_IDENTITY())
              or die "Error!";
 Purpose   : To allow parameters to follow the OpenGL matrix state
             more easily, to allow setting Modelview etc. for the
             shaders.
 Returns   : True if the parameter was set without difficulty,
             undefined if a problem was experienced.
 Arguments : None
 Throws    : None
 Comments  : The second argument indicates which of OpenGL's matrices
             it should follow, and the third indicates which of the
             transforms to apply as it's copied.  See MATRIX CONSTANTS
             for more information.
 
=head2 COMPILE CONSTANTS
 Usage     : my $from_source = CG_SOURCE();
 Purpose   : To indicate whether Cg code is to be built from source
             or simply read from a compiled object.
 Returns   : The constant's ID
 Arguments : None
 Throws    : None
 Comments  : Currently includes CG_SOURCE and CG_OBJECT.
 
=head2 PROFILE CONSTANTS
 Usage     : my $fp20 = CG_PROFILE_FP20();
 Purpose   : A set of constants for the Cg profile IDs. 
 Returns   : The profile ID. 
 Argument  : None 
 Throws    : None 
 Comments  : Currently includes CG_PROFILE_FP20, CG_PROFILE_FP30,
             CG_PROFILE_VP20, CG_PROFILE_VP30, CG_PROFILE_ARBFP1
             and CG_PROFILE_ARBVP1.
 See Also   : cgEnableProfile, cgDisableProfile

MATRIX CONSTANTS

 Usage     : cgSetStateMatrixParameter($param,
              CG_MODELVIEW_PROJECTION_MATRIX(), CG_MATRIX_IDENTITY())
              or die "Error!";
 Purpse    : Identifies the different OpenGL matrices and the
             transforms that can be applied to them as they are
             transfered to the shader.
 Comments  : Matrix identification constants include:
             CG_MODELVIEW_MATRIX, CG_PROJECTION_MATRIX,
             CG_TEXTURE_MATRIX, CG_MODELVIEW_PROJECTION_MATRIX.
             Transformation identification constants include:
             CG_MATRIX_IDENTITY, CG_MATRIX_TRANSPOSE,
             CG_MATRIX_INVERSE, CG_MATRIX_INVERSE_TRANSPOSE.


USAGE


TEST SCRIPTS

The test-scripts subdirectory of the install contains a set of scripts intended to demonstrate Cg coding. Whilst at the moment these are pretty much really there more to ensure correct functioning of various parts of the module they should act to ensure the module works on a given machine.

In order to run these you should be in the test-scripts directory. Many of them use relative paths to find their shader files and so attempting to run them from another directory will result in files not being found.


BUGS

This module is currently judged to be PRE-ALPHA. Whilst I have made some efforts to make it as bug-free as possible I have no doubt that there are many bugs lurking in the undergrowth, waiting to bite the unwary.

Also, at present only a small (but important) fraction of the C API is supported. I am still working on the rest of the API and expect a complete version to be released reasonably soon.


SUPPORT


HISTORY

0.01 Tue Aug 19 Release 0.01 released. This contained a subset of the functionality of the libraries, enough only to run and control a basic shader.

0.00 Wed Jul 30 Work began!


AUTHOR

        Paul Golds      
        Molt@Simbio51s.com      


COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


SEE ALSO

perl(1), SDL, SDL::OpenGL