//
//  VKTMultiCameraDevice.h
//  VideoKit
//
//  Created by Yusuf Olokoba on 11/23/2024.
//  Copyright © 2025 Yusuf Olokoba. All rights reserved.
//

#pragma once

#include <VideoKit/VKTCameraDevice.h>
#include <VideoKit/VKTPixelBuffer.h>

#pragma region --Types--
/*!
 @typedef VKTMultiCameraDevice
 
 @abstract Multi-camera device.

 @discussion Multi-camera device.
*/
typedef VKTMediaDevice VKTMultiCameraDevice;

/*!
 @typedef VKTMultiCameraDevicePixelBuffer
 
 @abstract Pixel buffer generated by a multi-camera device.

 @discussion Pixel buffer generated by a multi-camera device.
 This type enables access to additional metadata from the multi-camera device.
*/
typedef VKTPixelBuffer VKTMultiCameraPixelBuffer;

/*!
 @abstract Callback invoked when a mulit-camera device's system pressure level changes.
 
 @param context
 User-provided context.
*/
typedef void (*VKTMultiCameraDeviceSystemPressureChangeHandler) (void* context);
#pragma endregion


#pragma region --Discovery--
/*!
 @function VKTMultiCameraDeviceDiscoverDevices

 @abstract Discover available multi-camera devices.

 @discussion Discover available mulit-camera devices.

 @param handler
 Device handler. MUST NOT be `NULL`.

 @param context
 Handler context.

 @returns Status.
*/
VKT_API VKTStatus VKTMultiCameraDeviceDiscoverDevices (
    VKTMediaDeviceDiscoveryHandler handler,
    void* context
);
#pragma endregion


#pragma region --Inspection--
/*!
 @function VKTMultiCameraDeviceGetCameraDeviceCount

 @abstract Get the number of camera devices in a given multi-camera device.

 @discussion Get the number of camera devices in a given multi-camera device.

 @param device
 Multi-camera device.

 @param count
 Output camera count.
*/
VKT_API VKTStatus VKTMultiCameraDeviceGetCameraDeviceCount (
    VKTMultiCameraDevice* device,
    int32_t* count
);

/*!
 @function VKTMultiCameraDeviceGetCameraDevice

 @abstract Get the camera device at a given index in the multi-camera device.

 @discussion Get the camera device at a given index in the multi-camera device.

 @param device
 Multi-camera device.

 @param index
 Camera index.

 @param camera
 Output camera.
 This pointer MUST NOT be released.
*/
VKT_API VKTStatus VKTMultiCameraDeviceGetCameraDevice (
    VKTMultiCameraDevice* device,
    int32_t index,
    VKTCameraDevice** camera
);
#pragma endregion


#pragma region --Streaming--
/*!
 @function VKTMultiCameraDeviceIsCameraDeviceRunning

 @abstract Check whether a camera device in the multi-camera device is running.

 @discussion Check whether a camera device in the multi-camera device is running.

 @param device
 Multi-camera device.

 @param camera
 Camera device to check.
 This device MUST be in the multi-camera device.

 @param running
 Output result.
*/
VKT_API VKTStatus VKTMultiCameraDeviceIsCameraDeviceRunning (
    VKTMultiCameraDevice* device,
    VKTCameraDevice* camera,
    bool* running
);

/*!
 @function VKTMultiCameraDeviceStartCameraDevice

 @abstract Start running a camera device in the multi-camera device.

 @discussion Start running a camera device in the multi-camera device.

 @param device
 Multi-camera device.

 @param camera
 Camera device to stream.
 This device MUST be in the multi-camera device.
*/
VKT_API VKTStatus VKTMultiCameraDeviceStartCameraDevice (
    VKTMultiCameraDevice* device,
    VKTCameraDevice* camera
);

/*!
 @function VKTMultiCameraDeviceStopCameraDevice

 @abstract Stop running a camera device in the multi-camera device.

 @discussion Stop running a camera device in the multi-camera device.

 @param device
 Multi-camera device.

 @param camera
 Camera device to stop streaming.
 This device MUST be in the multi-camera device.
*/
VKT_API VKTStatus VKTMultiCameraDeviceStopCameraDevice (
    VKTMultiCameraDevice* device,
    VKTCameraDevice* camera
);
#pragma endregion


#pragma region --Pressure Management--
/*!
 @function VKTMultiCameraDeviceGetHardwareCost

 @abstract Get the hardware cost of the multi-camera device.

 @discussion Get the hardware cost of the multi-camera device.

 @param device
 Multi-camera device.

 @param cost
 Output hardware cost.
*/
VKT_API VKTStatus VKTMultiCameraDeviceGetHardwareCost (
    VKTMultiCameraDevice* device,
    float* cost
);

/*!
 @function VKTMultiCameraDeviceGetSystemPressureCost

 @abstract Get the current system pressure cost of the multi-camera device.

 @discussion Get the current system pressure cost of the multi-camera device.

 @param device
 Multi-camera device.

 @param cost
 Output system pressure cost.
*/
VKT_API VKTStatus VKTMultiCameraDeviceGetSystemPressureCost (
    VKTMultiCameraDevice* device,
    float* cost
);

/*!
 @function VKTMultiCameraDeviceSetSystemPressureChangeHandler

 @abstract Set the multi-camera device system pressure change handler.

 @discussion Set the multi-camera device system pressure change handler.

 @param device
 Multi-camera device.

 @param handler
 System pressure change handler.
 Can be `NULL` to remove the current handler.

 @param context
 User context.
*/
VKT_API VKTStatus VKTMultiCameraDeviceSetSystemPressureChangeHandler (
    VKTMultiCameraDevice* device,
    VKTMultiCameraDeviceSystemPressureChangeHandler handler,
    void* context
);
#pragma endregion


#pragma region --Pixel Buffer--
/*!
 @function VKTMultiCameraPixelBufferGetCameraDevice

 @abstract Get the camera device that generated the pixel buffer.

 @discussion Get the camera device that generated the pixel buffer.

 @param pixelBuffer
 Multi-camera pixel buffer.

 @param camera
 Output camera device.
*/
VKT_API VKTStatus VKTMultiCameraPixelBufferGetCameraDevice (
    VKTMultiCameraPixelBuffer* pixelBuffer,
    VKTCameraDevice** camera
);
#pragma endregion