CgToGLSL conditioner

From COLLADA Public Wiki
Jump to navigation Jump to search
Conditioner information
  • Name: CgToGLSL
  • Purpose: COLLADAFX profile conversion
  • Last updated: 2007-12-03
  • Current version: 1.0
  • Status: released
  • Created by: Heinrich Fink
  • Contact for technical issues: heinrich.fink@chello.at

Download

This article is part of the COLLADA conditioners directory
Adding to the conditioners directory

Description

This conditioner converts the profile_CG of a COLLADAFX Effect into a profile_GLSL version. As those two profiles are very similar, most of the elements are converted without any complications. The main work is done by compiling the Cg sources (CGFX and separated Cg) with NVIDIA's CG-Compiler using the GLSL vertex and fragment profiles (available since CgToolkit 1.5). Afterwards the conditioner manipulates the COLLADA-file and the compiled GLSL-sources in a way you end up with a complete and fully compliant profile_GLSL version of your favorite Cg-Effect. The compiled GLSL source-code is NOT human-readable anymore. But that's not even necessary! The interface of the COLLADAFX profile_GLSL tells you exactly how to use those shaders and bind certain values to render a desired material.

During the conversion-process the conditioner performs several type compatibility checks (for example you cannot bind a COLLADA-Type float4x4 parameter to a Cg parameter float). The conversion also stops if profile_CG-elements break the rules of the COLLADA Schema.

As the current COLLADA scheme provides GLSL 110 only, the conditioner breaks on all profile_CG elements that are NOT compatible with GLSL 110 types. See here for any incompatibilities between profile_CG and profile_GLSL.

Feature list

  • Complete Conversion of domProfile_CG into domProfile_GLSL
  • Typechecks between domProfile_CG and the loaded Cg-Program
  • Manipulation of the compiled GLSL code to be used outside the Cg-Runtime
  • float4x4 semantics processing (see here)
  • Transponation of matrices during conversion
    • This has to be done if you want to use the compiled GLSL-source outside the Cg-Runtime (GLSL has column-major, Cg has row-major matrix format).

Availability

The CgToGLSL conditioner is available for Windows and Mac OS X as a Refinery plugin and a standalone CLI tool. Please read install_notes.txt in the binary packages (available here) for further installation instructions. See BUILD.txt for build instruction on both platforms of the source-package.

Usage

Conditioner options

You can set the following options of the conditioner either via the Refinery GUI, or as a commandline option.

Type 

./CgToGLSL --help

for command line parameters.

GLSL: embed src

If set to "true" the generated GLSL sources are written into the <code> - element of profile_GLSL. Otherwise the sources are written as *.glsl files into the "GLSL: Out Dir"

GLSL: relative path

Refinery: If enabled, the path to the GLSL shader sources is set relative to the directory of the INPUT COLLADA-file (this is due to limitations of the COLLADA Refinery Plugin API)
CLI version: If enabled, the path to the GLSL shader sources is set relative to OUTPUT Collada file.

GLSL: Overwrite

If enabled, existing *.glsl files are overwritten, otherwise they are subsequently indexed. This applies only, if 'GLSL: embed src' is disabled.

GLSL: 4x4 semantics

If enabled, float4x4 params of profile_CG are checked against known matrix-semantics and eventually replaced with the corresponding GLSL intrinsic keyword. See here for possible semantics.

CG: Remove profiles

Enable to output a COLLADA-file with pure GLSL profiles, all profile_CG elements are stripped.

GLSL: Transpose Matrices

Enable to transpose all matrices of shader-source in the resulting GLSL translation. Note this is necessary to have a working GLSL representation of your Cg-Source, though you also might simply pass transposed matrices in your client app to the GLSL runtime and leave this option disabled.

GLSL: log to shdr-file

If enabled log-messages are appended as comments to the shader source. This is useful for detecting errors during the conversion process.

GLSL: Out Dir

Set a directory to write the GLSL- sources into.

CG CFX: Platform string

Set the platform string of the profile_CG's you want to convert into GLSL. This defaults to "PC-OGL".

CG Compiler options

Set additional compiler options being passed to NVIDIAs CgC compiler.

Write Logfile

Enable to write a detailed logfile of the conversion process. By default the logfile is placed in the current working directory (in the Refinery into the directory of the INPUT Collada file).

Halt on Error

When disabled the pipeline is not being interrupted and the DAE-data passed unmodified to the next conditioner when encounting an error during conversion.

float4x4 semantics

If "GLSL: 4x4 semantics" is turned on, the conditioner replaces parameters that have a known float4x4 semantic with the corresponding GLSL intrinsic keyword. The following list is compatible with those semantics applied in COLLADAMAYA and mentioned in Cg User Manual : 

GLSL KEYWORD <=>CG SEMANTICS

gl_ModelViewMatrix <=> state.matrix.modelview[0], WORLDVIEW
gl_ModelViewMatrixInverse <=> state.matrix.inverse.modelview[0], WORLDVIEWI, WORLDVIEWINVERSE
gl_ModelViewMatrixTranspose	<=> state.matrix.transpose.modelview[0]
gl_ModelViewMatrixInverseTranspose <=> state.matrix.invtrans.modelview[0], WORLDVIEWIT, WORLDVIEWINVERSETRANSPOSE
gl_ProjectionMatrix <=> state.matrix.projection, PROJECTION
gl_ProjectionMatrixInverse <=> state.matrix.inverse.projection, PROJECTIONI, PROJECTIONINVERSE
gl_ProjectionMatrixTranspose <=> state.matrix.transpose.projection
gl_ProjectionMatrixInverseTranspose <=> state.matrix.invtrans.projection, PROJECTIONIT, PROJECTIONINVERSETRANSPOSE
gl_ModelViewProjectionMatrix <=>state.matrix.mvp, VIEWPROJ, WORLDVIEWPROJECTION, VIEWPROJECTION
gl_ModelViewProjectionMatrixInverse <=> state.matrix.inverse.mvp, WORLDVIEWPROJECTIONINVERSE
gl_ModelViewProjectionMatrixTranspose <=> state.matrix.transpose.mvp
gl_ModelViewProjectionMatrixInverseTranspose <=> state.matrix.invtrans.mvp, WORLDVIEWPROJECTIONINVERSETRANSPOSE

Incompatible Cg Elements

Following parameter types will break the conversion process in the current version of the conditioner: 

Half Half1 Half1x1 Half1x2 Half1x3 Half1x4 Half2 Half2x1 Half2x2 Half2x3 Half2x4 Half3 Half3x1 Half3x2 Half3x3 Half3x4 Half4 Half4x1 Half4x2 Half4x3 Half4x4 
Fixed Fixed1 Fixed1x1 Fixed1x2 Fixed1x3 Fixed1x4 Fixed2 Fixed2x1 Fixed2x2 Fixed2x3 Fixed2x4 Fixed3 Fixed3x1 Fixed3x2 Fixed3x3 Fixed3x4 Fixed4 Fixed4x1 Fixed4x2 Fixed4x3 Fixed4x4 
Bool1x1 Bool1x2 Bool1x3 Bool1x4 Bool2x1 Bool2x2 Bool2x3 Bool2x4 Bool3x1 Bool3x2 Bool3x3 Bool3x4 Bool4x1 Bool4x2 Bool4x3 Bool4x4 
Int1x1 Int1x2 Int1x3 Int1x4 Int2x1 Int2x2 Int2x3 Int2x4 Int3x1 Int3x2 Int3x3 Int3x4 Int4x1 Int4x2 Int4x3 Int4x4
Float1x2 Float1x3 Float1x4 Float2x1 Float2x3 Float2x4 Float3x1 Float3x2 Float3x4 Float4x1 Float4x2 Float4x3

Also the following pure domProfile_CG elements will break the conversion:

<usertype> under <newparam> or <setparam> or <array>

<connect_param> under <array>

Revision History

Ver. 1.0 released 2007-12-03

  • New features
    • Xcode projects for Mac OS X (>10.4)
    • Build configurations for a standalone-version of CgToGLSL.
    • Added haltOnError-option. When disabled the pipeline is not being interrupted and the DAE-data passed unmodified to the next conditioner.
    • Improved log-messages which are now optionally being written to an external logfile (CgToGLSL_Log.txt).
    • Cg compiler options found in profile_CG are now taken care of.
    • Transposing matrices in Cg-code before translation is now done via swapping mul-arguments where possible.
  • bugfixes:
    • Removed "skip <bind>-array validation"-option. COLLADAMAYA now correctly exports the <bind>-array.
    • Fixed the unique identifier for one CgToGLSL-translation entity.
      • If the <include> or <code> - element resides on <technique>-level the unique-identifier-string now also contains the mandatory <technique>-sid.

Ver. 0.9 BETA released 2007-02-01

Initial release

Known issues and bugs

NVIDIA CGC 2.0 BETA compiler issues

At the time of writing the 2.0 Beta version of NVIDIAs Cg Compiler does not pass GLSL intrinsic float4x4 variables like gl_ModelViewMatrix. This way, the conversion process would not succeed. Until this issue is fixed you have to use the Cg 1.5 Toolkit with the CgToGLSL conditioner.

Note for Mac OS X Leopard: NVIDIA has not released a working installer for the Cg 1.5 Toolkit on Leopard. Instead you can simply download this archive, extract, and copy Cg.framework to /Library/Frameworks.

Retrieved from "http://www.khronos.org/collada/wiki_collada/index.php?title=CgToGLSL_conditioner&oldid=4752"