Functions

Functions can be declared in library definitions using public static fuction fields with no function body (similar to Haxe externs).

Example: function in library definition

class Foobar extends ammer.def.Library<"foobar"> {
  public static function hello(a:Int, b:String):Float;
}

In this example, hello is a function in the Foobar library. The function maps to the native function double hello(int a, char *b) (in C types).

All return types and argument types must be written explicitly, since Haxe type inference is not compatible with native libraries. Only a subset of Haxe types can be used. See FFI types.

Macros

The same public static function syntax can be used to declare C preprocessor macro calls, but the additional metadata @:ammer.macroCall should be applied. Macros which require unusual C syntax may cause a compilation failure: for arbitrary C code expressions, see the next section.

Customising the C code

For every method declared in an ammer definition, there is glue code generated which has the following general shape:

target_return_type func(args...) {
  native_args = ... // "pre": decode arguments from target-specific representation to C
  ... // "prereturn"
  c_return_type _return =
    native_call(native_args...); // "return"
  ... // "post": encode returned value to a target-specific representation, cleanup, return
}

A large part of the function, including its exact signature, depends on the concrete target. However, ammer ensures that the initial part of the function code gets the local variables to the same state on any platform: the local variables _arg0, ..., _argN are of the C types corresponding to the declared argument types.

If there is additional code that should be called before the actual native call happens, it can be inserted at the point marked "prereturn" above. This is accomplished with the @:ammer.c.prereturn metadata.

If the native call itself should be replaced with a different C expression, this can be accomplished with the @:ammer.c.return metadata. The substring %CODE% will be replaced in the provided code with the original call expression.

Pure Haxe functions

The @:ammer.haxe metadata can be used to define methods on libraries which are implemented purely in Haxe and have no native counterpart. When this metadata is attached to a method (and only then), it may have a body.

Metadata applicable to functions

Metadata can be used to inject additional C code into the wrapper code, mark functions as macro calls, or provide the native name for a function. See the full metadata descriptions for more information:

The following metadata can be attached to function arguments: