ユーティリティとシステム関数，マクロ
======================================================

.. highlight:: cpp



.. index:: alignPtr


cv::alignPtr
------------




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

    ポインタのアラインメントを，指定したバイト数に揃えます．






    
    :param ptr: 調整されるポインタ 
    
    
    :param n: アラインメントサイズ．2の指数倍でなければいけません 
    
    
    
この関数は，入力ポインタと同じタイプの，アラインメントが調整されたポインタを返します．



.. math::

    \texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)} 



.. index:: alignSize


cv::alignSize
-------------




.. cfunction:: size_t alignSize(size_t sz, int n)

    バッファサイズのアラインメントを，指定したバイト数に揃えます．






    
    :param sz: 調整されるバッファサイズ 
    
    
    :param n: アラインメントサイズ．2の指数倍でなければいけません 
    
    
    
この関数は， 
``sz``
以上かつ 
``n``
で割りきれる最小の値を返します．



.. math::

    \texttt{(sz + n-1) \& -n} 



.. index:: allocate


cv::allocate
------------




.. cfunction:: template<typename _Tp> _Tp* allocate(size_t n)

    要素の配列を確保します．






    
    :param n: 確保される要素数 
    
    
    
汎用関数 
``allocate``
は，指定した要素数分のバッファを確保します．各要素に対してデフォルトコンストラクタが呼ばれます．




.. index:: deallocate


cv::deallocate
--------------




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

    要素の配列を解放します．






    
    :param ptr: 解放されるバッファへのポインタ 
    
    
    :param n: バッファ内の要素数 
    
    
    
関数 
``deallocate``
は， 
:func:`allocate`
によって確保されたバッファを解放します．要素数は 
:func:`allocate`
に渡される値と一致しなければいけません．



.. index:: CV_Assert


cv::CV_Assert
-------------




.. cfunction:: CV_Assert(expr)

    実行時に条件をチェックします．







::


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

..



    
    :param expr: チェックされる式 
    
    
    
``CV_Assert``
マクロや 
``CV_DbgAssert``
マクロは指定された式を評価し，それが 0 ならばエラーを発生さます（ 
:func:`error`
を参照してください）． 
``CV_DbgAssert``
マクロはデバッグモードでのみ有効なのに対し， 
``CV_Assert``
マクロはデバッグとリリースの両モードで条件をチェックします．



.. index:: error


cv::error
---------




.. cfunction:: void error( const Exception\& exc )



.. cfunction:: \#define CV_Error( code, msg ) <...>



.. cfunction:: \#define CV_Error_( code, args ) <...>

    エラーを発生させ，例外を発行します．






    
    :param exc: 発行される例外 
    
    
    :param code: エラーコード．通常は負の値．定義済みのエラーコードは  ``cxerror.h``  で見られます 
    
    
    :param msg: エラーメッセージのテキスト 
    
    
    :param args: printf 形式のフォーマットをもつエラーメッセージ．丸括弧で囲まれます 
    
    
    
関数 
``error``
と，その補助マクロ 
``CV_Error``
および 
``CV_Error_``
は，エラーハンドラを呼び出します．現在のエラーハンドラは，エラーコード（ 
``exc.code``
），コンテキスト（ 
``exc.file``
, 
``exc.line``
），エラーメッセージ（ 
``exc.err``
）を，標準エラーストリーム 
``stderr``
に表示します．デバッグモードでは，デバッガで実行スタックと全パラメータを分析できるように，メモリアクセス違反を引き起こします．リリースモードでは，例外 
``exc``
が投げられます．


``CV_Error_``
マクロは，エラーメッセージを実行時に作成し，これが動的情報を含むようにします．例えば：





::


    
    // テキストメッセージ書式は，全体が括弧で囲まれることに注意してください．
    CV_Error_(CV_StsOutOfRange,
        ("the matrix element (
        i, j, mtx.at<float>(i,j)))
    

..


.. index:: Exception

.. _Exception:

Exception
---------

.. ctype:: Exception



error に渡される例外クラス．





::


    
    class  Exception
    {
    public:
        // 様々なコンストラクタとコピー処理
        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
    
        // エラーコード
        int code;newline
        // エラーテキストメッセージ
        string err;newline
        // エラーが発生した関数名
        string func;newline
        // エラーが発生したソースのファイル名
        string file;newline
        // エラーが発生したソースの行番号
        int line;
    };
    

..

``Exception``
クラスは，プログラム中で発生したエラーに関するすべての，あるいはほぼすべての必要情報をカプセル化します．通常， 
``CV_Error``
マクロおよび 
``CV_Error_``
マクロを介して，例外が明示的に作成され投げられます． 
:func:`error`
を参照してください．




.. index:: fastMalloc


cv::fastMalloc
--------------




.. cfunction:: void* fastMalloc(size_t size)

    アラインメントが調整されたメモリバッファを確保します．






    
    :param size: 確保されるバッファサイズ 
    
    
    
関数 
``fastMalloc``
は，指定されたサイズのバッファを確保し，それを返します．バッファサイズが 16バイト以上の場合，返されるバッファのアラインメントは 16 バイト境界に調整されます．



.. index:: fastFree


cv::fastFree
------------




.. cfunction:: void fastFree(void* ptr)

    メモリバッファを解放します．






    
    :param ptr: 確保されたバッファへのポインタ 
    
    
    
関数 
``fastFree``
は， 
:func:`fastMalloc`
によって確保されたバッファを解放します．NULL ポインタが渡された場合，この関数は何も行いません．




.. index:: format


cv::format
----------




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

    pintf 風の表現を用いてフォーマットされたテキスト string を返す．






    
    :param fmt: printf互換のフォーマット指定子 
    
    
    
関数 
``format``
は， 
``sprintf``
のように振る舞いますが，STL string を作成して返します．これは 
:func:`Exception`
コンストラクタで，エラーメッ
セージを作成する際に利用されます．



.. index:: getNumThreads


cv::getNumThreads
-----------------




.. cfunction:: int getNumThreads()

    OpenCV で利用されているスレッド数を返します．




OpenCV で利用されているスレッド数を返します．


参考： 
:func:`setNumThreads`
, 
:func:`getThreadNum`
.




.. index:: getThreadNum


cv::getThreadNum
----------------




.. cfunction:: int getThreadNum()

    現在実行中のスレッドのインデックスを返します．




この関数は，現在実行されているスレッドのインデックス（0基準）を返します．この関数は，OpenMP の並列領域内でのみ有効です．OpenCV が OpenMP をサポートしないようにビルドされている場合，この関数は常に 0 を返します．


参考： 
:func:`setNumThreads`
, 
:func:`getNumThreads`
.



.. index:: getTickCount


cv::getTickCount
----------------




.. cfunction:: int64 getTickCount()

    tick 数を返します．




この関数は，あるイベント（例えば，マシン起動時）からの tick 数を返します．

これは， 
:func:`RNG`
を初期化したり，関数の呼び出し前後で tick 数を読み出すことで関数の実行時間を計測したりするのに用いられます．



.. index:: getTickFrequency


cv::getTickFrequency
--------------------




.. cfunction:: double getTickFrequency()

    1 秒毎の tick 数を返します．




この関数は，1秒毎の tick 数を返します．
つまり以下のコードは，実行時間を秒単位で求めます．





::


    
    double t = (double)getTickCount();
    // 何らかの処理を行います ...
    t = ((double)getTickCount() - t)/getTickFrequency();
    

..


.. index:: setNumThreads


cv::setNumThreads
-----------------




.. cfunction:: void setNumThreads(int nthreads)

    OpenCV で利用されるスレッド数を設定します．






    
    :param nthreads: OpenCV で利用されるスレッド数 
    
    
    
この関数は，OpenMP の並列領域内において OpenCV で利用されるスレッド数を設定します． 
``nthreads=0``
ならば，関数はスレッドのデフォルト値を利用します．これは通常，CPUのコア数と等しくなります．


参考： 
:func:`getNumThreads`
, 
:func:`getThreadNum`