Vl prefix
(for example @c VlExampleObject). Object methods are lowercase and
start with the vl__ suffix
(e.g. @c vl_example_object_new).
@section objects-lifecycle 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 @c
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 @c init keyword, e.g. @c
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 @c 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 @c new keyword,
e.g. @c vl_example_object_new.
- **Deleting an object.** This disposes of an object created by a @c
new method, combining finalization and deallocation, for example
@c vl_example_object_delete.
@section objects-getters-setters Getters and setters
Most objects contain a number of methods to get (getters) and set
(setters) properties. These should contain the @c get and @c set
keywords in their name, for example
@code
double x = vl_example_object_get_property () ;
vl_example_object_set_property(x) ;
@endcode
**/
/**
@page matlab MATLAB integration
@author Andrea Vedaldi
The VLFeat C library is designed to integrate seamlessly with MATLAB.
Binary compatibility is simplified by the use of the C language
(rather than C++). In addition, the library design follows certain
restrictions that make it compatible with the MATLAB MEX interface.
The main issue in calling a library function from a MATLAB MEX
function is that MATLAB can abort the execution of the MEX function
at any point, either due to an error, or directly upon a user request
(Ctrl-C) (empirically, however, a MEX function seems to be
incorruptible only during the invocation of certain functions of the
MEX API such as @c mexErrMsgTxt).
When a MEX function is interrupted, resources (memory blocks or
objects) whose ownership was transferred from VLFeat to the MEX
function may be leaked. Notice that interrupting a MEX function would
similarly leak any memory block allocated within the MEX function. To
solve this issue, MATLAB provides his own memory manager (@c
mxMalloc, @c mxRealloc, ...). When a MEX file is interrupted or ends,
all memory blocks allocated by using one of such functions are
released, preventing leakage.
In order to integrate VLFeat with this model in the most seamless
way, VLFeat memory allocation functions (::vl_malloc, ::vl_realloc,
::vl_calloc) are mapped to the corresponding MEX memory allocation
functions. Such functions automatically dispose of all the memory
allocated by a MEX function when the function ends (even because of
an exception). Because of the restrictions of the library design
illustrated in @ref resources, this operation is safe and
correctly dispose of VLFeat local state. As a consequence, it is
possible to call @c mexErrMsgTxt at any point in the MEX function
without worring about leaking resources.
This however comes at the price of some limitations. Beyond the
restrictions illustred in @ref resources, here we note that no
VLFeat local resoruce (memory blocks or objects) can persist across
MEX file invocations. This implies that any result produced by a
VLFeat MEX function must be converted back to a MATLAB object such as
a vector or a structure. In particular, there is no direct way of
creating an object within a MEX file, returning it to MATLAB, and
passing it again to another MEX file.
**/
/**
@page metaprogram Preprocessor metaprogramming
@author Andrea Vedaldi
Part of VLFeat code uses a simple form of perprocessor metaprogramming.
This technique is used, similarly to C++ templates, to instantiate
multiple version of a given algorithm for different data types
(e.g. @c float and @c double).
In most cases preprocessor metaprogramming is invisible to the library
user, as it is used only internally.
**/
/**
@page glossary Glossary
- Column-major. A M x N matrix A is
stacked with column-major order as the sequence \f$(A_{11}, A_{21},
\dots, A_{12}, \dots)\f$. More in general, when stacking a multi
dimensional array this indicates that the first index is the one
varying most quickly, with the other followed in the natural order.
- Opaque structure. A structure is opaque if the user is not supposed
to access its member directly, but through appropriate interface functions.
Opaque structures are commonly used to define objects.
- Row-major. A M x N matrix A is
stacked with row-major order as the sequence \f$(A_{11}, A_{12},
\dots, A_{21}, \dots)\f$. More in general, when stacking a multi
dimensional array this indicates that the last index is the one
varying most quickly, with the other followed in reverse order.
- Feature frame. A feature frame is the geometrical
description of a visual features. For instance, the frame of
a @ref sift.h "SIFT feature" is oriented disk and the frame of
@ref mser.h "MSER feature" is either a compact and connected set or
a disk.
- Feature descriptor. A feature descriptor is a quantity
(usually a vector) which describes compactly the appearance of an
image region (usually corresponding to a feature frame).
**/
/**
@page dev Developing the library
@tableofcontents
This page contains information useful to the developer of VLFeat.
@section dev-copy Copyright
A short copyright notice is added at the beginning of each file. For
example:
Copyright (C) 2013 Milan Sulc Copyright (C) 2012 Daniele Perrone. Copyright (C) 2011-13 Andrea Vedaldi. All rights reserved. This file is part of the VLFeat library and is made available under the terms of the BSD license (see the COPYING file).The copyright of each file is assigned to the authors of the file. Every author making a substantial contribution to a file should note its copyright by adding a line to the copyright list with the year of the modification. Year ranges are acceptable. Lines are never deleted, only appended, or potentially modified to list more years. @section dev-style Coding style
for (i = 0 ; i < numEntries ; ++i) values[i] ++ ;is considered acceptable.
void vl_object_do_something(VlObject *self) ;Multi-dimensional arrays should be specified first by their address, and then by their dimensions. For example
void vl_use_array (float * array, vl_size numColumns, vl_size numRows) ; // good void vl_use_array (vl_size numColumns, vl_size numRows, float * array) ; // badArguments that are used as outputs should be specified first (closer to the left-hand side of an expression). For example
void vl_sum_numbers (float * output, float input1, float input2) ; // good void vl_sum_numbers (float input1, float input2, float * output) ; // badThese rules can be combined. For example
void vl_object_sum_to_array (VlObject * self, float * outArray,
vl_size numColumns, vl_size numRows, float * inArray) ; // good
Note that in this case no dimension for @c inArray is specified as it
is assumed that @c numColumns and @c numRows are the dimensions of
both arrays.
@@ref directive to point
to the main documentation page describing the module, if there is one.
@@cite{xyz} command. Here @c xyz is a BibTeX
key. For example, @c vlfeat.bib file contains the entry:
@@inproceedings{martin97the-det-curve,
Author = {A. Martin and G. Doddington and T. Kamm and M. Ordowski and M. Przybocki},
Booktitle = {Proc. Conf. on Speech Communication and Technology},
Title = {The {DET} curve in assessment of detection task performance},
Year = {1997}}
For example, the Doxygen directive
@@cite{martin97the-det-curve} generates the output
@cite{martin97the-det-curve}, which is a link to the corresponding
entry in the bibliography.
**/
/**
@file generic.h
@page generic General support functionalities
@author Andrea Vedaldi
VLFeat contains several support functionalities addressing the C
preprocessors, using multiple threads (including parallel computations),
handling errors, allocating memory, etc. These are described in
the following pages:
- @subpage resources
- @subpage threads
- @subpage misc
**/
/**
@page misc Preprocssor, library state, etc.
@author Andrea Vedaldi
@tableofcontents
@section misc-preproc C preprocessor helpers
VLFeat provides a few C preprocessor macros of general
utility. These include stringification (::VL_STRINGIFY,
::VL_XSTRINGIFY) and concatenation (::VL_CAT, ::VL_XCAT) of symbols.
@section misc-state VLFeat state and configuration parameters
VLFeat has some global configuration parameters that can
changed. Changing the configuration is thread unsave
(@ref threads). Use ::vl_set_simd_enabled to toggle the use of
a SIMD unit (Intel SSE code), ::vl_set_alloc_func to change
the memory allocation functions, and ::vl_set_printf_func
to change the logging function.
@section misc-error Error handling
Some VLFeat functions signal errors in a way similar to the
standard C library. In case of error, a VLFeat function
may return an error code directly,
or an invalid result (for instance a negative file descriptor or a null
pointer). Then ::vl_get_last_error and ::vl_get_last_error_message can be used
to retrieve further details about the error (these functions should be
used right after an error has occurred, before any other VLFeat call).
@section misc-memory Memory allocation
VLFeat uses the ::vl_malloc, ::vl_realloc, ::vl_calloc and ::vl_free
functions to allocate memory. Normally these functions are mapped to
the underlying standard C library implementations. However
::vl_set_alloc_func can be used to map them to other
implementations. For instance, in MATALB MEX files these functions
are mapped to the MATLAB equivalent which has a garbage collection
mechanism to cope with interruptions during execution.
@section misc-logging Logging
VLFeat uses the macros ::VL_PRINT and ::VL_PRINTF to print progress
or debug informations. These functions are normally mapped to the @c
printf function of the underlying standard C library. However
::vl_set_printf_func can be used to map it to a different
implementation. For instance, in MATLAB MEX files this function is
mapped to @c mexPrintf. Setting the function to @c NULL disables
logging.
@section misc-time Measuring time
VLFeat provides ::vl_tic and ::vl_toc as an easy way of measuring
elapsed time.
**/
/**
@page threads Threading
@tableofcontents
VLFeat supports for threaded computations can be used to take advantage
of multi-core architectures. Threading support includes:
- Supporting using VLFeat functions and objects from multiple threads
simultaneously. This is discussed in @ref threads-multiple.
- Using multiple cores to accelerate computations. This is
discussed in @ref threads-parallel.
@section threads-multiple Using VLFeat from multiple threads
VLFeat can be used from multiple threads simultaneously if proper
rules are followed.
- A VLFeat object instance is accessed only from one thread at any
given time. Functions operating on objects (member functions)
are conditionally thread safe: the same function may be called
simultaneously from multiple threads provided that it operates on
different, independent objects. However, modifying the same object
from multiple threads (using the same or different member functions)
is possible only from one thread at any given time, and should
therefore be synchronized. Certain VLFeat objects may contain
features specific to simplify multi-threaded operations
(e.g. ::VlKDForest).
- Thread-safe global functions are used. These include
thread-specific operations such as retrieving the last error by
::vl_get_last_error and obtaining the thread-specific random number
generator instance by ::vl_get_rand. In these cases, the functions
operate on thread-specific data that VLFeat creates and
maintains. Note in particular that each thread has an independent
default random number generator (as returned by
::vl_get_rand). VLFeat objects that involve using random numbers
will typically use the random number generator of the thread
currently accessing the object (although an object-specific
generator can be often be specified instead).
- Any other global function is considered non-thread safe and is
accessed exclusively by one thread at a time. A small number of
operations are non-reentrant and affect all threads
simultaneously. These are restricted to changing certain global
configuration parameters, such as the memory allocation functions by
::vl_set_alloc_func. These operations are not thread safe
and are preferably executed before multiple threads start to operate
with the library.
@section threads-parallel Parallel computations
VLFeat uses OpenMP to implement parallel computations. VLFeat avoids
changing OpenMP global state, such as the desired number of
computational threads, as this may affect the rest of the application
(e.g. MATLAB) in undesriable ways. Instead, it duplicates OpenMP
controls when appropriate (this is similar to the method used by other
libraries such as Intel MKL).
The maximum number of threads available to the application can be
obtained by ::vl_get_thread_limit. This limit is controlled by the
OpenMP library (the function is a wrapper around @c
omp_get_thread_limit), which in turn may determined that based on the
number of computational cores or the value of the @c OMP_THREAD_LIMIT
variable when the program is launched.
The desired number of computational threads is set by
::vl_set_num_threads() and retrieved by ::vl_get_max_threads(). This
number is a target value as well as an upper bound to the number of
threads used by VLFeat. @c vl_set_num_threads(1) disables the use of
multiple threads and @c vl_set_num_threads(0) uses OpenMP value
(retrieved by calling @c omp_get_max_threads()). The actual number
used in a specific computation is decided by OpenMP based on the
number of threads available, accounting for example for nested
parallelism when appropriate.
@sa http://software.intel.com/sites/products/documentation/doclib/mkl_sa/11/mkl_userguide_win/GUID-C2295BC8-DD22-466B-94C9-5FAA79D4F56D.htm
http://software.intel.com/sites/products/documentation/doclib/mkl_sa/11/mkl_userguide_win/index.htm#GUID-DEEF0363-2B34-4BAB-87FA-A75DBE842040.htm
http://software.intel.com/sites/products/documentation/hpc/mkl/lin/MKL_UG_managing_performance/Using_Additional_Threading_Control.htm
**/
#include "generic.h"
#include