xrcap header

// Copyright 2019 (c) Christopher A. Taylor.  All rights reserved.

/*
    Xrcap capture client C API for the RGBD Capture Server.
    Built on top of CaptureClient.hpp
*/


//------------------------------------------------------------------------------
// C Boilerplate

#ifndef CAPTURE_CLIENT_H
#define CAPTURE_CLIENT_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#if defined(XRCAP_BUILDING)
# if defined(XRCAP_DLL) && defined(_WIN32)
    #define XRCAP_EXPORT __declspec(dllexport)
# else
    #define XRCAP_EXPORT
# endif
#else
# if defined(XRCAP_DLL) && defined(_WIN32)
    #define XRCAP_EXPORT __declspec(dllimport)
# else
    #define XRCAP_EXPORT extern
# endif
#endif


//------------------------------------------------------------------------------
// Constants

#define XRCAP_VERSION 0

#define XRCAP_DIRECT_PORT 28772
#define XRCAP_RENDEZVOUS_PORT 28773

typedef enum XrcapState_t {
    XrcapState_Connecting        = 0,
    XrcapState_Authenticating    = 1,
    XrcapState_NoVideo           = 2,
    XrcapState_Streaming         = 3,
    XrcapState_Error             = 4,
} XrcapState;

typedef enum XrcapMode_t {
    XrcapMode_Disabled           = 0,
    XrcapMode_Calibration        = 1,
    XrcapMode_Capture            = 2,
} XrcapMode;

typedef enum XrcapCaptureStatus_t {
    XrcapCaptureStatus_Idle                      = 0,
    XrcapCaptureStatus_Initializing              = 1,
    XrcapCaptureStatus_Capturing                 = 2,
    XrcapCaptureStatus_NoCameras                 = 3,
    XrcapCaptureStatus_BadUsbConnection          = 4,
    XrcapCaptureStatus_FirmwareVersionMismatch   = 5,
    XrcapCaptureStatus_SyncCableMisconfigured    = 6,
} XrcapCaptureStatus;

typedef enum XrcapCameraCodes_t {
    XrcapCameraCodes_Idle           = 0,
    XrcapCameraCodes_Initializing   = 1,
    XrcapCameraCodes_StartFailed    = 2,
    XrcapCameraCodes_Capturing      = 3,
    XrcapCameraCodes_ReadFailed     = 4,
    XrcapCameraCodes_SlowWarning    = 5,
} XrcapCameraCodes;

typedef enum XrcapNetwork_t {
    XrcapNetwork_Idle                       = 0,
    XrcapNetwork_Connecting                 = 1,
    XrcapNetwork_RendezvousServerOffline    = 2,
    XrcapNetwork_WaitingForCaptureServer    = 3,
    XrcapNetwork_Connected                  = 4,
} XrcapNetwork;


//------------------------------------------------------------------------------
// Perspective

// Perspective includes a texture to render and a mesh description
typedef struct XrcapPerspective_t {
    // Check this first.  If Valid = 0, then do not render.
    int32_t Valid;

    // Number for this camera for this perspective
    int32_t CameraNumber;

    // Size of image and Y channel
    int32_t Width, Height;
    uint8_t* Y;

    // Size of U, V channels
    // Note: YUV channels follow eachother contiguously in memory.
    int32_t ChromaWidth, ChromaHeight;
    uint8_t* U;
    uint8_t* V;

    // Number of indices (multiple of 3) for triangles to render
    uint32_t IndicesCount;
    uint32_t* Indices;

    // Vertices for mesh represented as repeated: x,y,z,u,v
    uint32_t FloatCount;
    float* XyzuvVertices;
} XrcapPerspective;


//------------------------------------------------------------------------------
// Frame

typedef struct XrcapFrame_t {
    // Check this first.  If Valid = 0, then do not render.
    int32_t Valid;

    // Number for this frame.
    // Increments once for each frame to display.
    int32_t FrameNumber;

    // Exposure time in microseconds since the UNIX epoch.
    uint64_t ExposureEpochUsec;

    // Two perspectives to render.
    XrcapPerspective Perspectives[2];

    // XrcapState: Library status.
    int32_t LibraryStatus;

    // XrcapMode: App mode from xrcap_set_server_capture_mode().
    int32_t Mode;

    // XrcapNetwork: Connection status
    int32_t NetworkStatus;

    // XrcapCaptureStatus: Status of the capture server.
    int32_t ServerStatus;

    // Number of cameras attached to the server.
    int32_t CameraCount;

    // XrcapCameraCodes: Status code for each camera on the server.
    int32_t CameraCodes[8];

    // Bits per second received from server
    int32_t BitsPerSecond;
} XrcapFrame;


//------------------------------------------------------------------------------
// API

/*
    All functions are safe to call repeatedly each frame and will not slow down
    rendering of the application.

    Call xrcap_frame() to receive the current frame to render, which may be the
    same frame as the previous call.  Check `FrameNumber` to see if it changed.

    To start or stop capture remotely use xrcap_set_server_capture_mode().
*/

// Connect to rendezvous or capture server (direct).
XRCAP_EXPORT void xrcap_connect(
    const char* server_address,
    int32_t server_port,
    const char* session_name,
    const char* password
);

// This should be called every frame.
// Fills the frame with the current state.
// The structure indicates if a mesh can be rendered this frame or if there is
// an error status.
// Calling this invalidates data from the previous frame.
XRCAP_EXPORT void xrcap_frame(XrcapFrame* frame);

// Set capture server mode.
XRCAP_EXPORT void xrcap_set_server_capture_mode(int32_t mode);

// Blocks until shutdown is complete
XRCAP_EXPORT void xrcap_shutdown();


//------------------------------------------------------------------------------
// C Boilerplate

#ifdef __cplusplus
} // extern "C"
#endif

#endif // CAPTURE_CLIENT_H