diff options
| author | Kenneth Russel <[email protected]> | 2006-02-05 18:09:23 +0000 |
|---|---|---|
| committer | Kenneth Russel <[email protected]> | 2006-02-05 18:09:23 +0000 |
| commit | 875652cab75b68ac30b9b1cc81ee62f7ff1e165d (patch) | |
| tree | 7e6d85cee9453f6864d9067ac1c90213244ab4e0 /doc | |
| parent | 98da87017cb72785ca13f5b0657ce2c5d8a067c3 (diff) | |
Intermediate checkin for FBO support in Java2D/JOGL bridge. Needed to
keep track of server-side OpenGL objects, like textures and display
lists, created by the end user to preserve the illusion of independent
contexts even though they will all share textures and display lists
with the Java2D OpenGL context in order to access its FBO. Added
GLObjectTracker class to track creation and destruction of these
objects and to support cleanup when the last referring context has
been destroyed. Modified GLContextShareSet to create and install
GLObjectTrackers when necessary and GLContext to ref and unref tracker
appropriately. Changed GlueGen's JavaPrologue and JavaEpilogue
directives (and their documentation) to perform argument name
substitution. Wrote documentation section on argument name
substitution and specified behavior for primitive arrays (converts to
string "array_name, array_name_offset" in substitution). Rephrased
GlueGen's RangeCheck directives in terms of JavaPrologue directives
and deleted old specialized code. Fixed bug in handling of VBO support
in GLConfiguration when JavaPrologue was present for affected
functions. Added JavaPrologue and JavaEpilogue directives to all
existing OpenGL routines creating server-side objects (though it's
possible some were missed) to call GLObjectTracker when necessary.
Added RangeCheck directives for these routines as well. Worked around
bug in JOGL demos where shutdownDemo() was being called more than once.
git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/../svn-server-sync/gluegen/trunk@13 a78bb65f-1512-4460-ba86-f6dc96a7bf27
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/manual/index.html | 102 |
1 files changed, 86 insertions, 16 deletions
diff --git a/doc/manual/index.html b/doc/manual/index.html index 2e4ed84..cbeea8e 100755 --- a/doc/manual/index.html +++ b/doc/manual/index.html @@ -1,3 +1,9 @@ +<HTML> +<HEAD> +<TITLE>GlueGen Manual</TITLE> +</HEAD> +<BODY> + <H1>GlueGen Manual</H1> <H2> Table of Contents </H2> @@ -23,6 +29,7 @@ Chapter 2 - Using GlueGen <LI> <a href = "#SecStub">Stub Headers</a> <LI> <a href = "#Sec32">32- and 64-bit Considerations</a> <LI> <a href = "#SecOpaque">Opaque Directives</a> +<LI> <a href = "#SecSubstitution">Argument Name Substitution</a> <LI> <a href = "#SecConfiguration">Configuration File Directives</a> <UL> <LI> <a href = "#SecJavaEmitter">JavaEmitter Configuration</a> @@ -755,6 +762,63 @@ type to a Java long: Now HANDLEs are exposed to Java as longs as desired. A similar technique is used to expose XIDs on the X11 platform as Java longs. +</P> + + +<H3><a name="SecSubstitution">Argument Name Substitution</a></H3> + +<P> + +Certain configuration file directives allow the insertion of Java or C +code at various places in the generated glue code, to both eliminate +the need to hand-edit the generated glue code as well as to minimize +the hand-writing of glue code, which sidesteps the GlueGen process. In +some situations the inserted code may reference incoming arguments to +compute some value or perform some operation. Examples of directives +supporting this substitution include <a +href="#ReturnValueCapacity">ReturnValueCapacity</a> and <a +href="#ReturnedArrayLength">ReturnedArrayLength</a>. + +</P> +<P> + +The expressions in these directives may contain Java MessageFormat +expressions like <code>{0}</code> which refer to the incoming argument +names to the function. <code>{0}</code> refers to the first incoming +argument. + +</P> +<P> + +Strongly-typed C primitive pointers such as <code>int*</code>, which +ordinarily expand to overloaded Java methods taking +e.g. <code>int[]</code> as well as <code>IntBuffer</code>, present a +problem. The expansion to <code>int[] arr</code> also generates an +<code>int arr_offset</code> argument to be able to pass a pointer into +the middle of the array down to C. To allow the same MessageFormat +expression to be used for both cases, the subsitution that occurs when +such a primitive array is referenced is the string <code>arr, +arr_offset</code>; in other words, the subtituted string contains a +comma. This construct may be used in the following way: the code being +manually inserted may itself contain a method call taking +e.g. <code>{3}</code> (the incoming argument index of the primitive +array or buffer). The user should supply two overloaded versions of +this method, one taking a strongly-typed Buffer and one taking e.g. an +<code>int[] arr</code> and <code>int arr_offset</code> argument. The +implementation of <code>RangeCheck</code>s for primitive arrays and +strongly-typed buffers uses this construct. + +</P> +<P> + +It should be noted that in the autogenerated C code the offset +argument is expressed in bytes while at the Java level it is expressed +in elements. Most uses of GlueGen will probably not have to refer to +the primitive array arguments in C code so this slight confusion +should be minor. + +</P> + <H3><a name="SecConfiguration">Configuration File Directives</a></H3> @@ -1047,10 +1111,11 @@ href="#ImplJavaClass">ImplJavaClass</a>. (optional) Adds the specified code as an epilogue in the Java method for the specified C function; this code is run after the underlying C function has been called via the native method but before any result -is returned. No transformations are currently performed on this code, -unlike in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a> -and other directives. See also <a -href="#JavaPrologue">JavaPrologue</a>. +is returned. As in the <a +href="#ReturnedArrayLength">ReturnedArrayLength</a> and other +directives, <a href="#SecSubstitution">argument name +substitution</a> is performed on MessageFormat expressions in the +specified code. See also <a href="#JavaPrologue">JavaPrologue</a>. <dt><strong><a name="JavaOutputDir">JavaOutputDir</a></strong> @@ -1068,10 +1133,11 @@ defaults to the current working directory. (optional) Adds the specified code as a prologue in the Java method for the specified C function; this code is run before the underlying C -function is called via the native method. No transformations are -currently performed on this code, unlike in the <a +function is called via the native method. As in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a> and other -directives. See also <a href="#JavaEpilogue">JavaEpilogue</a>. +directives, <a href="#SecSubstitution">argument name +substitution</a> is performed on MessageFormat expressions in the +specified code. See also <a href="#JavaEpilogue">JavaEpilogue</a>. <dt><strong><a name="ManuallyImplement">ManuallyImplement</a></strong> @@ -1160,9 +1226,8 @@ that should be expressed in terms of a number of bytes rather than a number of elements, see the <a href="#RangeCheckBytes">RangeCheckBytes</a> directive. As in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a> and other -directives, MessageFormat expressions such as "{0}" are replaced with -the corresponding incoming argument name, where the first incoming -argument is index 0. +directives, <a href="#SecSubstitution">argument name substitution</a> +is performed on MessageFormat expressions. <dt><strong><a name="RangeCheckBytes">RangeCheckBytes</a></strong> @@ -1171,7 +1236,8 @@ argument is index 0. (optional) Same as the <a href="#RangeCheck">RangeCheck</a> directive, but the specified expression is treated as a minimum number of bytes -remaining rather than a minimum number of elements remaining. +remaining rather than a minimum number of elements remaining. This +directive may not be used with primitive arrays. <dt><strong><a name="RenameJavaMethod">RenameJavaMethod</a></strong> @@ -1203,7 +1269,8 @@ href="#ImplJavaClass">ImplJavaClass</a> directives. expression with MessageFormat specifiers such as "{0}". These specifiers will be replaced in the generated glue code with the incoming argument names where the first argument to the method is -numbered 0. <br> +numbered 0. See the section on <a href="#SecSubstitution"> argument +name substitution</a>.<br> (optional) For a function returning a compound C pointer type such as an <code>XVisualInfo*</code>, indicates that the returned pointer is @@ -1235,8 +1302,8 @@ subclass wrapping a C primitive pointer such as <code>char*</code> or <code>float*</code> being returned from a C function. Typically necessary in order to properly use such pointer return results from Java. As in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a> -directive, argument name substitution is performed on MessageFormat -expressions such as "{0}" where the first argument is index 0. +directive, <a href="#SecSubstitution">argument name substitution</a> +is performed on MessageFormat expressions. <dt><strong><a name="ReturnValueLength">ReturnValueLength</a></strong> @@ -1253,8 +1320,8 @@ directive handles boxing of individual elements of the array (which are pointers) in to the Java class which wraps that C struct type. See the (FIXME) examples for a concrete example of usage. As in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a> directive, -argument name substitution is performed on MessageFormat expressions -such as "{0}" where the first argument is index 0. +<a href="#SecSubstitution">argument name substitution</a> is performed +on MessageFormat expressions. <dt><strong><a name="RuntimeExceptionType">RuntimeExceptionType</a></strong> @@ -1538,3 +1605,6 @@ despite the fact that it has an associated function pointer typedef in the header. </dl> + +</BODY> +</HTML> |