Documentation - C API
Objects

Table of Contents

Author:
Andrea Vedaldi

Many VLFeat algorithms are available in the form of objects. The C language, used by VLFeat, does not support objects explicitly. Here an object is intended a C structure along with a number of functions (the object member functions or methods) operating on it. Ideally, the object data structure is kept opaque to the user, for example by defining it in the .c implementation files which are not accessible to the library user.

Object names are capitalized and start with the Vl prefix (for example VlExampleObject). Object methods are lowercase and start with the vl_<object_name>_ suffix (e.g. vl_example_object_new).

Object lifecycle

Conceptually, an object undergoes four phases during its lifecylce: allocation, initialization, finalization, and deallocation:

  • Allocation. The memory to hold the object structure is allocated. This is usually done by calling a memory allocation function such as vl_calloc to reserve an object of the required size sizeof(VlExampleObject). Alternatively, the object can simply by allocated on the stack by declaring a local variable of type VlExampleObject.
  • Initialization. The object is initialized by assigning a value to its data members and potentially allocating a number of resources, including other objects or memory buffers. Initialization is done by methods containing the init keyword, e.g. vl_example_object_init. Several such methods may be provided.
  • Finalization. Initialization is undone by finalization, whose main purpose is to release any resource allocated and still owned by the object. Finalization is done by the vl_example_object_finalize method.
  • Deallocation. The memory holding the object structure is disposed of, for example by calling vl_free or automatically when the corresponding local variable is popped from the stack.

In practice, most VlFeat object are supposed to be created on the heap. To this end, allocation/initialization and finalization/deallocation are combined into two operations:

  • Creating a new object. This allocates a new object on the heap and initializes it, combining allocation and initialization in a single operation. It is done by methods containing the new keyword, e.g. vl_example_object_new.
  • Deleting an object. This disposes of an object created by a new method, combining finalization and deallocation, for example vl_example_object_delete.

Getters and setters

Most objects contain a number of methods to get (getters) and set (setters) properties. These should contain the get and set keywords in their name, for example

double x = vl_example_object_get_property () ;
vl_example_object_set_property(x) ;