Some rework and....

More documentation

Doc/APIRef.tex

@@ -0,0 +1,184 @@
+\section{API Reference}
+\subsection{Preprocessor constants}
+
+\newcolumntype{b}{>{\hsize=.66\hsize}X}
+\newcolumntype{s}{>{\hsize=.33\hsize}X}
+
+\newcommand{\tblx}[2]{
+	\noindent
+	\begin{tabularx}{\textwidth} { | >{\raggedright\arraybackslash}X |  }
+		\hline
+		\texttt{#1} \\
+		\hline
+		#2 \\
+		\hline
+	\end{tabularx}
+	\mbox{}\\
+
+}
+
+\newcommand{\tbly}[3]{
+	\noindent
+	\begin{tabularx}{\textwidth}{|s|b|}
+		\hline
+			#1 & \texttt{#2} \\
+		\hline
+			\multicolumn{2}{|l|}{\begin{minipage}{0.9\linewidth} #3 \end{minipage}} \\
+		\hline
+	\end{tabularx}
+	\mbox{}
+}
+
+\paragraph{Error codes}
+\mbox{}\\
+
+% DS5W_OK
+\tblx{DS5W\_OK}{The operation completed without an error}
+
+% DS5W_E_UNKNOWN
+\tblx{DS5W\_E\_UNKNOWN}{An unknown error occurred}
+
+% DS5W_E_INSUFFICIENT_BUFFER
+\tblx{DS5W\_E\_INSUFFICIENT\_BUFFER}{The user supplied buffer is to small }
+
+% DS5W_E_EXTERNAL_WINAPI
+\tblx{DS5W\_E\_EXTERNAL\_WINAPI}{An unsuspected Windows sided error occurred}
+
+% DS5W_E_INVALID_ARGS
+\tblx{DS5W\_E\_INVALID\_ARGS}{The user supplied arguments are invalid}
+
+% DS5W_E_CURRENTLY_NOT_SUPPORTED
+\tblx{DS5W\_E\_CURRENTLY\_NOT\_SUPPORTED}{This feature is currently not supported}
+
+% DS5W_E_DEVICE_REMOVED
+\tblx{DS5W\_E\_DEVICE\_REMOVED}{The device was removed unexpectedly}
+
+% DS5W_E_BT_COM
+\tblx{DS5W\_E\_BT\_COM}{Bluetooth communication error}
+
+
+
+\paragraph{Error helpers}
+\mbox{}\\
+
+% DS5W_SUCCESS(expr)
+\tblx{DS5W\_SUCCESS(expr)}{Check if the user supplied expression is an error success code}
+
+% DS5W_FAILED(expr)
+\tblx{DS5W\_FAILED(expr)}{Check if the user supplied expression is an error code}
+
+
+
+\paragraph{I/O State helpers}
+\mbox{}\\
+
+% DS5W_ISTATE_BTX_SQUARE / CROSS / CIRCLE / TRIANGLE
+\tblx{DS5W\_ISTATE\_BTX\_SQUARE}{PlayStation Square button}
+\tblx{DS5W\_ISTATE\_BTX\_CROSS}{PlayStation Cross button}
+\tblx{DS5W\_ISTATE\_BTX\_CIRCLE}{PlayStation Circle button}
+\tblx{DS5W\_ISTATE\_BTX\_TRIANGLE}{PlayStation Triangle button}
+
+% DPAD
+\tblx{DS5W\_ISTATE\_DPAD\_LEFT}{D-Pad left}
+\tblx{DS5W\_ISTATE\_DPAD\_DOWN}{D-Pad down}
+\tblx{DS5W\_ISTATE\_DPAD\_RIGHT}{D-Pad right}
+\tblx{DS5W\_ISTATE\_DPAD\_UP}{D-Pad up}
+
+% Button A
+\tblx{DS5W\_ISTATE\_BTN\_A\_LEFT\_BUMPER}{Left bumper button}
+\tblx{DS5W\_ISTATE\_BTN\_A\_RIGHT\_BUMPER}{Right bumper button}
+\tblx{DS5W\_ISTATE\_BTN\_A\_LEFT\_TRIGGER}{Left trigger binary input}
+\tblx{DS5W\_ISTATE\_BTN\_A\_RIGHT\_TRIGGER}{Right trigger binary input}
+\tblx{DS5W\_ISTATE\_BTN\_A\_SELECT}{Select / Share button}
+\tblx{DS5W\_ISTATE\_BTN\_A\_MENU}{Menu Button}
+\tblx{DS5W\_ISTATE\_BTN\_A\_LEFT\_STICK}{Left stick push button}
+\tblx{DS5W\_ISTATE\_BTN\_A\_RIGHT\_STICK}{Right stick push button}
+
+% Button B
+\tblx{DS5W\_ISTATE\_BTN\_B\_PLAYSTATION\_LOGO}{PlayStation logo button}
+\tblx{DS5W\_ISTATE\_BTN\_B\_PAD\_BUTTON}{The touch-pads integrated button}
+\tblx{DS5W\_ISTATE\_BTN\_B\_MIC\_BUTTON}{Microphone mute button}
+
+% Outstate
+\tblx{DS5W\_OSTATE\_PLAYER\_LED\_LEFT}{Left player indicator LED bit-mask}
+\tblx{DS5W\_OSTATE\_PLAYER\_LED\_MIDDLE\_LEFT}{Left middle player indicator LED bit-mask}
+\tblx{DS5W\_OSTATE\_PLAYER\_LED\_MIDDLE}{Middle player indicator LED bit-mask}
+\tblx{DS5W\_OSTATE\_PLAYER\_LED\_MIDDLE\_RIGHT}{Right middle player indicator LED bit-mask}
+\tblx{DS5W\_OSTATE\_PLAYER\_LED\_RIGHT}{Right player indicator LED bit-mask}
+
+\subsection{Types}
+\paragraph{DeviceEnumInfo} This struct contains all internal data required for the controller enumeration. You should not read or write any of the internal data directly. The struct can be freely user allocated with random data. It will be initialized by the corresponding function call, don't use it before it got initialized by the corresponding function.
+
+\paragraph{DeviceContext} This struct contains all internal data for reading and writing to the controller. You should not read or write any of the internal data directly. The struct can be freely user allocated with random data. It will be initialized by the corresponding function call, don't use it before it got initialized by the corresponding function. It is very important to free this data with the corresponding function before the application exits or memory is reused. 
+
+\paragraph{AnalogStick} This struct represent the XY position of one analog stick. Make sure to implement dead zones by yourself! \\
+
+\tbly{int8\_t}{x}{X Position (left to right) of the analog stick.} \\
+
+\tbly{int8\_t}{y}{Y Position (top to bottom) of the analog stick.} \\
+
+\paragraph{Vector3, Vec3} Represents a three component 16-Bit vector \\
+
+\tbly{int16\_t}{x}{X Component} \\
+
+\tbly{int16\_t}{y}{Y Component} \\
+
+\tbly{int16\_t}{z}{Z Component} \\
+
+\paragraph{Color} RGB 8-Bit color components. The library also provides several conversion functions to turn several color formats into 8-Bit RGB values.\\
+
+\tbly{uint8\_t}{r}{R - Red color channel}\\
+
+\tbly{uint8\_t}{g}{G - Green color channel}\\
+
+\tbly{uint8\_t}{b}{B - Blue color channel}\\
+
+\paragraph{Touch} This struct contains information about a single fingers touch position. \\
+
+\tbly{int8\_t}{x}{X Position of the finger (left to right).} \\
+
+\tbly{int8\_t}{y}{Y Position of the finger (top to bottom).} \\
+
+\paragraph{MicLed} Enum class representation the state of the microphone LED. \\
+
+\tblx{OFF}{Microphone LED is completely off}
+\tblx{ON}{Microphone LED is on}
+\tblx{PULSE}{Microphone LED is pulsing}
+
+
+\paragraph{TriggerEffectType} Enum class: feedback / effect type of the adaptive trigger.\\
+
+\tblx{NoResitance}{Adaptive trigger is disabled. Will provide no resistance.}
+\tblx{ContinuousResitance}{Adaptive trigger will provide a continuous resistance from a specific starting point.}
+\tblx{SectionResitance}{Adaptive trigger will provide a force fixed resistance on a defined section.}
+\tblx{EffectEx}{Adaptive trigger will execute an extended effect.}
+\tblx{Calibrate}{Adaptive trigger will enter an fixed function calibration program. Still experimental use only!}
+
+\paragraph{TriggerEffect}
+TODO
+
+\label{APIRef_Types_ledbr}
+\paragraph{LedBrightness} Enum class representation the brightness of the player indication LEDs.\\
+
+\tblx{LOW}{Low brightness player indication LEDs}
+\tblx{MEDIUM}{Medium brightness player indication LEDs}
+\tblx{HIGH}{High brightness player indication LEDs}
+
+\paragraph{PlayerLeds} Struct defining the player LDEs state.\\
+
+\tbly{Bitmask / uint8\_t}{bitmask}{Bitmask of the enabled player indication LEDs. Or together all enabled LEDs by using the \texttt{DS5W\_OSTATE\_PLAYER\_LED\_XXXXX} macros.}\\
+
+\tbly{bool}{playerLedFade}{Indicates weather the player LEDs should fade in when enabled.}\\
+
+\tbly{\hyperref[APIRef_Types_ledbr]{LedBrightness}}{brightness}{Brightness of the player LEDs}\\
+
+\paragraph{DS5InputState}
+TODO
+
+\paragraph{DS5OutputState}
+TODO
+
+\subsection{Functions}
+FUNCTIONS
+
+\newpage

Doc/DualSenseWindows_Doc.tex

@@ -9,7 +9,37 @@
 \usepackage{graphicx}
 \usepackage{float}
 \usepackage{dirtree}
+\usepackage{xcolor}
+\usepackage{longtable}
+\usepackage{tabularx}
 
+
+\definecolor{clr-background}{RGB}{255,255,255}
+\definecolor{clr-text}{RGB}{0,0,0}
+\definecolor{clr-string}{RGB}{163,21,21}
+\definecolor{clr-namespace}{RGB}{0,0,0}
+\definecolor{clr-keyword}{RGB}{0,0,255}
+\definecolor{clr-type}{RGB}{43,145,175}
+\definecolor{clr-variable}{RGB}{0,0,0}
+\definecolor{clr-constant}{RGB}{111,0,138}
+\definecolor{clr-comment}{RGB}{0,128,0}
+
+\lstdefinestyle{VSC}{
+	backgroundcolor=\color{clr-background},
+	basicstyle=\color{clr-text},
+	stringstyle=\color{clr-string},
+	identifierstyle=\color{clr-variable},
+	commentstyle=\color{clr-comment},
+	keywordstyle=\color{clr-type},
+	keywordstyle={[2]\color{clr-constant}},
+	tabsize=4,
+	numbers=left,
+	numbersep=5pt
+}
+
+\lstloadlanguages{[Visual]C++}
+\lstset{style=VSC}
+
 \PassOptionsToPackage{hyphens}{url}\usepackage{hyperref}
 
 
@@ -34,5 +64,6 @@
 \include{Features}
 \include{Installation}
 \include{QuickStart}
+\include{APIRef}
 
 \end{document}

Doc/DualSenseWindows_Doc.wsp

@@ -7,4 +7,5 @@
 .\Features.tex
 .\Installation.tex
 .\QuickStart.tex
+.\APIRef.tex
 

Doc/QuickStart.tex

@@ -1,4 +1,128 @@
-\section{Quick start}
-Quick start
+\section{Quick start guide}
+In this section we will introduce you to the API step by step. You will need a DualSense controller connected via USB or Bluetooth.
+
+\subsection{Starting point}
+First start by creating the \texttt{main.cpp} file (assuming you already finished the installation steps from the former section). Include \texttt{ds5w.h} and create your main with an infinity loop inside.
+\begin{lstlisting}[language=C++,label=code0,caption={DS5W Main}]{DS5W Main}
+#include <Windows.h>
+#include <ds5w.h>
+#include <iostream>
+
+int main(int argc, char** argv){
+
+   while(true){
+
+   }
+
+   return 0;
+}
+\end{lstlisting}
+The library doesn't feature any global state or memory allocation, so it is not required to initialize the library. You can directly continue with the enumeration of all connected DualSense controllers.
+
+\subsection{Enumerate controllers}
+To enumerate DualSense controllers you need to supply an array of \texttt{DS5W::DeviceEnumInfo} or an array of pointers to \texttt{DS5W::DeviceEnumInfo} objects. The \texttt{DS5W::DeviceEnumInfo} object doesn't need any initializations, it will be initialized by the function you will call next. The function \texttt{DS5W::enumDevices(...)} will fill the supplied array with as many controllers as are available or the array can hold. Please consider looking at the API documentation to find the best way to robustly integrate that function call into your project.\\
+
+\begin{minipage}{\textwidth}
+\begin{lstlisting}[language=C++,label=code1,caption={Enumerate controllers}]{Enumerate controllers}
+// ...
+int main(int argc, char** argv){
+	// Array of controller infos
+	DS5W::DeviceEnumInfo infos[16];
+
+	// Number of controllers found
+	unsigned int controllersCount = 0;
+
+	// Call enumerate function and switch on return value
+	switch(DS5W::enumDevices(infos, 16, &controllersCount)){
+		// The buffer was not big enough. Ignore for now
+		case DS5W_E_INSUFFICIENT_BUFFER:
+			break;
+
+		// Any other error will terminate the application
+		default:
+			// Insert your error handling
+			return -1;
+	}
+// ...
+\end{lstlisting}
+\end{minipage}
+
+\subsection{Selecting a controller}
+In this example we will select the first controller found. To enable a controller it is required to create a \texttt{DS5W::DeviceContext} context for it. The context will be initialized by the function call \texttt{DS5W::initDeviceContext(...)}. It is required to shutdown the controller after usage by calling \\
+\texttt{DS5W::freeDeviceContext(...)}.\\
+
+\begin{minipage}{\textwidth}
+\begin{lstlisting}[language=C++,label=code2,caption={Controller init / shutdown}]{Controller init / shutdown}
+	// ...
+	// Check number of controllers
+	if(!controllersCount){
+		return -1;
+	}
+
+	// Context for controller
+	DS5W::DeviceContext con;
+
+	// Init controller and close application is failed
+	if(DS5W_FAILED(DS5W::initDeviceContext(&infos[0], &con))){
+		return -1;
+	}
+
+	// Main loop
+	while(true){
+		// ...
+	}
+
+	// Shutdown context
+	DS5W::freeDeviceContext(&con);
+}
+\end{lstlisting}
+\end{minipage}
+
+\subsection{Reading controller input}
+The next step is read the input from the controller. We will check here if the PlayStation logo buttons is presses. When this is the case the application will exit the infinity loop and thus will shutdown. For reading the input data the \texttt{DS5W::DS5InputState} struct is required, it will be filled by the \texttt{DS5W::getDeviceInputState(...)} method call. \\
+
+\begin{minipage}{\textwidth}
+\begin{lstlisting}[language=C++,label=code3,caption={Reading the input}]{Reading the input}
+while(true){
+	// Input state
+	DS5W::DS5InputState inState;
+
+	// Retrieve data
+	if (DS5W_SUCCESS(DS5W::getDeviceInputState(&con, &inState))){
+		// Check for the Logo button
+		if(inState.buttonsB & DS5W_ISTATE_BTN_B_PLAYSTATION_LOGO){
+			// Break from while loop
+			break;
+		}
+
+		// ...
+	}
+}
+\end{lstlisting}
+\end{minipage}
+
+\subsection{Writing controller output}
+Writing to the controller is as simple as reading from it. It requires the struct \texttt{DS5W::DS5OutputState}, to prevent random data being sent please make sure to ZeroMemory the struct or setting every value. After setting all values you want to update, the data is written by calling the\\
+\texttt{DS5W::setDeviceOutputState(...)} function. In this example we will directly map the triggers input to the rumble motors output.
+
+\begin{minipage}{\textwidth}
+\begin{lstlisting}[language=C++,label=code4,caption={Writing the output}]{Writing the output}
+// ...
+
+// Create struct and zero it
+DS5W::DS5OutputState outState;
+ZeroMemory(&outState, sizeof(DS5W::DS5OutputState));
+
+// Set output data
+outState.leftRumble = inState.leftTrigger;
+outState.rightRumble = inState.rightTrigger;
+
+// Send output to the controller
+DS5W::setDeviceOutputState(&con, &outState);
+
+// ...
+\end{lstlisting}
+\end{minipage}
+Putting all the above code snippets together will give you a working example application.
 
 \newpage

VS19_Solution/DS5W_Test/src/wWinMain.cpp

@@ -52,7 +52,7 @@ INT WINAPI wWinMain(HINSTANCE _In_ hInstance, HINSTANCE _In_opt_ hPrevInstance,
 	// Enum all controllers presentf
 	DS5W::DeviceEnumInfo infos[16];
 	unsigned int controllersCount = 0;
-	DS5W_ReturnValue rv = DS5W::enumDevices(infos, 16, true, &controllersCount);
+	DS5W_ReturnValue rv = DS5W::enumDevices(infos, 16, &controllersCount);
 
 	// check size
 	if (controllersCount == 0) {
@@ -129,7 +129,7 @@ INT WINAPI wWinMain(HINSTANCE _In_ hInstance, HINSTANCE _In_opt_ hPrevInstance,
 					(inState.buttonsAndDpad & DS5W_ISTATE_DPAD_DOWN ? L"D " : L"  ") << (inState.buttonsAndDpad & DS5W_ISTATE_DPAD_RIGHT ? L"R " : L"  ");
 				builder << L"\tButtons: " << (inState.buttonsAndDpad & DS5W_ISTATE_BTX_SQUARE ? L"S " : L"  ") << (inState.buttonsAndDpad & DS5W_ISTATE_BTX_CROSS ? L"X " : L"  ") <<
 					(inState.buttonsAndDpad & DS5W_ISTATE_BTX_CIRCLE ? L"O " : L"  ") << (inState.buttonsAndDpad & DS5W_ISTATE_BTX_TRIANGLE ? L"T " : L"  ") << std::endl;
-				builder << (inState.buttonsA & DS5W_ISTATE_BTN_A_MENUE ? L"MENU" : L"") << (inState.buttonsA & DS5W_ISTATE_BTN_A_SELECT ? L"\tSELECT" : L"") << std::endl;;
+				builder << (inState.buttonsA & DS5W_ISTATE_BTN_A_MENU ? L"MENU" : L"") << (inState.buttonsA & DS5W_ISTATE_BTN_A_SELECT ? L"\tSELECT" : L"") << std::endl;;
 
 				builder << L"Trigger Feedback:\tLeft: " << (int)inState.leftTriggerFeedback << L"\tRight: " << (int)inState.rightTriggerFeedback << std::endl << std::endl;