Sync wiki -> header

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

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.

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<MTLRenderCommandEncoder>`.
  *
- * 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!
  *

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);

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:
  *

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
  */