From 875652cab75b68ac30b9b1cc81ee62f7ff1e165d Mon Sep 17 00:00:00 2001 From: Kenneth Russel Date: Sun, 5 Feb 2006 18:09:23 +0000 Subject: 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 --- doc/manual/index.html | 102 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 86 insertions(+), 16 deletions(-) (limited to 'doc/manual') 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 @@ + + +GlueGen Manual + + +

GlueGen Manual

@@ -23,6 +29,7 @@ Chapter 2 - Using GlueGen

Stub Headers

32- and 64-bit Considerations

Opaque Directives +

Argument Name Substitution

Configuration File Directives

JavaEmitter Configuration @@ -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. +
+ + +
Argument Name Substitution
+ +
+ +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 ReturnValueCapacity and ReturnedArrayLength. + +
+
+ +The expressions in these directives may contain Java MessageFormat +expressions like {0} which refer to the incoming argument +names to the function. {0} refers to the first incoming +argument. + +
+
+ +Strongly-typed C primitive pointers such as int*, which +ordinarily expand to overloaded Java methods taking +e.g. int[] as well as IntBuffer, present a +problem. The expansion to int[] arr also generates an +int arr_offset 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 arr, +arr_offset; 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. {3} (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 +int[] arr and int arr_offset argument. The +implementation of RangeChecks for primitive arrays and +strongly-typed buffers uses this construct. + +
+
+ +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. + +
+
Configuration File Directives
@@ -1047,10 +1111,11 @@ href="#ImplJavaClass">ImplJavaClass. (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 ReturnedArrayLength -and other directives. See also JavaPrologue. +is returned. As in the ReturnedArrayLength and other +directives, argument name +substitution is performed on MessageFormat expressions in the +specified code. See also JavaPrologue.
JavaOutputDir @@ -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 ReturnedArrayLength and other -directives. See also JavaEpilogue. +directives, argument name +substitution is performed on MessageFormat expressions in the +specified code. See also JavaEpilogue.
ManuallyImplement @@ -1160,9 +1226,8 @@ that should be expressed in terms of a number of bytes rather than a number of elements, see the RangeCheckBytes directive. As in the ReturnedArrayLength 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, argument name substitution +is performed on MessageFormat expressions.
RangeCheckBytes @@ -1171,7 +1236,8 @@ argument is index 0. (optional) Same as the RangeCheck 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.
RenameJavaMethod @@ -1203,7 +1269,8 @@ href="#ImplJavaClass">ImplJavaClass 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.
+numbered 0. See the section on argument +name substitution.
(optional) For a function returning a compound C pointer type such as an XVisualInfo*, indicates that the returned pointer is @@ -1235,8 +1302,8 @@ subclass wrapping a C primitive pointer such as char* or float* being returned from a C function. Typically necessary in order to properly use such pointer return results from Java. As in the ReturnedArrayLength -directive, argument name substitution is performed on MessageFormat -expressions such as "{0}" where the first argument is index 0. +directive, argument name substitution +is performed on MessageFormat expressions.
ReturnValueLength @@ -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 ReturnedArrayLength directive, -argument name substitution is performed on MessageFormat expressions -such as "{0}" where the first argument is index 0. +argument name substitution is performed +on MessageFormat expressions.
RuntimeExceptionType @@ -1538,3 +1605,6 @@ despite the fact that it has an associated function pointer typedef in the header. + + + -- cgit v1.2.3

GlueGen Manual

Table of Contents

Argument Name Substitution

Configuration File Directives