lablGL/raw.mli

   1 (* $Id: raw.mli,v 1.10 2007-04-13 02:48:43 garrigue Exp $ *)
   2
   3 (* This module provides a direct way to access C arrays of basic types.
   4    This is particularly useful when one wants to avoid costly
   5    conversions between ML and C representations. *)
   6
   7 type (+'a) t
   8
   9 type kind =
  10     [`bitmap|`byte|`double|`float|`int|`long|`short
  11     |`ubyte|`uint|`ulong|`ushort]
  12     (* Supported element types. [bitmap] is equivalent to [ubyte] but
  13        allows user modules to distinguish between them *)
  14 type fkind = [`double|`float]
  15 type ikind = [`bitmap|`byte|`int|`long|`short|`ubyte|`uint|`ulong|`ushort]
  16 type lkind = [`int|`long|`uint|`ulong]
  17
  18 val create : ([< kind] as 'a) -> len:int -> 'a t
  19     (* [create t :len] returns a new raw array of C type t
  20        and length len. This array is managed by the GC *)
  21 val create_static : ([< kind] as 'a) -> len:int -> 'a t
  22     (* [create_static t :len] returns a new raw array of C type t
  23        and length len. This array is created through malloc.
  24        You must free it explicitely *)
  25 val free_static : 'a t -> unit
  26     (* Free a raw array created through create_static *)
  27
  28 val kind : 'a t -> 'a
  29     (* Returns the type of a free array. Beware of the influence on the
  30        type system: you probably want to write [(kind raw :> kind)] *)
  31 val byte_size : 'a t -> int
  32     (* The size of the array in bytes. That is (sizeof t * len)
  33        where t and len are the parameters to create *)
  34 val static : 'a t -> bool
  35     (* Wether this array was statically allocated or not *)
  36 val cast : 'a t -> kind:([< kind] as 'b) -> 'b t
  37     (* Change the type of a raw array *)
  38
  39 external sizeof : [< kind] -> int = "ml_raw_sizeof"
  40     (* [sizeof t] returns the physical size of t in bytes *)
  41 val length : [< kind] t -> int
  42     (* [length raw] returns the length of raw array according to
  43        its contents type *)
  44 val sub : ([< kind] t as 'a) -> pos:int -> len:int -> 'a
  45     (* returns the slice of length len starting at position pos *)
  46
  47 (* The following functions access raw arrays in the intuitive way.
  48    They raise [Invalid_argument] when access is attempted out of
  49    bounds *)
  50
  51 external get : [< ikind] t -> pos:int -> int = "ml_raw_get"
  52 external set : [< ikind] t -> pos:int -> int -> unit = "ml_raw_set"
  53 external get_float : [< fkind] t -> pos:int -> float = "ml_raw_get_float"
  54 external set_float : [< fkind] t -> pos:int -> float -> unit
  55   = "ml_raw_set_float"
  56 external get_hi : [< lkind] t -> pos:int -> int = "ml_raw_get_hi"
  57 external set_hi : [< lkind] t -> pos:int -> int -> unit = "ml_raw_set_hi"
  58 external get_lo : [< lkind] t -> pos:int -> int = "ml_raw_get_lo"
  59 external set_lo : [< lkind] t -> pos:int -> int -> unit = "ml_raw_set_lo"
  60 external get_long : [< lkind] t -> pos:int -> nativeint = "ml_raw_get_long"
  61 external set_long : [< lkind] t -> pos:int -> nativeint -> unit
  62     = "ml_raw_set_long"
  63
  64 (* Simultaneous access versions are much more efficient than individual
  65    access, the overhead being paid only once *)
  66
  67 val gets : [< ikind] t -> pos:int -> len:int -> int array
  68 val sets : [< ikind] t -> pos:int -> int array -> unit
  69 val gets_float : [< fkind] t -> pos:int -> len:int -> float array
  70 val sets_float : [< fkind] t -> pos:int -> float array -> unit
  71
  72 (* Fastest version: simply copy the contents of the array to and from
  73    a string *)
  74
  75 val gets_string : 'a t -> pos:int -> len:int -> string
  76 val sets_string : 'a t -> pos:int -> string -> unit
  77
  78 (* Abbreviations to create raw arrays from ML arrays and strings *)
  79
  80 val of_array : int array -> kind:([< ikind] as 'a) -> 'a t
  81 val of_float_array : float array -> kind:([< fkind] as 'a) -> 'a t
  82 val of_string : string -> kind:([< kind] as 'a) -> 'a t
  83 val of_matrix : float array array -> kind:([< fkind] as 'a) -> 'a t