From cd49cce4c5df6666ef1af4a1647b7bbe8176cc7f Mon Sep 17 00:00:00 2001 From: Cameron Gutman Date: Wed, 13 May 2015 22:00:10 -0500 Subject: [PATCH] Add comments to Limelight.h to provide some documentation --- limelight-common/Limelight.h | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/limelight-common/Limelight.h b/limelight-common/Limelight.h index d129ff5..804af5e 100644 --- a/limelight-common/Limelight.h +++ b/limelight-common/Limelight.h @@ -1,3 +1,7 @@ +// +// This header exposes the public streaming API for client usage +// + #pragma once #ifdef __cplusplus @@ -7,31 +11,61 @@ extern "C" { #define IP_ADDRESS unsigned int typedef struct _STREAM_CONFIGURATION { + // Dimensions in pixels of the desired video stream int width; int height; + + // FPS of the desired video stream int fps; + + // Bitrate of the desired video stream (audio adds another ~1 Mbps) int bitrate; + + // Max video packet size in bytes (use 1024 if unsure) int packetSize; + + // AES encryption data for the remote input stream. This must be + // the same as what was passed as rikey and rikeyid + // in /launch and /resume requests. char remoteInputAesKey[16]; char remoteInputAesIv[16]; } STREAM_CONFIGURATION, *PSTREAM_CONFIGURATION; typedef struct _LENTRY { + // Pointer to the next entry or NULL if this is the last entry struct _LENTRY *next; + + // Pointer to data (never NULL) char* data; + + // Size of data in bytes (never <= 0) int length; } LENTRY, *PLENTRY; +// A decode unit describes a buffer chain of H264 data from multiple packets typedef struct _DECODE_UNIT { + // Length of the entire buffer chain in bytes int fullLength; + + // Head of the buffer chain (never NULL) PLENTRY bufferList; } DECODE_UNIT, *PDECODE_UNIT; +// This callback is invoked to provide details about the video stream and allow configuration of the decoder typedef void(*DecoderRendererSetup)(int width, int height, int redrawRate, void* context, int drFlags); + +// This callback is invoked right before video data starts being submitted to the decoder typedef void(*DecoderRendererStart)(void); + +// After this callback is invoked, no more video data will be submitted to the decoder typedef void(*DecoderRendererStop)(void); + +// This callback performs the final teardown of the video decoder typedef void(*DecoderRendererRelease)(void); +// This callback provides Annex B formatted H264 elementary stream data to the +// decoder. If the decoder is unable to process the submitted data for some reason, +// it must return DR_NEED_IDR to generate a keyframe. #define DR_OK 0 #define DR_NEED_IDR -1 typedef int(*DecoderRendererSubmitDecodeUnit)(PDECODE_UNIT decodeUnit); @@ -44,10 +78,19 @@ typedef struct _DECODER_RENDERER_CALLBACKS { DecoderRendererSubmitDecodeUnit submitDecodeUnit; } DECODER_RENDERER_CALLBACKS, *PDECODER_RENDERER_CALLBACKS; +// This callback initializes the audio renderer typedef void(*AudioRendererInit)(void); + +// This callback occurs before audio data is submitted typedef void(*AudioRendererStart)(void); + +// After this callback is invoked, no more audio data will be submitted typedef void(*AudioRendererStop)(void); + +// This callback performs the final teardown of the audio decoder typedef void(*AudioRendererRelease)(void); + +// This callback provides Opus audio data to be decoded and played. sampleLength is in bytes. typedef void(*AudioRendererDecodeAndPlaySample)(char* sampleData, int sampleLength); typedef struct _AUDIO_RENDERER_CALLBACKS { @@ -73,14 +116,27 @@ typedef struct _AUDIO_RENDERER_CALLBACKS { #define STAGE_INPUT_STREAM_START 10 #define STAGE_MAX 11 +// This callback is invoked to indicate that a stage of initialization is about to begin typedef void(*ConnListenerStageStarting)(int stage); + +// This callback is invoked to indicate that a stage of initialization has completed typedef void(*ConnListenerStageComplete)(int stage); + +// This callback is invoked to indicate that a stage of initialization has failed typedef void(*ConnListenerStageFailed)(int stage, long errorCode); +// This callback is invoked after initialization has finished typedef void(*ConnListenerConnectionStarted)(void); + +// This callback is invoked when a connection failure occurs. It will not +// occur as a result of a call to LiStopConnection() typedef void(*ConnListenerConnectionTerminated)(long errorCode); +// This callback is invoked to display a dialog-type message to the user typedef void(*ConnListenerDisplayMessage)(char* message); + +// This callback is invoked to display a transient message for the user +// while streaming typedef void(*ConnListenerDisplayTransientMessage)(char* message); typedef struct _CONNECTION_LISTENER_CALLBACKS { @@ -93,7 +149,12 @@ typedef struct _CONNECTION_LISTENER_CALLBACKS { ConnListenerDisplayTransientMessage displayTransientMessage; } CONNECTION_LISTENER_CALLBACKS, *PCONNECTION_LISTENER_CALLBACKS; +// This is a Windows-only callback used to indicate that the client +// should call LiCompleteThreadStart() from a new thread as soon as possible. typedef void(*PlatformThreadStart)(void); + +// This is a Windows-only callback used to display a debug message for +// developer use. typedef void(*PlatformDebugPrint)(char* string); typedef struct _PLATFORM_CALLBACKS { @@ -101,17 +162,33 @@ typedef struct _PLATFORM_CALLBACKS { PlatformDebugPrint debugPrint; } PLATFORM_CALLBACKS, *PPLATFORM_CALLBACKS; +// This function begins streaming. +// +// Callbacks are all optional. Pass NULL for individual callbacks within each struct or pass NULL for the entire struct +// to use the defaults for all callbacks. +// +// _serverMajorVersion is the major version number of the 'appversion' tag in the /serverinfo request +// int LiStartConnection(IP_ADDRESS host, PSTREAM_CONFIGURATION streamConfig, PCONNECTION_LISTENER_CALLBACKS clCallbacks, PDECODER_RENDERER_CALLBACKS drCallbacks, PAUDIO_RENDERER_CALLBACKS arCallbacks, PPLATFORM_CALLBACKS plCallbacks, void* renderContext, int drFlags, int _serverMajorVersion); + +// This function stops streaming. void LiStopConnection(void); + +// Use to get a user-visible string to display initialization progress +// from the integer passed to the ConnListenerStageXXX callbacks const char* LiGetStageName(int stage); +#ifdef _WIN32 /* Call in the context of a new thread */ void LiCompleteThreadStart(void); +#endif +// This function queues a mouse move event to be sent to the remote server. int LiSendMouseMoveEvent(short deltaX, short deltaY); +// This function queues a mouse button event to be sent to the remote server. #define BUTTON_ACTION_PRESS 0x07 #define BUTTON_ACTION_RELEASE 0x08 #define BUTTON_LEFT 0x01 @@ -119,6 +196,7 @@ int LiSendMouseMoveEvent(short deltaX, short deltaY); #define BUTTON_RIGHT 0x03 int LiSendMouseButtonEvent(char action, int button); +// This function queues a keyboard event to be sent to the remote server. #define KEY_ACTION_DOWN 0x03 #define KEY_ACTION_UP 0x04 #define MODIFIER_SHIFT 0x01 @@ -126,6 +204,7 @@ int LiSendMouseButtonEvent(char action, int button); #define MODIFIER_ALT 0x04 int LiSendKeyboardEvent(short keyCode, char keyAction, char modifiers); +// Button flags #define A_FLAG 0x1000 #define B_FLAG 0x2000 #define X_FLAG 0x4000 @@ -141,11 +220,20 @@ int LiSendKeyboardEvent(short keyCode, char keyAction, char modifiers); #define LS_CLK_FLAG 0x0040 #define RS_CLK_FLAG 0x0080 #define SPECIAL_FLAG 0x0400 + +// This function queues a controller event to be sent to the remote server. It will +// be seen by the computer as the first controller. int LiSendControllerEvent(short buttonFlags, char leftTrigger, char rightTrigger, short leftStickX, short leftStickY, short rightStickX, short rightStickY); + +// This function queues a controller event to be sent to the remote server. The controllerNumber +// parameter is a zero-based index of which controller this event corresponds to. The largest legal +// controller number is 3 (for a total of 4 controllers, the Xinput maximum). On generation 3 servers (GFE 2.1.x), +// these will be sent as controller 0 regardless of the controllerNumber parameter. int LiSendMultiControllerEvent(short controllerNumber, short buttonFlags, char leftTrigger, char rightTrigger, short leftStickX, short leftStickY, short rightStickX, short rightStickY); +// This function queues a vertical scroll event to the remote server. int LiSendScrollEvent(char scrollClicks); #ifdef __cplusplus