Documentation>C API
Objects

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 lifecycle: 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) ;