diff options
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> |