4つの手順で学ぶ
カメラ操作とメモリー記録

// 1-2. エラー判定とハンドルの初期状態を用意する：本文と同じ順番で処理する。
#define KYVP_USE_EXPERIMENTAL_APIS
#define KYVP_USE_STREAM_DIRECT_CALLBACK
#include "KYVPLibTL.h"
#include "KYVPLibExtension.h"
#include "KYVPParametersHandler.h"
#include "KYFoundation.h"
#include <windows.h>
#include <cstdint>
#include <cstring>
#include <stdexcept>
#include <vector>
#include <atomic>
#include <mutex>
#include <limits>
#include <cmath>
#include <cstdio>

static void check(KY_RESULT r, const char* api) {
    if (KY_RESULT_FAILED(r)) throw std::runtime_error(api);
}
static KYVP_TL_HANDLE hTLHandle = KYVP_TL_HANDLE_INVALID;
static KYVP_PCI_INTERFACE_HANDLE hPCIInterfaceHandle = KYVP_PCI_INTERFACE_HANDLE_INVALID;
static KYVP_DEVICE_HANDLE hLocalDeviceHandle = KYVP_DEVICE_HANDLE_INVALID;
static KYVP_REMOTE_DEVICE_HANDLE hRemoteDeviceHandle = KYVP_REMOTE_DEVICE_HANDLE_INVALID;
static KYVP_STREAM_HANDLE hStreamHandle = KYVP_STREAM_HANDLE_INVALID;
static KYVP_COLLECTION_HANDLE hRemoteDeviceParameterCollectionHandle = KYVP_COLLECTION_HANDLE_INVALID;
static KYVP_COLLECTION_HANDLE hStreamParameterCollectionHandle = KYVP_COLLECTION_HANDLE_INVALID;
static bool libraryReady=false, tlOpen=false, interfaceOpen=false;
static bool deviceOpen=false, streamOpen=false, callbackRegistered=false;
static bool streamStarted=false, cameraStartAttempted=false;
struct CollectionState { bool created=false,transport=false,callback=false; };
static CollectionState cameraCollectionState,streamCollectionState;
static void KYVP_CALLCONV StreamCallback(KYVP_BUFFER_HANDLE,void*);

// 1-3. SDKとフレームグラバーを開く：本文と同じ順番で処理する。
// SDK全体を初期化する。最初に1回呼び、最後にCloseLibで終了する。
check(KYVPLibTL_InitLib(), "InitLib"); libraryReady=true;
// Interfaceを列挙する親モジュールTLを開く。
check(KYVPLibTL_TLOpen_V1(&hTLHandle), "TLOpen"); tlOpen=true;
KY_BOOL changed=KY_FALSE;
// PC上のフレームグラバー一覧を最新状態に更新する。
check(KYVPLibTL_TLUpdateInterfaceList_V1(hTLHandle,&changed,0), "TLUpdateInterfaceList");
uint32_t count=0;
// 接続されたInterfaceの件数を取得し、範囲外の選択を防ぐ。
check(KYVPLibTL_TLGetNumInterfaces_V1(hTLHandle,&count), "TLGetNumInterfaces");
const uint32_t selectedInterface=0;
if (selectedInterface>=count) throw std::runtime_error("No selected frame grabber");
char id[128]={}; size_t size=sizeof(id);
// 選んだInterfaceを開くためのID文字列を取得する。
check(KYVPLibTL_TLGetInterfaceID_V1(hTLHandle,selectedInterface,id,&size), "TLGetInterfaceID");
const KYVP_PCI_INTERFACE_INFO* info=nullptr;
KYVP_INFO_DATATYPE type; size=sizeof(info);
// ボードの識別情報を取得する。戻る情報の所有者はSDK。
check(KYVPLibTL_TLGetInterfaceInfo_V1(hTLHandle,id,
    KYVP_INTERFACE_INFO_CMD_KYVP_PCI_INTERFACE_INFO,&type,&info,&size), "TLGetInterfaceInfo");
// 選択したフレームグラバーを操作可能にする。
check(KYVPLibTL_TLOpenInterface_V1(hTLHandle,id,&hPCIInterfaceHandle), "TLOpenInterface");
interfaceOpen=true;

// 1-4. 必要な場合だけPoCXP給電を準備する：本文と同じ順番で処理する。
// 前提：Interface XMLとTransportを登録済みのCollectionを渡す。
static void enablePoCxp(KYVP_COLLECTION_HANDLE interfaceParams,
                       const char* portName, int64_t onValue) {
    KY_BOOL available=KY_FALSE;
    // 対象ノードを現在の構成で利用できるか調べる。
    check(KYParametersHandler_IsParameterAvailable_V1(
        interfaceParams,portName,&available,nullptr,nullptr), "PoCXP available");
    if (!available) throw std::runtime_error("PoCXP node unavailable");
    // XMLで確認した列挙値の数値を設定する。
    check(KYParametersHandler_SetValueEnum_V1(
        interfaceParams,portName,onValue,nullptr,nullptr), "PoCXP on");
}
// 例：PoCXP0のOn列挙値が1であることを実機のXMLで確認した場合。
// enablePoCxp(interfaceParams, "PoCXP0", 1);
// 必要な接続ポートだけを対象にし、起動待ち後にカメラを検出する。

// 1-5. カメラを検出して開く：本文と同じ順番で処理する。
KY_BOOL changed=KY_FALSE; uint32_t count=0;
for (int retry=0; retry<10; ++retry) {
    // このフレームグラバーに接続したカメラを再検出する。
    check(KYVPLibTL_IFUpdateDeviceList_V1(hPCIInterfaceHandle,&changed,500), "IFUpdateDeviceList");
    // 検出済みカメラの件数を確認する。
    check(KYVPLibTL_IFGetNumDevices_V1(hPCIInterfaceHandle,&count), "IFGetNumDevices");
    if (count>0) break;
}
const uint32_t selectedCamera=0;
if (selectedCamera>=count) throw std::runtime_error("No selected camera");
char id[128]={}; size_t size=sizeof(id);
// 開くカメラのIDを取得する。
check(KYVPLibTL_IFGetDeviceID_V1(hPCIInterfaceHandle,selectedCamera,id,&size), "IFGetDeviceID");
const KYVP_DEVICE_INFO* info=nullptr;
KYVP_INFO_DATATYPE type; size=sizeof(info);
// カメラの型番や識別情報を調べるための情報を取得する。
check(KYVPLibTL_IFGetDeviceInfo_V1(hPCIInterfaceHandle,id,
    KYVP_DEVICE_INFO_CMD_KYVP_DEVICE_INFO,&type,&info,&size), "IFGetDeviceInfo");
// カメラを制御権限付きで開く。以後、撮像条件を変更できる。
check(KYVPLibTL_IFOpenDevice_V1(hPCIInterfaceHandle,id,
    KYVP_DEVICE_ACCESS_FLAGS_CONTROL,&hLocalDeviceHandle), "IFOpenDevice");
deviceOpen=true;
uint32_t streams=0;
// カメラが持つ画像受信用Streamの数を確認する。
check(KYVPLibTL_DevGetNumDataStreams_V1(hLocalDeviceHandle,&streams), "DevGetNumDataStreams");
if (streams==0) throw std::runtime_error("Camera has no stream");
// カメラ内部のレジスタへ接続するRemote Portを取得する。
check(KYVPLibTL_DevGetPort_V1(hLocalDeviceHandle,&hRemoteDeviceHandle), "DevGetPort");

// 1-6. カメラXMLを読み込み、パラメータ操作をつなぐ：本文と同じ順番で処理する。
// XMLDescriptor、ParseXmlUrl、RemoteDevice_Transportは指定Cサンプルを使用。
// これらの関数定義とremoteDeviceXmlFileは、呼出しより前に配置する。
char cameraXmlUrl[128]={}; size_t size=sizeof(cameraXmlUrl);
// カメラ機能を定義したXMLの取得場所を調べる。
check(KYVPLibTL_RemoteDevice_GetPortURL_V1(
    hRemoteDeviceHandle,cameraXmlUrl,&size), "RemoteDevice_GetPortURL");
ParseXmlUrl(cameraXmlUrl,&remoteDeviceXmlFile,LoadXML_ModuleRegisterMap_RemoteDevice);
if (!remoteDeviceXmlFile.pData || remoteDeviceXmlFile.uSize==0)
    throw std::runtime_error("Camera XML is empty");

KYParametersHandler_InitParameters init={}; init.version=1;
// XMLを解釈するParametersHandlerを初期化する。
check(KYParametersHandler_Initialize_V1(&init,nullptr,nullptr), "ParametersHandler Initialize");
// 対象モジュール専用のパラメータ集合を作る。
check(KYParametersHandler_CreateParameterCollection_V1(
    &hRemoteDeviceParameterCollectionHandle,nullptr,nullptr), "Create camera collection");
cameraCollectionState.created=true;
// 名前による設定操作を、実際のPort読書きへつなぐ。
check(KYParametersHandler_RegisterParameterCollectionTransport_V1(
    hRemoteDeviceParameterCollectionHandle,RemoteDevice_Transport,
    nullptr,nullptr,nullptr), "Register camera transport");
cameraCollectionState.transport=true;
// 登録したXMLとTransportを使い、パラメータ操作を使用可能にする。
check(KYParametersHandler_InitializeParameterCollection_V1(
    hRemoteDeviceParameterCollectionHandle,nullptr,nullptr), "Initialize camera collection");

// 2-1. 型に合う書込み関数を用意する：本文と同じ順番で処理する。
static KYVP_NodeDescriptor* writableNode(const char* name) {
    KYVP_NodeDescriptor* node=nullptr;
    // ノードの型、書込み可否、最小値・最大値・刻み幅を調べる。
    check(KYParametersHandler_GetNodeDescriptor_V1(
        hRemoteDeviceParameterCollectionHandle,name,&node,nullptr,nullptr), name);
    if (!node || !node->m_bIsImplemented || !node->m_bIsAvailable || !node->m_bIsWritable)
        throw std::runtime_error(name);
    return node;
}
static void setInt(const char* name, int64_t value) {
    auto* n=writableNode(name);
    if (n->m_eInterfaceType!=KYVP_ParameterInterfaceType_IInteger ||
        value<n->m_nMinIntValue || value>n->m_nMaxIntValue)
        throw std::runtime_error(name);
    if (n->m_nIncIntValue>0 &&
        (static_cast<uint64_t>(value)-static_cast<uint64_t>(n->m_nMinIntValue))
            % static_cast<uint64_t>(n->m_nIncIntValue)!=0)
        throw std::runtime_error(name);
    size_t size=sizeof(value);
    // 型とサイズを合わせた値を対象パラメータへ書き込む。
    check(KYParametersHandler_SetValue_V1(hRemoteDeviceParameterCollectionHandle,
        name,&value,&size,nullptr,nullptr), name);
}
static void setFloat(const char* name, double value) {
    auto* n=writableNode(name);
    if (n->m_eInterfaceType!=KYVP_ParameterInterfaceType_IFloat || !std::isfinite(value) ||
        value<n->m_fMinFloatValue || value>n->m_fMaxFloatValue)
        throw std::runtime_error(name);
    if (n->m_fIncFloatValue>0) {
        double steps=(value-n->m_fMinFloatValue)/n->m_fIncFloatValue;
        if (std::abs(steps-std::round(steps))>1e-6) throw std::runtime_error(name);
    }
    size_t size=sizeof(value);
    // 型とサイズを合わせた値を対象パラメータへ書き込む。
    check(KYParametersHandler_SetValue_V1(hRemoteDeviceParameterCollectionHandle,
        name,&value,&size,nullptr,nullptr), name);
}
static void setEnum(const char* name, const char* value) {
    if (writableNode(name)->m_eInterfaceType!=KYVP_ParameterInterfaceType_IEnumeration)
        throw std::runtime_error(name);
    // 列挙型パラメータをOnやMono8などの値名で設定する。
    check(KYParametersHandler_SetValueEnumByValueName_V1(
        hRemoteDeviceParameterCollectionHandle,name,value,nullptr,nullptr), name);
}

// 2-2. 解像度と画像形式を設定する：本文と同じ順番で処理する。
// 撮像停止中に実行。例の値が現在のMin/Max/Incに適合することが前提。
setEnum("PixelFormat", "Mono8");
// Offsetが変更できる機種の例。中央固定の機種では対応しない軸を設定しない。
setInt("OffsetX", 0);
setInt("OffsetY", 0);
setInt("Width", 640);
setInt("Height", 480);

int64_t actualWidth=0, actualHeight=0;
size_t size=sizeof(actualWidth);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "Width",&actualWidth,&size,nullptr,nullptr), "Read Width");
size=sizeof(actualHeight);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "Height",&actualHeight,&size,nullptr,nullptr), "Read Height");

// 2-3. 連続撮像、フレームレート、露光時間を設定する：本文と同じ順番で処理する。
setEnum("AcquisitionMode", "Continuous");
setEnum("ExposureMode", "Timed");
setEnum("TriggerSelector", "ExposureStart");
setEnum("TriggerMode", "Off");
// 実機で他のTriggerSelectorを使っていた場合は、その有効状態も確認する。
// ExposureAutoやAcquisitionFrameRateEnableが存在する機種では事前に確認する。
setFloat("ExposureTime", 1000.0);          // 1 ms
setFloat("AcquisitionFrameRate", 100.0);   // 100 fps
double actualExposure=0, actualFps=0;
size_t size=sizeof(actualExposure);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "ExposureTime",&actualExposure,&size,nullptr,nullptr), "Read ExposureTime");
size=sizeof(actualFps);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "AcquisitionFrameRate",&actualFps,&size,nullptr,nullptr), "Read AcquisitionFrameRate");

// 2-4. ゲインを設定する：本文と同じ順番で処理する。
// XML上でGainがFloat型として提供されている機種の例。
// GainAutoがある機種では、手動設定の前にOffへ切り替える。
setFloat("Gain", 0.0);
double actualGain=0.0;
size_t size=sizeof(actualGain);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "Gain",&actualGain,&size,nullptr,nullptr), "Read Gain");
printf("Gain = %.3f dB\n", actualGain);

// OptrAnalogGainは別の機種依存機能。通常のGainの代替として自動設定しない。
// 型・可用性・メーカーの適用条件を確認してから専用に実装する。

// 2-6. OptrImageStampを有効にして読み戻す：本文と同じ順番で処理する。
setEnum("OptrImageStamp", "On");
char stampMode[32]={}; size_t size=sizeof(stampMode);
// 適用された列挙値を文字列で読み戻す。
check(KYParametersHandler_GetValueEnumAsString_V1(
    hRemoteDeviceParameterCollectionHandle,"OptrImageStamp",
    stampMode,&size,nullptr,nullptr), "Read OptrImageStamp");
stampMode[sizeof(stampMode)-1]='\0';
if (std::strcmp(stampMode,"On")!=0)
    throw std::runtime_error("Image stamp was not enabled");
// 読み戻した結果を保持し、Callback内で毎回パラメータを問い合わせない。

// 2-7. 読み戻した画像条件を受信側へ通知する：本文と同じ順番で処理する。
int64_t width=0,height=0; uint64_t formatValue=0;
size_t size=sizeof(width);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "Width",&width,&size,nullptr,nullptr), "Read Width");
size=sizeof(height);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "Height",&height,&size,nullptr,nullptr), "Read Height");
size=sizeof(formatValue);
// 現在の実値を読み戻す。sizeは呼出しごとに設定する。
check(KYParametersHandler_GetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "PixelFormat",&formatValue,&size,nullptr,nullptr), "Read PixelFormat value");
if (width<=0 || height<=0 || uint64_t(width)>UINT32_MAX || uint64_t(height)>UINT32_MAX)
    throw std::runtime_error("Invalid image size");
KYVP_DEVICE_IMAGE_DETAILS details={}; details.m_uVersion=1;
details.m_uWidth=uint32_t(width); details.m_uHeight=uint32_t(height);
details.m_uPixelFormat=uint32_t(formatValue);
size=sizeof(details.m_szPixelFormatName);
// 適用された列挙値を文字列で読み戻す。
check(KYParametersHandler_GetValueEnumAsString_V1(hRemoteDeviceParameterCollectionHandle,
    "PixelFormat",details.m_szPixelFormatName,&size,nullptr,nullptr), "Read PixelFormat name");
KY_BOOL tapAvailable=KY_FALSE;
// 対象ノードを現在の構成で利用できるか調べる。
check(KYParametersHandler_IsParameterAvailable_V1(hRemoteDeviceParameterCollectionHandle,
    "DeviceTapGeometry",&tapAvailable,nullptr,nullptr), "DeviceTapGeometry available");
if (tapAvailable) {
    size=sizeof(details.m_szTapGeometryType);
    // 適用された列挙値を文字列で読み戻す。
    check(KYParametersHandler_GetValueEnumAsString_V1(hRemoteDeviceParameterCollectionHandle,
        "DeviceTapGeometry",details.m_szTapGeometryType,&size,nullptr,nullptr), "Read tap geometry");
}
// 確定した画像条件をカメラ接続の受信側へ知らせる。
check(KYVPExtension_RemoteDevice_SetImageDetails_V1(hRemoteDeviceHandle,details), "SetImageDetails");

// 3-1. Streamを開き、転送形式を確定する：本文と同じ順番で処理する。
uint32_t count=0;
// カメラが持つ画像受信用Streamの数を確認する。
check(KYVPLibTL_DevGetNumDataStreams_V1(hLocalDeviceHandle,&count), "DevGetNumDataStreams");
if (count==0) throw std::runtime_error("No stream");
char id[128]={}; size_t size=sizeof(id);
// 指定インデックスのStreamを識別するIDを取得する。
check(KYVPLibTL_DevGetDataStreamID_V1(hLocalDeviceHandle,0,id,&size), "DevGetDataStreamID");
// 画像の受信経路を開く。この時点では撮像を開始しない。
check(KYVPLibTL_DevOpenDataStream_V1(hLocalDeviceHandle,id,&hStreamHandle), "DevOpenDataStream");
streamOpen=true;
char url[128]={}; size=sizeof(url);
// 受信側の設定を定義したStream XMLの場所を取得する。
check(KYVPLibTL_Stream_GetPortURL_V1(hStreamHandle,url,&size), "Stream_GetPortURL");
ParseXmlUrl(url,&streamXmlFile,LoadXML_ModuleRegisterMap_Stream);
if (!streamXmlFile.pData || streamXmlFile.uSize==0) throw std::runtime_error("Stream XML is empty");
// 対象モジュール専用のパラメータ集合を作る。
check(KYParametersHandler_CreateParameterCollection_V1(
    &hStreamParameterCollectionHandle,nullptr,nullptr), "Create stream collection");
streamCollectionState.created=true;
// 名前による設定操作を、実際のPort読書きへつなぐ。
check(KYParametersHandler_RegisterParameterCollectionTransport_V1(
    hStreamParameterCollectionHandle,Stream_Transport,nullptr,nullptr,nullptr), "Register stream transport");
streamCollectionState.transport=true;
// 登録したXMLとTransportを使い、パラメータ操作を使用可能にする。
check(KYParametersHandler_InitializeParameterCollection_V1(
    hStreamParameterCollectionHandle,nullptr,nullptr), "Initialize stream collection");
// 列挙型パラメータをOnやMono8などの値名で設定する。
check(KYParametersHandler_SetValueEnumByValueName_V1(
    hStreamParameterCollectionHandle,"PackedDataMode","Unpacked",nullptr,nullptr), "PackedDataMode");

// 3-2. 受信通知を登録し、受信バッファをQueueする：本文と同じ順番で処理する。
// 以下はCallbackからも参照する共有変数として定義する。
static constexpr size_t NUMBER_OF_BUFFERS=16;
static KYVP_BUFFER_HANDLE buffers[NUMBER_OF_BUFFERS];
static size_t allocatedBuffers=0, payloadBytes=0;
// StreamCallbackは3-5で定義し、ここより前に同じ宣言を置く。
// 画像到着時に実行する関数を、取得開始前に登録する。
check(KYVPExtension_DataStream_Callback_Register_V1(
    hStreamHandle,StreamCallback,nullptr), "Register callback");
callbackRegistered=true;
KYVP_INFO_DATATYPE type; size_t size=sizeof(payloadBytes);
// Streamの情報を取得する。ここでは必要な受信領域サイズを調べる。
check(KYVPLibTL_DSGetInfo_V1(hStreamHandle,KYVP_STREAM_INFO_CMD_PAYLOAD_SIZE,
    &type,&payloadBytes,&size), "Get payload size");
if (payloadBytes==0) throw std::runtime_error("Empty payload");
for (size_t i=0;i<NUMBER_OF_BUFFERS;++i) {
    // SDKに受信領域を確保させ、Streamへ登録する。
    check(KYVPLibTL_DSAllocAndAnnounceBuffer_V1(
        hStreamHandle,payloadBytes,nullptr,&buffers[i]), "Allocate buffer");
    ++allocatedBuffers;
    // バッファを次の受信に利用できる状態へ戻す。二重Queueしない。
    check(KYVPLibTL_DSQueueBuffer_V1(hStreamHandle,buffers[i]), "Queue buffer");
}

// 3-3. 100枚分の録画RAMを準備する：本文と同じ順番で処理する。
struct Stamp {
    uint16_t imageCounter=0,triggerCounter=0,offsetX=0,offsetY=0;
    uint32_t microseconds=0;
};
static constexpr size_t recordFrames=100;
static std::vector<uint8_t> recordingMemory;
static std::vector<Stamp> imageStamps;
static std::vector<uint64_t> kayaTimes;
static std::atomic<size_t> recorded{0};
static std::atomic<bool> recording{false},receiveFailed{false};
static std::mutex copyMutex;
if (payloadBytes<11 || recordFrames>(std::numeric_limits<size_t>::max)()/payloadBytes)
    throw std::runtime_error("Invalid recording allocation size");
// 受信バッファとは別に、全フレームを保持する領域を先に確保する。
recordingMemory.resize(payloadBytes*recordFrames);
// 画像と同じ添字で、カメラ側StampとKAYA側の時刻を保存する。
imageStamps.resize(recordFrames);
kayaTimes.assign(recordFrames,0);
recorded=0; recording=false; receiveFailed=false;

// 3-4. Mono8のOptrImageStampを読み取る：本文と同じ順番で処理する。
static Stamp readMono8Stamp(const uint8_t* p) {
    Stamp s;
    // 先頭2画素を上位・下位として連結し、画像カウンターを復元する。
    s.imageCounter = uint16_t((uint16_t(p[0])<<8)|p[1]);
    // 3画素を連結する。単位はµs、値の幅は24 bit。
    s.microseconds = (uint32_t(p[2])<<16)|(uint32_t(p[3])<<8)|p[4];
    // カメラが受理した外部トリガーの数を読む。
    s.triggerCounter = uint16_t((uint16_t(p[5])<<8)|p[6]);
    // この画像に対応するROIの横方向・縦方向の位置を読む。
    s.offsetX = uint16_t((uint16_t(p[7])<<8)|p[8]);
    s.offsetY = uint16_t((uint16_t(p[9])<<8)|p[10]);
    return s;
}
// 呼出し条件：Mono8、Stamp=On、画像先頭アドレス、11バイト以上を確認済み。
// 24-bit時刻の差分例（間隔が1周未満の場合に限る）：
// uint32_t deltaUs=(current.microseconds-previous.microseconds)&0x00FFFFFFu;

// 3-5. Callbackで画像をコピーしてバッファを返す：本文と同じ順番で処理する。
static void KYVP_CALLCONV StreamCallback(KYVP_BUFFER_HANDLE buffer,void*) {
    if (KYVPLibTL_BufferHandleIsNull(buffer)) return;
    std::lock_guard<std::mutex> guard(copyMutex);
    const KYVP_BUFFER_INFO* info=nullptr;
    KYVP_INFO_DATATYPE type; size_t size=sizeof(info);
    // 受信したバッファの先頭アドレスや時刻情報を取得する。
    KY_RESULT r=KYVPLibTL_DSGetBufferInfo_V1(hStreamHandle,buffer,
        KYVP_BUFFER_INFO_CMD_KYVP_BUFFER_INFO,&type,&info,&size);
    if (KY_RESULT_FAILED(r) || !info || !info->m_pBase) {
        receiveFailed=true;
    } else if (recording.load()) {
        size_t i=recorded.load();
        if (i<recordFrames) {
            // 完全な画像でコピー可能な長さであることをSDKの情報で確認する。
            // この最小断片は正常なMono8フレームを前提とする。
            auto* pixels=static_cast<const uint8_t*>(info->m_pBase);
            // i枚目の保存位置へコピーする。Queue前にコピーを終える。
            std::memcpy(recordingMemory.data()+i*payloadBytes,pixels,payloadBytes);
            imageStamps[i]=readMono8Stamp(pixels);
            uint64_t timeNs=0; size=sizeof(timeNs);
            // 受信したバッファの先頭アドレスや時刻情報を取得する。
            if (KY_RESULT_SUCCEEDED(KYVPLibTL_DSGetBufferInfo_V1(hStreamHandle,buffer,
                    KYVP_BUFFER_INFO_CMD_TIMESTAMP_NS_CHRONO,&type,&timeNs,&size)))
                kayaTimes[i]=timeNs;
            // 画像と付随情報を書き終えてから、完了枚数を公開する。
            recorded.store(i+1);
            if (i+1==recordFrames) recording=false;
        }
    }
    // バッファを次の受信に利用できる状態へ戻す。二重Queueしない。
    if (KY_RESULT_FAILED(KYVPLibTL_DSQueueBuffer_V1(hStreamHandle,buffer)))
        receiveFailed=true;
}

// 3-6. 受信側、カメラ側の順に取得を開始する：本文と同じ順番で処理する。
recording=true;
// カメラの送信を始める前に、フレームグラバー側の受信を開始する。
check(KYVPLibTL_DSStartAcquisition_V1(hStreamHandle,
    KYVP_ACQ_START_FLAGS_DEFAULT,0), "DSStartAcquisition");
streamStarted=true;
int64_t startValue=1; size_t size=sizeof(startValue);
cameraStartAttempted=true;
// 型とサイズを合わせた値を対象パラメータへ書き込む。
check(KYParametersHandler_SetValue_V1(hRemoteDeviceParameterCollectionHandle,
    "AcquisitionStart",&startValue,&size,nullptr,nullptr), "AcquisitionStart");
const ULONGLONG begin=GetTickCount64();
bool timedOut=false;
while (recorded.load()<recordFrames && !receiveFailed.load()) {
    if (GetTickCount64()-begin>30000) { timedOut=true; break; }
    Sleep(10);
}
recording=false;
// 次は必ず第4章の停止へ進む。ここではRAMを解放しない。

// 3-7. 参考：PDFのイベント方式との対応：本文と同じ順番で処理する。
// Direct Callback方式の代わりに使う場合のみ。
KYVP_EVENT_HANDLE eventHandle;
// Direct Callbackの代わりにNEW_BUFFERイベントを登録する。
check(KYVPLibTL_DSRegisterEvent_V1(hStreamHandle,
    KYVP_EVENT_TYPE_NEW_BUFFER,&eventHandle), "DSRegisterEvent");
// 専用スレッドのループ内：
KYVPLIBTL_EVENT_NEW_BUFFER_DATA eventData={};
size_t size=sizeof(eventData);
// 受信スレッドで新しい画像を待つ。無期限待ちを避ける。
KY_RESULT r=KYVPLibTL_EventGetData_V1(eventHandle,&eventData,&size,1000);
if (KY_RESULT_SUCCEEDED(r) && !KYVPLibTL_BufferHandleIsNull(eventData.hBufferHandle))
    StreamCallback(eventData.hBufferHandle,nullptr);
// 上の関数が再Queueするため、ここでは二重にQueueしない。

// 4-1. Streamとカメラの取得を停止する：本文と同じ順番で処理する。
recording=false;
bool stopOk=true;
if (streamStarted) {
    // Streamの受信を停止する。続いてカメラ側も止める。
    KY_RESULT r=KYVPLibTL_DSStopAcquisition_V1(hStreamHandle,KYVP_ACQ_STOP_FLAGS_DEFAULT);
    if (KY_RESULT_SUCCEEDED(r)) streamStarted=false;
    else stopOk=false;
}
if (cameraStartAttempted) {
    int64_t value=0; size_t size=sizeof(value);
    // 型とサイズを合わせた値を対象パラメータへ書き込む。
    KY_RESULT r=KYParametersHandler_SetValue_V1(hRemoteDeviceParameterCollectionHandle,
        "AcquisitionStop",&value,&size,nullptr,nullptr);
    if (KY_RESULT_SUCCEEDED(r)) cameraStartAttempted=false;
    else stopOk=false;
}
// stopOkがfalseなら失敗を保存し、正常停止した前提でメモリを解放しない。

// 4-2. 通知を解除し、受信処理の終了を確認する：本文と同じ順番で処理する。
if (callbackRegistered) {
    // 登録時と同じ関数を指定し、画像到着通知を解除する。
    KY_RESULT r=KYVPExtension_DataStream_Callback_Unregister_V1(hStreamHandle,StreamCallback);
    if (KY_RESULT_SUCCEEDED(r)) callbackRegistered=false;
    else stopOk=false;
}
// イベント方式のみ：終了フラグ通知 → 受信スレッドjoin → 下記解除。
// KYVPLibTL_DSUnregisterEvent_V1(hStreamHandle,KYVP_EVENT_TYPE_NEW_BUFFER);

// 使用SDKの停止／解除契約に従い、新規通知がなく、実行中Callbackも
// 終了したことを確認する。終了確認前には次の段階へ進まない。

// 4-3. 録画結果を確定して画像を利用する：本文と同じ順番で処理する。
// 前提：4-1と4-2が成功し、受信処理の終了確認が済んでいる。
const size_t captured=recorded.load();
const bool complete=(captured==recordFrames && !receiveFailed.load());
for (size_t i=0;i<captured;++i) {
    const uint8_t* frame=recordingMemory.data()+i*payloadBytes;
    const Stamp& stamp=imageStamps[i];
    const uint64_t hostTimeNs=kayaTimes[i];
    // frameとstampを必要な処理へ渡す。所有メモリなのでこの時点では有効。
    // ファイル保存する場合もCallback内ではなくここで行う。
}
printf("Recorded %zu frames (%s)\n",captured,complete?"complete":"partial/error");

// 4-4. 受信バッファの登録を解除する：本文と同じ順番で処理する。
bool allRevoked=true;
for (size_t i=0;i<allocatedBuffers;++i) {
    void* memory=nullptr; void* context=nullptr;
    // 受信処理終了後、Streamから受信バッファの登録を取り外す。
    KY_RESULT r=KYVPLibTL_DSRevokeBuffer_V1(hStreamHandle,buffers[i],&memory,&context);
    if (KY_RESULT_FAILED(r)) { allRevoked=false; continue; }
    // 解除済みフラグをバッファごとに記録し、再試行で二重解除しない。
    // DSAllocAndAnnounceBufferの領域はSDK所有。free(memory)しない。
}
if (allRevoked) allocatedBuffers=0;
// ユーザー確保方式のみ：Revoke成功後に元の確保方法に対応した解放を行う。
// _aligned_malloc → _aligned_free、cudaHostAlloc → cudaFreeHost。

// 4-5. パラメータコレクションを片付ける：本文と同じ順番で処理する。
// CollectionStateは1-2で宣言済み。第1・3章で成功状態を記録する。
static bool closeCollection(KYVP_COLLECTION_HANDLE& h,CollectionState& s) {
    if (!s.created) return true;
    if (s.callback) {
        // 登録済みの場合だけ、パラメータ変更通知を解除する。
        if (KY_RESULT_FAILED(KYParametersHandler_UnregisterParameterCollectionCallback_V1(
            h,nullptr,nullptr))) return false;
        s.callback=false;
    }
    if (s.transport) {
        // パラメータ集合とPort操作の結び付きを解除する。
        if (KY_RESULT_FAILED(KYParametersHandler_UnregisterParameterCollectionTransport_V1(
            h,nullptr,nullptr))) return false;
        s.transport=false;
    }
    // パラメータ集合を削除する。XMLはこの成功後に解放できる。
    if (KY_RESULT_FAILED(KYParametersHandler_DeleteParameterCollection_V1(h,nullptr,nullptr)))
        return false;
    h=KYVP_COLLECTION_HANDLE_INVALID; s.created=false;
    return true;
}

// 4-6. Streamを閉じる：本文と同じ順番で処理する。
// 前提：通知解除、受信終了確認、Revokeが完了。
// streamCollectionStateは3-1のCreate/Register成功を記録した状態。
if (!closeCollection(hStreamParameterCollectionHandle,streamCollectionState))
    return false; // boolを返す終了関数内の例
if (streamOpen) {
    // 通知とバッファを片付けたStreamを閉じる。
    KY_RESULT r=KYVPLibTL_DSClose_V1(hStreamHandle);
    if (KY_RESULT_FAILED(r)) return false;
    hStreamHandle=KYVP_STREAM_HANDLE_INVALID;
    streamOpen=false;
}
// streamXmlFileのpData/name、動的確保したStream URL/IDは所有分を解放してNULLへ。

// 4-7. カメラを閉じる：本文と同じ順番で処理する。
// 前提：このカメラの全Streamをクローズ済み。
if (!closeCollection(hRemoteDeviceParameterCollectionHandle,cameraCollectionState))
    return false;
// Deviceイベントを原本のAPIで登録した場合のみ、同じ関数を指定して解除。
// KYVPExtension_Device_EventCallBackUnregister_V1(
//     hLocalDeviceHandle,Device_EventCallBackImpl);
// 解除の成否とイベント処理終了を確認してから進む。
if (deviceOpen) {
    // 全Streamを閉じたカメラの接続を終了する。
    KY_RESULT r=KYVPLibTL_DevClose_V1(hLocalDeviceHandle);
    if (KY_RESULT_FAILED(r)) return false;
    hLocalDeviceHandle=KYVP_DEVICE_HANDLE_INVALID;
    hRemoteDeviceHandle=KYVP_REMOTE_DEVICE_HANDLE_INVALID;
    deviceOpen=false;
}
// カメラXML本体・名前・動的URLは、Collectionの参照終了後に解放。

// 4-8. フレームグラバーとSDKを閉じる：本文と同じ順番で処理する。
// 任意登録の対になる解除。登録した場合だけ成否を確認して実行。
// KYVPExtension_PCIInterface_EventCallBackUnregister_V1(
//     hPCIInterfaceHandle,PCIInterface_EventCallBackImpl);
// KYVPExtension_AuxDataCallback_Unregister_Args args={};
// args.version=1; args.hIFHandle=hPCIInterfaceHandle;
// args.pCallbackFunction=PCIInterface_AuxEventCallBackImpl;
// KYVPExtension_PCIInterface_AuxDataCallback_Unregister(&args);
// 自分がONにしたPoCXPを必要に応じてOFF → Interface Collection/XMLを解放。
if (interfaceOpen) {
    // 全カメラを閉じたフレームグラバーを終了する。
    if (KY_RESULT_FAILED(KYVPLibTL_IFClose_V1(hPCIInterfaceHandle))) return false;
    hPCIInterfaceHandle=KYVP_PCI_INTERFACE_HANDLE_INVALID; interfaceOpen=false;
}
if (tlOpen) {
    // 全Interfaceを閉じた後に親モジュールTLを終了する。
    if (KY_RESULT_FAILED(KYVPLibTL_TLClose_V1(hTLHandle))) return false;
    hTLHandle=KYVP_TL_HANDLE_INVALID; tlOpen=false;
}
if (libraryReady) {
    // SDKが保持する全体リソースを終了する。
    if (KY_RESULT_FAILED(KYVPLibTL_CloseLib())) return false;
    libraryReady=false;
}
std::vector<uint8_t>().swap(recordingMemory);
std::vector<Stamp>().swap(imageStamps);
std::vector<uint64_t>().swap(kayaTimes);

// 4-9. 成功時と失敗時を同じ終了経路へ集める：本文と同じ順番で処理する。
// 構造を示す疑似コード。下記の関数名はSDK APIではない。
int result=0;
try {
    // 第1章：SDK・FG・カメラ・Collectionを準備
    // 第2章：画像形式・露光・ゲイン・Stamp・SetImageDetails
    // 第3章：Stream・Buffer・RAM・取得・待機
} catch (const std::exception& e) {
    std::fprintf(stderr,"Operation failed: %s\n",e.what());
    result=1;
}
// 第4章を、成功した操作の状態に応じて実行。
// 停止 → 通知終了 → 結果利用 → Buffer → Collection/Stream
// → Collection/Device → Interface → TL/SDK → 所有RAM
// 解放に失敗した場合はresult=1として未解放対象を記録する。
return result;