316 lines
13 KiB
C
316 lines
13 KiB
C
/********************************************************************************************
|
|
* Twitch Broadcasting SDK
|
|
*
|
|
* This software is supplied under the terms of a license agreement with Justin.tv Inc. and
|
|
* may not be copied or used except in accordance with the terms of that agreement
|
|
* Copyright (c) 2012-2013 Justin.tv Inc.
|
|
*********************************************************************************************/
|
|
|
|
#ifndef TTVSDK_TWITCH_WEBCAM_H
|
|
#define TTVSDK_TWITCH_WEBCAM_H
|
|
|
|
#include "twitchsdktypes.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDeviceChange - Listing of the events which occur when a new device is plugged in or a device is unplugged from the system.
|
|
*/
|
|
typedef enum
|
|
{
|
|
TTV_WEBCAM_DEVICE_FOUND, //!< The device was plugged in and is ready to be started.
|
|
TTV_WEBCAM_DEVICE_LOST //!< The device was unplugged and is unavailable. If it was capturing you will not receive a stop notification.
|
|
|
|
} TTV_WebCamDeviceChange;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDeviceStatus - Listing of the states a device may be in once it is available in the system.
|
|
*/
|
|
typedef enum
|
|
{
|
|
TTV_WEBCAM_DEVICE_UNINITIALIZED, //!< The device hasn't been initialized.
|
|
TTV_WEBCAM_DEVICE_STARTED, //!< The device is currently capturing.
|
|
TTV_WEBCAM_DEVICE_STOPPED //!< The device is not currently capturing.
|
|
|
|
} TTV_WebCamDeviceStatus;
|
|
|
|
|
|
/**
|
|
* TTV_WebcamFormat - Listing of the various formats a device may return a buffer in. If you are unable to handle a buffer format in your application
|
|
* you may call TTV_WebCam_ConvertToRGBA to convert the buffer to RGBA.
|
|
*/
|
|
typedef enum
|
|
{
|
|
TTV_WEBCAM_FORMAT_UNKNOWN,
|
|
|
|
// compressed video types
|
|
//H264, // Not supported for now, since each frame can have a different size
|
|
|
|
// NOTE: The following format names do not match their actual memory layout.
|
|
// For example, ARGB32 is actually laid out in memory as BGRA.
|
|
// This naming is inconsistent with the rest of the SDK (which has names that match the memory layout).
|
|
// The reasoning for this is to match Direct3D, which also names things backwards.
|
|
// That way when a webcam provides ARGB a user can create a texture of ARGB and not be confused.
|
|
// See http://msdn.microsoft.com/en-us/library/windows/desktop/bb153349%28v=vs.85%29.aspx
|
|
|
|
// NOTE: The following format names do not match their actual memory layout.
|
|
// For example, ARGB32 is actually laid out in memory as BGRA.
|
|
// This naming is inconsistent with the rest of the SDK (which has names that match the memory layout).
|
|
// The reasoning for this is to match Direct3D, which also names things backwards.
|
|
// That way when a webcam provides ARGB a user can create a texture of ARGB and not be confused.
|
|
// See http://msdn.microsoft.com/en-us/library/windows/desktop/bb153349%28v=vs.85%29.aspx
|
|
|
|
// raw rgb types
|
|
TTV_WEBCAM_FORMAT_RGB1, // 1 bit per pixel, palettized
|
|
TTV_WEBCAM_FORMAT_RGB4, // 4 bpp, palettized
|
|
TTV_WEBCAM_FORMAT_RGB8, // 8 bpp, palettized
|
|
TTV_WEBCAM_FORMAT_RGB555, // 16 bpp, XRRRRRGG GGGBBBBB
|
|
TTV_WEBCAM_FORMAT_RGB565, // 16 bpp, RRRRRGGG GGGBBBBB
|
|
TTV_WEBCAM_FORMAT_RGB24, // 24 bpp, R8G8B8
|
|
TTV_WEBCAM_FORMAT_XRGB32, // 32 bpp, B8G8R8X8
|
|
TTV_WEBCAM_FORMAT_ARGB1555, // 16 bpp, 1 bit alpha, ARRRRRGG GGGBBBBB
|
|
TTV_WEBCAM_FORMAT_ARGB32, // 32 bpp, 8 bits alpha, B8G8R8A8
|
|
TTV_WEBCAM_FORMAT_ARGB4444, // 16 bpp, 4 bits alpha
|
|
TTV_WEBCAM_FORMAT_B10G10R10A2, // 32 bpp, 10 RGB, 2 alpha, BBBBBBBB BBGGGGGG GGGGRRRR RRRRRRAA
|
|
TTV_WEBCAM_FORMAT_R10G10B10A2, // 32 bpp, 10 RGB, 2 alpha, RRRRRRRR RRGGGGGG GGGGBBBB BBBBBBAA
|
|
|
|
// raw yuv types
|
|
TTV_WEBCAM_FORMAT_AYUV, // AYUV 4:4:4 packed 8 bpp
|
|
TTV_WEBCAM_FORMAT_YUY2, // YUY2 4:2:2 packed 8 bpp
|
|
TTV_WEBCAM_FORMAT_UYVY, // UYVY 4:2:2 packed 8 bpp
|
|
TTV_WEBCAM_FORMAT_IMC1, // IMC1 4:2:0 planar 8 bpp
|
|
TTV_WEBCAM_FORMAT_IMC2, // IMC2 4:2:0 planar 8 bpp
|
|
TTV_WEBCAM_FORMAT_IMC3, // IMC3 4:2:0 planar 8 bpp
|
|
TTV_WEBCAM_FORMAT_IMC4, // IMC4 4:2:0 planar 8 bpp
|
|
TTV_WEBCAM_FORMAT_YV12, // YV12 4:2:0 planar 8 bpp
|
|
TTV_WEBCAM_FORMAT_NV12 // NV12 4:2:0 planar 8 bpp
|
|
|
|
} TTV_WebcamFormat;
|
|
|
|
|
|
/**
|
|
* TTV_WebcamResolution - The resolution of an image.
|
|
*/
|
|
typedef struct
|
|
{
|
|
unsigned int height; //!< The buffer height.
|
|
unsigned int width; //!< The buffer width.
|
|
|
|
} TTV_WebcamResolution;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDeviceCapability - The properties of a mode in which a device can capture. Devices usually support more than one capability.
|
|
*/
|
|
typedef struct
|
|
{
|
|
unsigned int capabilityIndex; //!< The unique index of the capability which is not simply the index in the list.
|
|
TTV_WebcamResolution resolution; //!< The resolution of the capability.
|
|
uint32_t frameRate; //!< The approximate frame rate in frames per second.
|
|
TTV_WebcamFormat format; //!< The buffer format.
|
|
bool isTopToBottom; //!< Whether or not the buffer is packed from top to bottom.
|
|
bool isNative; //!< Whether or not a conversion from the raw buffer needs to be done to provide this format. Native formats are more efficient.
|
|
|
|
} TTV_WebCamDeviceCapability;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDeviceCapabilityList - A list of capabilities for the device.
|
|
*/
|
|
typedef struct
|
|
{
|
|
TTV_WebCamDeviceCapability* list; //!< The list.
|
|
unsigned int count; //!< The number of elements in the list.
|
|
|
|
} TTV_WebCamDeviceCapabilityList;
|
|
|
|
|
|
|
|
#define kMaxDeviceNameLength 64 //!< The max number of characters in the friendly name of a device.
|
|
#define kMaxDeviceIdLength 256 //!< The max number of characters in the unique id a device.
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDevice - Information about one specific device instance.
|
|
*/
|
|
typedef struct
|
|
{
|
|
utf8char uniqueId[kMaxDeviceIdLength+1]; //!< The unique id of the device which should be saved as a user preference once selected.
|
|
utf8char name[kMaxDeviceNameLength+1]; //!< The human readable name of the device.
|
|
unsigned int deviceIndex; //!< The device index for the current run of the game. If the device is unplugged and plugged back in it will change.
|
|
TTV_WebCamDeviceStatus status; //!< The current capture status.
|
|
TTV_WebCamDeviceCapabilityList capabilityList; //!< The list of resolutions and formats the device supports.
|
|
|
|
} TTV_WebCamDevice;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamDeviceList - A list of devices in the system.
|
|
*/
|
|
typedef struct
|
|
{
|
|
TTV_WebCamDevice* list; //!< The list.
|
|
unsigned int count; //!< The number of elements in the list.
|
|
|
|
} TTV_WebCamDeviceList;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamFrame - Information about a captured frame.
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint8_t* imageBuffer; //!< The buffer containing the captured image.
|
|
unsigned int deviceIndex; //!< The index of the device from which the frame originated.
|
|
unsigned int bufferSize; //!< The length of thr buffer.
|
|
TTV_WebCamDeviceCapability capability; //!< The active capability at the time the frame was generated.
|
|
} TTV_WebCamFrame;
|
|
|
|
|
|
/**
|
|
* TTV_WebCamInitializationCallback - The callback to the client indicated the result of the webcam system initializing. Once this is called
|
|
* and indicates success the client will receive device change events which indicate devices being found.
|
|
*
|
|
* @param error The result code of the initialization. TTV_EC_SUCCESS indicates success.
|
|
* @param userdata The custom data provided by the client.
|
|
*/
|
|
typedef void (*TTV_WebCamInitializationCallback) (TTV_ErrorCode error, void* userdata);
|
|
|
|
|
|
/**
|
|
* TTV_WebCamShutdownCallback - The callback to the client indicated the result of the webcam system shutting down. Once this is called the
|
|
* webcam system is no longer available until reinitialized.
|
|
*
|
|
* @param error The result code of the initialization. TTV_EC_SUCCESS indicates success.
|
|
* @param userdata The custom data provided by the client.
|
|
*/
|
|
typedef void (*TTV_WebCamShutdownCallback) (TTV_ErrorCode error, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCamDeviceStatusCallback - Callback called when a device starts or stops capturing. The device data should be copied before the callback returns if the client
|
|
* wants to keep it. If the capability is in a format that the client doesn't know how to handle it should call TTV_WebCam_ConvertToRGBA to convert the buffer
|
|
* to RGBA. The status is contained in the device info.
|
|
*
|
|
* @param device The device info.
|
|
* @param capability The capability which was started or stopped.
|
|
* @param error Any error associated with the status change. TTV_EC_SUCCESS indicates success.
|
|
* @param userdata The custom data provided by the client.
|
|
*/
|
|
typedef void (*TTV_WebCamDeviceStatusCallback) (const TTV_WebCamDevice* device, const TTV_WebCamDeviceCapability* capability, TTV_ErrorCode error, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCamDeviceChangeCallback - Callback called when a device is added or removed from the system. The device data should be copied before the callback returns if the client
|
|
* wants to keep it.
|
|
*
|
|
* @param change The type of change.
|
|
* @param device The device the change occurred on.
|
|
* @param error Any error associated with the status change. TTV_EC_SUCCESS indicates success.
|
|
* @param userdata The custom data provided by the client in the TTV_WebCamCallbacks structure during initialization.
|
|
*/
|
|
typedef void (*TTV_WebCamDeviceChangeCallback) (TTV_WebCamDeviceChange change, const TTV_WebCamDevice* device, TTV_ErrorCode error, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCamCallbacks - The set of callbacks and their data which are called when unsolicited events
|
|
* occur in the webcam system.
|
|
*/
|
|
typedef struct
|
|
{
|
|
TTV_WebCamDeviceChangeCallback deviceChangeCallback; //!< The callback to call when a device is found or lost.
|
|
|
|
void* deviceChangeUserData; //!< The userdata to pass along when deviceChangeCallback is called.
|
|
|
|
} TTV_WebCamCallbacks;
|
|
|
|
|
|
/**
|
|
* TTV_WebCam_Init - Sets up the webcam system for use.
|
|
*
|
|
* @param interruptCallbacks The structure which configures the callbacks and user data passed along when an unsolicited event occurs.
|
|
* @param initCallback The callback which is called when initialization of the systen is complete. When the callback is called the device list will
|
|
* be available and devices ready for use.
|
|
* @param userdata The data to be passed into the initCallback.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_ALREADY_INITIALIZED, TTV_EC_INVALID_ARG.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_Init(const TTV_WebCamCallbacks* interruptCallbacks, TTV_WebCamInitializationCallback initCallback, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCam_Shutdown - Shuts down and cleans up the internals of the webcam system.
|
|
*
|
|
* @param callback The callback which is called when shutdown of the systen is complete.
|
|
* @param userdata The data to be passed into the callback.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_Shutdown(TTV_WebCamShutdownCallback callback, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCam_Start - Begins capturing from the named device. The unique id of the device can be obtained from a call to TTV_WebCam_GetDevices. The callback will
|
|
* be called when the start has been processed. When capturing starts the frameReadyCallback in the configured interruptCallbacks will be
|
|
* called periodically with the latest frame from the device.
|
|
*
|
|
* @param uniqueId The unique identifer of the device which can be found in the TTV_WebCamDevice struct.
|
|
* @param capabilityIndex The index of the parameters to use when capturing frames from the device.
|
|
* @param callback The callback to call when capturing begins.
|
|
* @param userdata The data to pass to the callback.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_Start(int deviceIndex, int capabilityIndex, TTV_WebCamDeviceStatusCallback callback, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCam_Stop - Stops the capturing of frames from the device. The callback will be called when the start has been processed.
|
|
*
|
|
* @param uniqueId The unique identifer of the device which can be found in the TTV_WebCamDevice struct.
|
|
* @param callback The callback to call when capturing begins.
|
|
* @param userdata The data to pass to the callback.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_Stop(int deviceIndex, TTV_WebCamDeviceStatusCallback callback, void* userdata);
|
|
|
|
/**
|
|
* TTV_WebCam_FlushEvents - Causes callbacks from the webcam system to be flushed to the client. This should be called very frequently (once per game frame ideally).
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_FlushEvents();
|
|
|
|
/**
|
|
* TTV_WebCam_IsFrameAvailable - Determines if there is a new frame available for the given device.
|
|
*
|
|
* @param deviceIndex The index of the device to check.
|
|
* @param available The result.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_IsFrameAvailable(int deviceIndex, bool* available);
|
|
|
|
/**
|
|
* TTV_WebCam_GetFrame - Fills the given buffer with the contents of the next available frame.
|
|
*
|
|
* NOTE: On iOS the image is not automatically rotated to compensate for the orientation of the device.
|
|
* The provided image is captured from the cameras default orientation of UIDeviceOrientationPortrait.
|
|
* Use the following code snippet to determine the device's current orientation and make changes to the way you display it.
|
|
*
|
|
* UIInterfaceOrientation orient = [[UIApplication sharedApplication] statusBarOrientation];
|
|
*
|
|
* @param deviceIndex The index of the device to get the image from.
|
|
* @param buffer The buffer to fill.
|
|
* @param pitch The number of bytes in each row of the buffer.
|
|
*
|
|
* @return TTV_EC_SUCCESS, TTV_EC_NOT_INITIALIZED.
|
|
*/
|
|
TTV_ErrorCode TTV_WebCam_GetFrame(int deviceIndex, void* buffer, unsigned int pitch);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* TTVSDK_TWITCH_WEBCAM_H */
|