diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index d36ba0906..0ea47c1e2 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -932,7 +932,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller); /** - * Return the sfSymbolsName for a given button on a game controller on Apple platforms. + * Return the sfSymbolsName for a given button on a game controller on Apple + * platforms. * * \param gamecontroller the controller to query * \param button a button on the game controller @@ -945,7 +946,8 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForButton(SDL_GameController *gamecontroller, SDL_GameControllerButton button); /** - * Return the sfSymbolsName for a given axis on a game controller on Apple platforms. + * Return the sfSymbolsName for a given axis on a game controller on Apple + * platforms. * * \param gamecontroller the controller to query * \param axis an axis on the game controller diff --git a/include/SDL_hidapi.h b/include/SDL_hidapi.h index a440f9883..e72e464d7 100644 --- a/include/SDL_hidapi.h +++ b/include/SDL_hidapi.h @@ -116,12 +116,11 @@ typedef struct SDL_hid_device_info /** * Initialize the HIDAPI library. * - * This function initializes the HIDAPI library. Calling it is not - * strictly necessary, as it will be called automatically by - * SDL_hid_enumerate() and any of the SDL_hid_open_*() functions - * if it is needed. This function should be called at the beginning - * of execution however, if there is a chance of HIDAPI handles - * being opened by different threads simultaneously. + * This function initializes the HIDAPI library. Calling it is not strictly + * necessary, as it will be called automatically by SDL_hid_enumerate() and + * any of the SDL_hid_open_*() functions if it is needed. This function should + * be called at the beginning of execution however, if there is a chance of + * HIDAPI handles being opened by different threads simultaneously. * * \returns 0 on success and -1 on error. * @@ -132,9 +131,8 @@ extern DECLSPEC int SDLCALL SDL_hid_init(void); /** * Finalize the HIDAPI library. * - * This function frees all of the static data associated with - * HIDAPI. It should be called at the end of execution to avoid - * memory leaks. + * This function frees all of the static data associated with HIDAPI. It + * should be called at the end of execution to avoid memory leaks. * * \returns 0 on success and -1 on error. * @@ -145,20 +143,18 @@ extern DECLSPEC int SDLCALL SDL_hid_exit(void); /** * Enumerate the HID Devices. * - * This function returns a linked list of all the HID devices - * attached to the system which match vendor_id and product_id. - * If `vendor_id` is set to 0 then any vendor matches. - * If `product_id` is set to 0 then any product matches. - * If `vendor_id` and `product_id` are both set to 0, then - * all HID devices will be returned. + * This function returns a linked list of all the HID devices attached to the + * system which match vendor_id and product_id. If `vendor_id` is set to 0 + * then any vendor matches. If `product_id` is set to 0 then any product + * matches. If `vendor_id` and `product_id` are both set to 0, then all HID + * devices will be returned. * * \param vendor_id The Vendor ID (VID) of the types of device to open. * \param product_id The Product ID (PID) of the types of device to open. - * - * \returns a pointer to a linked list of type SDL_hid_device_info, - * containing information about the HID devices attached to the - * system, or NULL in the case of failure. Free this linked list - * by calling SDL_hid_free_enumeration(). + * \returns a pointer to a linked list of type SDL_hid_device_info, containing + * information about the HID devices attached to the system, or NULL + * in the case of failure. Free this linked list by calling + * SDL_hid_free_enumeration(). * * \since This function is available since SDL 2.0.18. */ @@ -170,7 +166,7 @@ extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short v * This function frees a linked list created by SDL_hid_enumerate(). * * \param devs Pointer to a list of struct_device returned from - * SDL_hid_enumerate(). + * SDL_hid_enumerate(). */ extern DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -210,25 +206,23 @@ SDL_hid_device * SDL_hid_open_path(const char *path, int bExclusive /* = false * /** * Write an Output report to a HID device. * - * The first byte of `data` must contain the Report ID. For - * devices which only support a single report, this must be set - * to 0x0. The remaining bytes contain the report data. Since - * the Report ID is mandatory, calls to SDL_hid_write() will always - * contain one more byte than the report contains. For example, - * if a hid report is 16 bytes long, 17 bytes must be passed to - * SDL_hid_write(), the Report ID (or 0x0, for devices with a - * single report), followed by the report data (16 bytes). In - * this example, the length passed in would be 17. + * The first byte of `data` must contain the Report ID. For devices which only + * support a single report, this must be set to 0x0. The remaining bytes + * contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_write() will always contain one more byte than the report contains. + * For example, if a hid report is 16 bytes long, 17 bytes must be passed to + * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), + * followed by the report data (16 bytes). In this example, the length passed + * in would be 17. * - * SDL_hid_write() will send the data on the first OUT endpoint, if - * one exists. If it does not, it will send the data through - * the Control Endpoint (Endpoint 0). + * SDL_hid_write() will send the data on the first OUT endpoint, if one + * exists. If it does not, it will send the data through the Control Endpoint + * (Endpoint 0). * * \param dev A device handle returned from SDL_hid_open(). - * \param data The data to send, including the report number as - * the first byte. + * \param data The data to send, including the report number as the first + * byte. * \param length The length in bytes of the data to send. - * * \returns the actual number of bytes written and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -238,19 +232,19 @@ extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned ch /** * Read an Input report from a HID device with timeout. * - * Input reports are returned - * to the host through the INTERRUPT IN endpoint. The first byte will - * contain the Report number if the device uses numbered reports. + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. * * \param dev A device handle returned from SDL_hid_open(). * \param data A buffer to put the read data into. - * \param length The number of bytes to read. For devices with - * multiple reports, make sure to read an extra byte for - * the report number. + * \param length The number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. * \param milliseconds timeout in milliseconds or -1 for blocking wait. - * - * \returns the actual number of bytes read and -1 on error. - If no packet was available to be read within the timeout period, this function returns 0. + * \returns the actual number of bytes read and -1 on error. If no packet was + * available to be read within the timeout period, this function + * returns 0. * * \since This function is available since SDL 2.0.18. */ @@ -259,18 +253,18 @@ extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned c /** * Read an Input report from a HID device. * - * Input reports are returned - * to the host through the INTERRUPT IN endpoint. The first byte will - * contain the Report number if the device uses numbered reports. + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. * * \param dev A device handle returned from SDL_hid_open(). * \param data A buffer to put the read data into. - * \param length The number of bytes to read. For devices with - * multiple reports, make sure to read an extra byte for - * the report number. - * - * \returns the actual number of bytes read and -1 on error. - * If no packet was available to be read and the handle is in non-blocking mode, this function returns 0. + * \param length The number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. + * \returns the actual number of bytes read and -1 on error. If no packet was + * available to be read and the handle is in non-blocking mode, this + * function returns 0. * * \since This function is available since SDL 2.0.18. */ @@ -279,18 +273,15 @@ extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *dat /** * Set the device handle to be non-blocking. * - * In non-blocking mode calls to SDL_hid_read() will return - * immediately with a value of 0 if there is no data to be - * read. In blocking mode, SDL_hid_read() will wait (block) until - * there is data to read before returning. + * In non-blocking mode calls to SDL_hid_read() will return immediately with a + * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read() + * will wait (block) until there is data to read before returning. * * Nonblocking can be turned on and off at any time. * * \param dev A device handle returned from SDL_hid_open(). - * \param nonblock enable or not the nonblocking reads - * - 1 to enable nonblocking - * - 0 to disable nonblocking. - * + * \param nonblock enable or not the nonblocking reads - 1 to enable + * nonblocking - 0 to disable nonblocking. * \returns 0 on success and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -300,25 +291,21 @@ extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int non /** * Send a Feature report to the device. * - * Feature reports are sent over the Control endpoint as a - * Set_Report transfer. The first byte of `data` must - * contain the Report ID. For devices which only support a - * single report, this must be set to 0x0. The remaining bytes - * contain the report data. Since the Report ID is mandatory, - * calls to SDL_hid_send_feature_report() will always contain one - * more byte than the report contains. For example, if a hid - * report is 16 bytes long, 17 bytes must be passed to - * SDL_hid_send_feature_report(): the Report ID (or 0x0, for - * devices which do not use numbered reports), followed by the - * report data (16 bytes). In this example, the length passed - * in would be 17. + * Feature reports are sent over the Control endpoint as a Set_Report + * transfer. The first byte of `data` must contain the Report ID. For devices + * which only support a single report, this must be set to 0x0. The remaining + * bytes contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_send_feature_report() will always contain one more byte than the + * report contains. For example, if a hid report is 16 bytes long, 17 bytes + * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for + * devices which do not use numbered reports), followed by the report data (16 + * bytes). In this example, the length passed in would be 17. * * \param dev A device handle returned from SDL_hid_open(). - * \param data The data to send, including the report number as - * the first byte. - * \param length The length in bytes of the data to send, including - * the report number. - * + * \param data The data to send, including the report number as the first + * byte. + * \param length The length in bytes of the data to send, including the report + * number. * \returns the actual number of bytes written and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -328,23 +315,20 @@ extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, con /** * Get a feature report from a HID device. * - * Set the first byte of `data` to the Report ID of the - * report to be read. Make sure to allow space for this - * extra byte in `data`. Upon return, the first byte will - * still contain the Report ID, and the report data will - * start in data[1]. + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. * * \param dev A device handle returned from SDL_hid_open(). - * \param data A buffer to put the read data into, including - * the Report ID. Set the first byte of `data` to the - * Report ID of the report to be read, or set it to zero - * if your device does not use numbered reports. - * \param length The number of bytes to read, including an - * extra byte for the report ID. The buffer can be longer - * than the actual report. - * - * \returns the number of bytes read plus one for the report ID - * (which is still in the first byte), or -1 on error. + * \param data A buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length The number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on error. * * \since This function is available since SDL 2.0.18. */ @@ -363,7 +347,6 @@ extern DECLSPEC void SDLCALL SDL_hid_close(SDL_hid_device *dev); * \param dev A device handle returned from SDL_hid_open(). * \param string A wide string buffer to put the data into. * \param maxlen The length of the buffer in multiples of wchar_t. - * * \returns 0 on success and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -376,7 +359,6 @@ extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, * \param dev A device handle returned from SDL_hid_open(). * \param string A wide string buffer to put the data into. * \param maxlen The length of the buffer in multiples of wchar_t. - * * \returns 0 on success and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -389,7 +371,6 @@ extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wcha * \param dev A device handle returned from SDL_hid_open(). * \param string A wide string buffer to put the data into. * \param maxlen The length of the buffer in multiples of wchar_t. - * * \returns 0 on success and -1 on error. * * \since This function is available since SDL 2.0.18. @@ -403,7 +384,6 @@ extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev * \param string_index The index of the string to get. * \param string A wide string buffer to put the data into. * \param maxlen The length of the buffer in multiples of wchar_t. - * * \returns 0 on success and -1 on error. * * \since This function is available since SDL 2.0.18. diff --git a/include/SDL_render.h b/include/SDL_render.h index daf2d9801..26e906f41 100644 --- a/include/SDL_render.h +++ b/include/SDL_render.h @@ -980,17 +980,21 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, float *scaleX, float *scaleY); /** - * Get logical coordinates of point in renderer when given real coordinates of point in window. - * Logical coordinates will differ from real coordinates when render is scaled and logical renderer size set - * - * \param renderer the renderer from which the logical coordinates should be calcualted + * Get logical coordinates of point in renderer when given real coordinates of + * point in window. + * + * Logical coordinates will differ from real coordinates when render is scaled + * and logical renderer size set + * + * \param renderer the renderer from which the logical coordinates should be + * calcualted * \param windowX the real X coordinate in the window * \param windowY the real Y coordinate in the window * \param logicalX the pointer filled with the logical x coordinate * \param logicalY the pointer filled with the logical y coordinate - * + * * \since This function is available since SDL 2.0.18. - * + * * \sa SDL_RenderGetScale * \sa SDL_RenderSetScale * \sa SDL_RenderGetLogicalSize @@ -1021,6 +1025,7 @@ extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer, extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer, float logicalX, float logicalY, int *windowX, int *windowY); + /** * Set the color used for drawing operations (Rect, Line and Clear). * @@ -1848,8 +1853,8 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); * This function returns `void *`, so SDL doesn't have to include Metal's * headers, but it can be safely cast to an `id`. * - * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to - * give SDL a drawable to render to, which might happen if the window is + * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give + * SDL a drawable to render to, which might happen if the window is * hidden/minimized/offscreen. This doesn't apply to command encoders for * render targets, just the window's backbacker. Check your return values! * diff --git a/include/SDL_system.h b/include/SDL_system.h index 8910d3fa7..e22a23c0c 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -148,7 +148,8 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio * * \param threadID The Unix thread ID to change priority of. * \param sdlPriority The new SDL_ThreadPriority value. - * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, SCHED_OTHER, etc...) + * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, + * SCHED_OTHER, etc...) * \returns 0 on success, or -1 on error. */ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); diff --git a/include/SDL_timer.h b/include/SDL_timer.h index 791f3b4c4..389f640c2 100644 --- a/include/SDL_timer.h +++ b/include/SDL_timer.h @@ -61,9 +61,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); * Get the number of milliseconds since SDL library initialization. * * Note that you should not use the SDL_TICKS_PASSED macro with values - * returned by this function, as that macro does clever math to compensate - * for the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. - * 64-bit values from this function can be safely compared directly. + * returned by this function, as that macro does clever math to compensate for + * the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. 64-bit + * values from this function can be safely compared directly. * * For example, if you want to wait 100 ms, you could do this: * diff --git a/include/SDL_video.h b/include/SDL_video.h index fc462d76d..8af719aa1 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -1389,8 +1389,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * * \param window The window that will be associated with the barrier. * \param rect A rectangle area in window-relative coordinates. If NULL the - * barrier for the specified window will be destroyed. - * + * barrier for the specified window will be destroyed. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1403,9 +1402,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SD * Get the mouse confinement rectangle of a window. * * \param window The window to query - * - * \returns A pointer to the mouse confinement rectangle of a window, - * or NULL if there isn't one. + * \returns A pointer to the mouse confinement rectangle of a window, or NULL + * if there isn't one. * * \sa SDL_SetWindowMouseRect */