Utility and System Functions and Macros

cv::alignPtr

template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))

Aligns pointer to the specified number of bytes

Parameters:

• ptr – The aligned pointer
• n – The alignment size; must be a power of two

The function returns the aligned pointer of the same type as the input pointer:

cv::alignSize

size_t alignSize(size_t sz, int n)

Aligns a buffer size to the specified number of bytes

Parameters:

• sz – The buffer size to align
• n – The alignment size; must be a power of two

The function returns the minimum number that is greater or equal to sz and is divisble by n :

cv::allocate

template<typename _Tp> _Tp* allocate(size_t n)

Allocates an array of elements

Parameter:n – The number of elements to allocate

The generic function allocate allocates buffer for the specified number of elements. For each element the default constructor is called.

cv::deallocate

template<typename _Tp> void deallocate(_Tp* ptr, size_t n)

Allocates an array of elements

Parameters:

• ptr – Pointer to the deallocated buffer
• n – The number of elements in the buffer

The generic function deallocate deallocates the buffer allocated with allocate() . The number of elements must match the number passed to allocate() .

CV_Assert

CV_Assert(expr)

Checks a condition at runtime.

#define CV_Assert( expr ) ...
#define CV_DbgAssert(expr) ...

param expr:The checked expression

The macros CV_Assert and CV_DbgAssert evaluate the specified expression and if it is 0, the macros raise an error (see error() ). The macro CV_Assert checks the condition in both Debug and Release configurations, while CV_DbgAssert is only retained in the Debug configuration.

cv::error

void error(const Exception& exc)

#define CV_Error( code, msg ) <...>

#define CV_Error_( code, args ) <...>

Signals an error and raises the exception

Parameters:

• exc – The exception to throw
• code – The error code, normally, a negative value. The list of pre-defined error codes can be found in cxerror.h
• msg – Text of the error message
• args – printf-like formatted error message in parantheses

The function and the helper macros CV_Error and CV_Error_ call the error handler. Currently, the error handler prints the error code ( exc.code ), the context ( exc.file , exc.line and the error message exc.err to the standard error stream stderr . In Debug configuration it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed in debugger. In Release configuration the exception exc is thrown.

The macro CV_Error_ can be used to construct the error message on-fly to include some dynamic information, for example:

// note the extra parentheses around the formatted text message
CV_Error_(CV_StsOutOfRange,
    ("the matrix element (
    i, j, mtx.at<float>(i,j)))

Exception

Exception

The exception class passed to error

class  Exception
{
public:
    // various constructors and the copy operation
    Exception() { code = 0; line = 0; }
    Exception(int _code, const string& _err,
              const string& _func, const string& _file, int _line);newline
    Exception(const Exception& exc);newline
    Exception& operator = (const Exception& exc);newline

    // the error code
    int code;newline
    // the error text message
    string err;newline
    // function name where the error happened
    string func;newline
    // the source file name where the error happened
    string file;newline
    // the source file line where the error happened
    int line;
};

The class Exception encapsulates all or almost all the necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly, via CV_Error and CV_Error_ macros, see error() .

cv::fastMalloc

void* fastMalloc(size_t size)

Allocates aligned memory buffer

Parameter:size – The allocated buffer size

The function allocates buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned on 16 bytes.

cv::fastFree

void fastFree(void* ptr)

Deallocates memory buffer

Parameter:ptr – Pointer to the allocated buffer

The function deallocates the buffer, allocated with fastMalloc() . If NULL pointer is passed, the function does nothing.

cv::format

string format(const char* fmt, ...)

Returns a text string formatted using printf-like expression

Parameter:fmt – The printf-compatible formatting specifiers

The function acts like sprintf , but forms and returns STL string. It can be used for form the error message in Exception() constructor.

cv::getNumThreads

int getNumThreads()

Returns the number of threads used by OpenCV

The function returns the number of threads that is used by OpenCV.

See also: setNumThreads() , getThreadNum() .

cv::getThreadNum

int getThreadNum()

Returns index of the currently executed thread

The function returns 0-based index of the currently executed thread. The function is only valid inside a parallel OpenMP region. When OpenCV is built without OpenMP support, the function always returns 0.

See also: setNumThreads() , getNumThreads() .

cv::getTickCount

int64 getTickCount()

Returns the number of ticks

The function returns the number of ticks since the certain event (e.g. when the machine was turned on). It can be used to initialize RNG() or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.

cv::getTickFrequency

double getTickFrequency()

Returns the number of ticks per second

The function returns the number of ticks per second. That is, the following code computes the executing time in seconds.

double t = (double)getTickCount();
// do something ...
t = ((double)getTickCount() - t)/getTickFrequency();

cv::setNumThreads

void setNumThreads(int nthreads)

Sets the number of threads used by OpenCV

Parameter:nthreads – The number of threads used by OpenCV

The function sets the number of threads used by OpenCV in parallel OpenMP regions. If nthreads=0 , the function will use the default number of threads, which is usually equal to the number of the processing cores.

See also: getNumThreads() , getThreadNum()