2.2.4.1 Vector type names

The names of the FLI types are designed to best match the types that are defined by Clang, which is used on Mac OS X, iOS and FreeBSD and is optionally available on other operating systems. For every C/Objective-C type of the form vector_<type><count>, there is an FLI type of the form fli:vector-<scalar fli type><count>. For example, the C/Objective-C type vector_double8 is matched by the FLI type fli:vector-double8.

The scalar fli types and their matching Common Lisp types are:

char

(signed-byte 8)

uchar

(unsigned-byte 8)

short

(signed-byte 16)

ushort

(unsigned-byte 16)

int

(signed-byte 32)

uint

(unsigned-byte 32)

long

(signed-byte 64)

ulong

(unsigned-byte 64)

float

single-float

double

double-float

The count can be 2, 3, 4, 8, 16 (for elements of 32 bits or less) or 32 (for elements of 16 bits or less). The restrictions mean that the maximum size of a vector is 64 bytes and the maximum count is 32.

Note that long and ulong are always 64 bits in this context, even on 32-bit where the C type long is 32 bits.

The full list of types:

vector-char2 vector-char3 vector-char4 vector-char8 vector-char16 vector-char32

vector-uchar2 vector-uchar3 vector-uchar4 vector-uchar8 vector-uchar16 vector-uchar32

vector-short2 vector-short3 vector-short4 vector-short8 vector-short16 vector-short32

vector-ushort2 vector-ushort3 vector-ushort4 vector-ushort8 vector-ushort16 vector-ushort32

vector-int2 vector-int3 vector-int4 vector-int8 vector-int16

vector-uint2 vector-uint3 vector-uint4 vector-uint8 vector-uint16

vector-long2 vector-long3 vector-long4 vector-long8

vector-ulong2 vector-ulong3 vector-ulong4 vector-ulong8

vector-float2 vector-float3 vector-float4 vector-float8 vector-float16

vector-double2 vector-double3 vector-double4 vector-double8

In addition, vector-long1 and vector-ulong1 are defined as immediate 64-bit signed and unsigned integers, because Clang defines them like that.

2.2.4.2 Vector type values

When passing an argument that is declared as any of the FLI vector types, the value needs to be a Lisp vector of the correct length or a foreign pointer to the FLI vector type.

• For vector-double<count> and vector-float<count>, the Lisp vector must either have element type double-float or single-float, or have element type t and contain elements of type float.
• For the integer vector types, the Lisp vector must either have an element type that is subtype of the element type of the FLI vector type, or have element type t and contain elements that fit into the FLI vector.
• If a foreign pointer is passed for an argument that is declared as a FLI vector type, it must point to an object of the FLI vector type, which must be an exact match, including being correctly signed. The vector is passed by value, not as a pointer.

When a FLI vector type is passed into Lisp, either because it is a returned value from a foreign function or an argument to a foreign callable, it is automatically converted to a Lisp vector of the correct length and element type. This also occurs when accessing a value using foreign-slot-value, foreign-aref and dereference.

2.2.4.3 Using a foreign pointer to a vector type

When you have a foreign pointer to a vector type, you can access individual elements using foreign-aref, or convert the vector into a Lisp vector using dereference. The reverse operations can be performed using the setf form or foreign-aref and dereference. For example:

(let ((d4-poi (fli:allocate-foreign-object 

               :type 'fli:vector-double4)))

  (setf (fli:dereference d4-poi) #(0d0 1d0 2d0 3d0))

  (format t "Collected values: ~s~%"

             (loop for x below 4 

               collect (fli:foreign-aref d4-poi x)))

  (setf (fli:foreign-aref d4-poi 3) -3d0)

  (format t "Dereference after setf: ~s~%" 

           (fli:dereference d4-poi)))

=>

Collected values: (0.0D0 1.0D0 2.0D0 3.0D0)

Dereference after setf: #(0.0D0 1.0D0 2.0D0 -3.0D0)

Normally there is no reason to allocate a foreign object for a vector type as in the example above. You would, however, encounter such a pointer if you have foreign code that calls into Lisp passing it an argument that is a pointer to a vector type, and your Lisp code needs to set the values in it. In this case, you will need to declare the argument type as (:pointer vector-double4) and then set it like this:

(fli:define-foreign-callable my-callable

   ((d4-poi (:pointer fli:vector-double4)))

  (let ((lisp-v4 (my-compute-d4-values)))

     (setf (fli:dereference d4-poi) lisp-v4)))

(defun my-compute-d4-values () 

   (vector 3.5d0 7d0 9d23 0.1d0)))

Note that if you call a function that takes a pointer to a vector type, you can use the FLI types :reference, :reference-pass and :reference-return to pass and return values without having to explicitly allocate a foreign pointer. For example, if the C function my_function takes a pointer to vector_double2 and fills it like this:

void my_function (vector_double2* d2_poi) {

   (*d2_poi)[0] = 3.0;

   (*d2_poi)[1] = 4.0;

}

then in Lisp you can call it by:

(fli:define-foreign-function my-function 

   ((d2-po1 (:reference-return fli:vector-double2))))

(my-function)  ; returns #(3D0 4D0)

2.2.4.4 Notes on foreign vector types

C compilers other than Clang can also define vector types in various ways:

• In GCC, they can be defined using the vector_size attribute, for example, vector_double4 would be defined by:
• typedef double vector_double4 __attribute__ ((vector_size (32)));
• Note that the size is in bytes, rather than an element count.
• The compiler supplied by ARM has "vector data types", so for example the type float32x4_t matches vector-float4.
• In Clang, it is possible to define vector types using the GCC syntax, OpenCL syntax, AltiVec syntax and Neon syntax.

On 32-bit x86, vector types can be passed either with or without using SSE2. The Lisp FLI definitions must pass/receive arguments in the same way as the C compiler that was used to compile the foreign code. On Mac OS X, this is always with SSE2, so this is not an issue, but on other platforms (Linux, FreeBSD, Solaris) the situation is not clear. What the Lisp definitions do is controlled by *use-sse2-for-ext-vector-type*.

When using vector-char2 and vector-uchar2 on x86_64 platforms and the C compiler is Clang or a derivative, you need to check that you have the latest version of the C compiler, because earlier versions of Clang compiled these types differently from later versions. This affects Mac OS X too because the Xcode C compiler is based on Clang. You can check the version of the C compiler by executing cc -v in a shell. On Mac OS X, you need to check that you have LLVM 8.0 or later. If you have Clang, you need to check that you have version 3.9 or later.

On Mac OS X x86_64, the treatment of vector_char2 and vector_uchar2 changed between LLVM 6.0 and 8.0. LispWorks is compatible with LLVM 8.0. You can check which version of LLVM you have by executing cc -v in a shell.

When a structure is passed by value and it contains one of more fields whose types are vector types, it is also important to declare the type correctly in Lisp, otherwise the wrong data may be passed. That is because the machine registers that are used to pass such structures may be different from the registers that are used to pass seemingly equivalent structures that are defined without vector types. Such structures are commonly used to represent matrices.