SDL_Surface * SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);
| SDL_Camera * | camera | オープンしたカメラデバイス |
| Uint64 * | timestampNS | フレームのタイムスタンプの代入先へのポインタ. 0のときエラー. NULLも可 |
(SDL_Surface *) 新しいビデオフレームを戻す. 有効なフレームがないときNULLを戻す.
このフレームは画像データのメモリポインタで, サイズと形式はデバイスのオープン時に要求したものである.
これはノンブロッキングAPIである.
有効なフレームがあればNULLでないサーフェイスが戻り, timestampNSには0でない値が代入される.
エラーの場合のNULLを戻すので注意すること. しかし, NULLを戻すこと自体は正常で, 単に新しいフレームの準備ができていない場合もある. カメラデバイスが完全に失われた(使用中にUSBカメラが断線したなど)場合, SDLはそれをイベントを送信して知らせるが, それとは別に真っ黒なフレームをSDL_CloseCamera()が呼ばれるまで送り続ける. そのため, ここでエラーが発生するのはほぼメモリ不足の場合のみである.
この関数の使用した後, このフレームはSDL_ReleaseCameraFrame()で解放する必要がある. それを行わない場合, システムからのフレームの供給が停止する.
戻されたサーフェイスに対してSDL_DestroySurface()を呼んではならない.
システムがユーザにカメラへのアクセスの許可を求め待っている場合, この関数はNULL(有効なフレームが存在しない)を戻す. アプリケーションはSDL_EVENT_CAMERA_DEVICE_APPROVED(またはSDL_EVENT_CAMERA_DEVICE_DENIED)イベントを待つか, SDL_GetCameraPermissionState()が0以外を戻すまでポーリングする必要がある.