CXCORE リファレンス マニュアル
- 基本構造体（Basic Structures）
- 配列操作（Operations on Arrays）
- 動的構造体（Dynamic Structures）
- 描画関数（Drawing Functions）
- データ永続性と実行時型情報（Data Persistence and RTTI）
- その他の関数（Miscellaneous Functions）
- エラーハンドリングとシステム関数（Error Handling and System Functions）
- エラーハンドリング（Error Handling）
- システム関数（System Functions）
エラーハンドリングとシステム関数（Error Handling and System Functions）
システム関数（System Functions）
Alloc
メモリバッファの領域を確保する
void* cvAlloc( size_t size );
- size
- バッファサイズ（バイト単位）．
関数 cvAlloc は size バイトの領域を確保し，その領域へのポインタを返す． エラーが生じた場合は，エラーを通知しNULLポインタを返す． デフォルトで cvAlloc は，mallocを呼ぶ icvAlloc の呼び出しを行うが， 関数 cvSetMemoryManager を用いて， ユーザ定義のメモリ領域確保/領域解放のための関数を定義することも可能である．
Free
メモリバッファの領域を解放する
void cvFree( void** ptr );
- ptr
- 解放する領域へのポインタのポインタ．
関数 cvFree は，cvAllocによって確保されたメモリバッファの領域解放を行う． 関数から出る際にバッファへのポインタをクリアするため，ポインタのポインタを用いている． *ptr が既に NULL の場合，この関数は何もしない．
GetTickCount
tick数を返す
int64 cvGetTickCount( void );
関数 cvGetTickCount は，プラットフォーム依存の開始時点からのtick数（スタートアップからのCPU tick数，1970年からのミリ秒等）を返す． この関数は，ある関数やユーザコードの実行時間を正確に計測するのに便利である． tick数から時間単位に変換するためには，cvGetTickFrequencyを用いる．
GetTickFrequency
1マイクロ秒あたりのtick数を返す
double cvGetTickFrequency( void );
関数 cvGetTickFrequency は，1マイクロ秒あたりのtick数を返す． つまり，cvGetTickCount() をcvGetTickFrequency() で割った値が，プラットフォーム依存の開始時刻からのマイクロ秒単位の時刻になる．
RegisterModule
他のモジュールを登録する
typedef struct CvPluginFuncInfo
{
void** func_addr;
void* default_func_addr;
const char* func_names;
int search_modules;
int loaded_from;
}
CvPluginFuncInfo;
typedef struct CvModuleInfo
{
struct CvModuleInfo* next;
const char* name;
const char* version;
CvPluginFuncInfo* func_tab;
}
CvModuleInfo;
int cvRegisterModule( const CvModuleInfo* module_info );
- module_info
- モジュールに関する情報．
関数 cvRegisterModule は，モジュールが登録されているリストに新しいモジュールを追加する． モジュールが登録されると，そのモジュールの情報は，関数cvGetModuleInfo を用いて取り出すことができるようになる． 登録されたモジュールも，CXCOREでサポートされている最適化プラグイン（IPP，MKL，...）を活用する． CXCORE 及び CV (computer vision)，CVAUX (auxilary computer vision) や HIGHGUI (visualization & image/video acquisition) などはモジュールの一例である． 通常は，登録が終わってから共有ライブラリ（shared library）がロードされる． どのように登録されるかの詳細は，cxcore/src/cxswitcher.cpp と cv/src/cvswitcher.cpp を参照のこと． また，IPPとMKLがどのようにモジュールとリンクされるのかについては，cxcore/src/cxswitcher.cpp, cxcore/src/_cxipp.h を参照のこと．
GetModuleInfo
登録されたモジュールとプラグインの情報を取り出す
void cvGetModuleInfo( const char* module_name,
const char** version,
const char** loaded_addon_plugins );
- module_name
- 対象のモジュール名，NULLの場合はすべてのモジュール．
- version
- 出力パラメータ．モジュールについての情報（バージョンを含む）．
- loaded_addon_plugins
- CXCOREがロード可能な最適化プラグインの名前とバージョンのリスト．
関数 cvGetModuleInfo は，登録モジュールの一つ，またはすべての情報を返す． 返された情報はライブラリ内部に保存される．そのためユーザが領域解放や返された文字列の変更を行う必要はない．
UseOptimized
最適化モード／非最適化モードを切り替える
int cvUseOptimized( int on_off );
- on_off
- 0以外のとき最適化，0のとき非最適化．
関数 cvUseOptimized は，cxcoreや，OpenCVのほかのライブラリなどを，純粋なC言語だけで実装したモードと， 可能な部分はIPP と MKLを用いて最適化したモードとを切り替える． cvUseOptimized(0) が呼ばれたときは，最適化ライブラリはロードされない． この関数はデバッグ時，IPP&MKLのアップグレード時，処理速度を動作中に比較したい時などに有効である． 戻り値は，ロードされた最適化関数の数． デフォルトで最適化プラグインがロードされるので，プログラムの最初にcvUseOptimized(1)を呼ぶ必要はない （実際，スタートアップ時に処理時間が増えるだけ）ことに注意．
SetMemoryManager
カスタムあるいはデフォルトのメモリ管理関数を指定する
typedef void* (CV_CDECL *CvAllocFunc)(size_t size, void* userdata);
typedef int (CV_CDECL *CvFreeFunc)(void* pptr, void* userdata);
void cvSetMemoryManager( CvAllocFunc alloc_func=NULL,
CvFreeFunc free_func=NULL,
void* userdata=NULL );
- alloc_func
- 領域確保関数（インタフェースは，コンテクストを決定するために使用されることがあるuserdata以外は， mallocと同じ）．
- free_func
- 領域解放関数（インタフェースは，freeと同じ）．
- userdata
- カスタム関数に引数として渡されるユーザデータ．
関数 cvSetMemoryManager は，cvAlloc, cvFree や 上位レベルの関数 （例えば，cvCreateImage）から呼ばれるユーザ定義のメモリ管理関数（mallocとfreeに取って代わるもの）の設定を行う． cvAllocによってデータ領域を確保するときに，この関数が呼ばれることに注意． 再帰呼び出しの無限ループを避けるため，ユーザ定義の領域確保／解放関数では cvAllocとcvFreeの呼び出しを行ってはいけない．
alloc_func と free_func へのポインタが NULLの場合は， デフォルトのメモリ管理関数が用いられる．
SetIPLAllocators
画像領域の確保と解放のためのIPL関数に切り替える
typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
(int,int,int,char*,char*,int,int,int,int,int,
IplROI*,IplImage*,void*,IplTileInfo*);
typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);
void cvSetIPLAllocators( Cv_iplCreateImageHeader create_header,
Cv_iplAllocateImageData allocate_data,
Cv_iplDeallocate deallocate,
Cv_iplCreateROI create_roi,
Cv_iplCloneImage clone_image );
#define CV_TURN_ON_IPL_COMPATIBILITY() ¥
cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage, ¥
iplDeallocate, iplCreateROI, iplCloneImage )
- create_header
- iplCreateImageHeaderへのポインタ．
- allocate_data
- iplAllocateImageへのポインタ．
- deallocate
- iplDeallocateへのポインタ．
- create_roi
- iplCreateROIへのポインタ．
- clone_image
- iplCloneImageへのポインタ．
関数 cvSetIPLAllocatorsは，CXCOREが，画像領域の確保と解放を行うためにIPLの関数を使用するよう変更する． 利便性のために，ラッピングマクロ CV_TURN_ON_IPL_COMPATIBILITYが存在する． この関数は，IPL と CXCORE/OpenCVを同時に使っていたり，iplCreateImageHeaderなどを呼んでいたりする場合には有効である． IPLが単にデータ処理のみで，すべての領域確保や解放はCXCOREで行っている場合や， 逆にすべての領域確保や解放をIPLで，そしてデータ処理はOpenCVの関数で行っている場合は，この関数は不要である．
GetNumThreads
現在使われているスレッド数を返す
int cvGetNumThreads( void);
関数 cvGetNumThreadsは，（OpenMPを用いて）並列化されたOpenCV関数によって使用される現在のスレッド数を返す．
SetNumThreads
スレッド数をセットする
void cvSetNumThreads( int threads=0 );
- threads
- スレッド数．
関数 cvSetNumThreads は，並列化されたOpenCV関数によって使用されるスレッド数をセットする． 引数が0か負の場合，またプログラム開始時は，スレッド数にOpenMPランタイムの関数omp_get_num_procs() の戻り値であるシステムのプロセッサ数がセットされる．
GetThreadNum
現在のスレッドのインデックスを返す
int cvGetThreadNum( void );
関数 cvGetThreadNum は，この関数を呼んだスレッドのインデックス （0からcvGetNumThreads()-1の範囲の値）を返す． この関数は，OpenMPランタイムの関数omp_get_thread_num()のラッパーである． 取り出されたインデックスは，並列化された各コード内のローカルスレッドのデータにアクセスするために用いられる．