SDL::OpenGL::Cg - SDL::OpenGL interface to the Cg shader language.
See the examples in 'test-scripts'.
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
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.
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
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
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
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
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
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
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
Usage : my $err = cgGetError(); Purpose : Obtaining the error code of the last error which occured. Returns : The error code. Throws : None Comments :
See Also :
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 :
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
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
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
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
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
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
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
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.
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.
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.
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!
Paul Golds
[email protected]
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.
perl(1), SDL, SDL::OpenGL