mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-10-26 12:27:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync wiki -> header

Browse Source
This commit is contained in:
Ryan C. Gordon
2021-11-10 15:21:01 -05:00
parent 98c9836287
commit b42ae3dbfe
6 changed files with 103 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
include/SDL_gamecontroller.h
View File

@@ -932,7 +932,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam
extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller); 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 gamecontroller the controller to query
* \param button a button on the game controller * \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); 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 gamecontroller the controller to query
* \param axis an axis on the game controller * \param axis an axis on the game controller

176
include/SDL_hidapi.h
View File

@@ -116,12 +116,11 @@ typedef struct SDL_hid_device_info
/** /**
* Initialize the HIDAPI library. * Initialize the HIDAPI library.
* *
* This function initializes the HIDAPI library. Calling it is not * This function initializes the HIDAPI library. Calling it is not strictly
* strictly necessary, as it will be called automatically by * necessary, as it will be called automatically by SDL_hid_enumerate() and
* SDL_hid_enumerate() and any of the SDL_hid_open_*() functions * any of the SDL_hid_open_*() functions if it is needed. This function should
* if it is needed. This function should be called at the beginning * be called at the beginning of execution however, if there is a chance of
* of execution however, if there is a chance of HIDAPI handles * HIDAPI handles being opened by different threads simultaneously.
* being opened by different threads simultaneously.
* *
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
@@ -132,9 +131,8 @@ extern DECLSPEC int SDLCALL SDL_hid_init(void);
/** /**
* Finalize the HIDAPI library. * Finalize the HIDAPI library.
* *
* This function frees all of the static data associated with * This function frees all of the static data associated with HIDAPI. It
* HIDAPI. It should be called at the end of execution to avoid * should be called at the end of execution to avoid memory leaks.
* memory leaks.
* *
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
@@ -145,20 +143,18 @@ extern DECLSPEC int SDLCALL SDL_hid_exit(void);
/** /**
* Enumerate the HID Devices. * Enumerate the HID Devices.
* *
* This function returns a linked list of all the HID devices * This function returns a linked list of all the HID devices attached to the
* attached to the system which match vendor_id and product_id. * system which match vendor_id and product_id. If `vendor_id` is set to 0
* If `vendor_id` is set to 0 then any vendor matches. * then any vendor matches. If `product_id` is set to 0 then any product
* If `product_id` is set to 0 then any product matches. * matches. If `vendor_id` and `product_id` are both set to 0, then all HID
* If `vendor_id` and `product_id` are both set to 0, then * devices will be returned.
* all HID devices will be returned.
* *
* \param vendor_id The Vendor ID (VID) of the types of device to open. * \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. * \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
* \returns a pointer to a linked list of type SDL_hid_device_info, * information about the HID devices attached to the system, or NULL
* containing information about the HID devices attached to the * in the case of failure. Free this linked list by calling
* system, or NULL in the case of failure. Free this linked list * SDL_hid_free_enumeration().
* by calling SDL_hid_free_enumeration().
* *
* \since This function is available since SDL 2.0.18. * \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(). * This function frees a linked list created by SDL_hid_enumerate().
* *
* \param devs Pointer to a list of struct_device returned from * \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); 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. * Write an Output report to a HID device.
* *
* The first byte of `data` must contain the Report ID. For * The first byte of `data` must contain the Report ID. For devices which only
* devices which only support a single report, this must be set * support a single report, this must be set to 0x0. The remaining bytes
* to 0x0. The remaining bytes contain the report data. Since * contain the report data. Since the Report ID is mandatory, calls to
* the Report ID is mandatory, calls to SDL_hid_write() will always * SDL_hid_write() will always contain one more byte than the report contains.
* contain one more byte than the report contains. For example, * For example, if a hid report is 16 bytes long, 17 bytes must be passed to
* 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),
* SDL_hid_write(), the Report ID (or 0x0, for devices with a * followed by the report data (16 bytes). In this example, the length passed
* single report), followed by the report data (16 bytes). In * in would be 17.
* this example, the length passed in would be 17.
* *
* SDL_hid_write() will send the data on the first OUT endpoint, if * SDL_hid_write() will send the data on the first OUT endpoint, if one
* one exists. If it does not, it will send the data through * exists. If it does not, it will send the data through the Control Endpoint
* the Control Endpoint (Endpoint 0). * (Endpoint 0).
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev A device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as * \param data The data to send, including the report number as the first
* the first byte. * byte.
* \param length The length in bytes of the data to send. * \param length The length in bytes of the data to send.
*
* \returns the actual number of bytes written and -1 on error. * \returns the actual number of bytes written and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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. * Read an Input report from a HID device with timeout.
* *
* Input reports are returned * Input reports are returned to the host through the INTERRUPT IN endpoint.
* to the host through the INTERRUPT IN endpoint. The first byte will * The first byte will contain the Report number if the device uses numbered
* contain the Report number if the device uses numbered reports. * reports.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev A device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into. * \param data A buffer to put the read data into.
* \param length The number of bytes to read. For devices with * \param length The number of bytes to read. For devices with multiple
* multiple reports, make sure to read an extra byte for * reports, make sure to read an extra byte for the report
* the report number. * number.
* \param milliseconds timeout in milliseconds or -1 for blocking wait. * \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
* \returns the actual number of bytes read and -1 on error. * available to be read within the timeout period, this function
If no packet was available to be read within the timeout period, this function returns 0. * returns 0.
* *
* \since This function is available since SDL 2.0.18. * \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. * Read an Input report from a HID device.
* *
* Input reports are returned * Input reports are returned to the host through the INTERRUPT IN endpoint.
* to the host through the INTERRUPT IN endpoint. The first byte will * The first byte will contain the Report number if the device uses numbered
* contain the Report number if the device uses numbered reports. * reports.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev A device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into. * \param data A buffer to put the read data into.
* \param length The number of bytes to read. For devices with * \param length The number of bytes to read. For devices with multiple
* multiple reports, make sure to read an extra byte for * reports, make sure to read an extra byte for the report
* the report number. * number.
* * \returns the actual number of bytes read and -1 on error. If no packet was
* \returns the actual number of bytes read and -1 on error. * available to be read and the handle is in non-blocking mode, this
* If no packet was available to be read and the handle is in non-blocking mode, this function returns 0. * function returns 0.
* *
* \since This function is available since SDL 2.0.18. * \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. * Set the device handle to be non-blocking.
* *
* In non-blocking mode calls to SDL_hid_read() will return * In non-blocking mode calls to SDL_hid_read() will return immediately with a
* immediately with a value of 0 if there is no data to be * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read()
* read. In blocking mode, SDL_hid_read() will wait (block) until * will wait (block) until there is data to read before returning.
* there is data to read before returning.
* *
* Nonblocking can be turned on and off at any time. * Nonblocking can be turned on and off at any time.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev A device handle returned from SDL_hid_open().
* \param nonblock enable or not the nonblocking reads * \param nonblock enable or not the nonblocking reads - 1 to enable
* - 1 to enable nonblocking * nonblocking - 0 to disable nonblocking.
* - 0 to disable nonblocking.
*
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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. * Send a Feature report to the device.
* *
* Feature reports are sent over the Control endpoint as a * Feature reports are sent over the Control endpoint as a Set_Report
* Set_Report transfer. The first byte of `data` must * transfer. The first byte of `data` must contain the Report ID. For devices
* contain the Report ID. For devices which only support a * which only support a single report, this must be set to 0x0. The remaining
* single report, this must be set to 0x0. The remaining bytes * bytes contain the report data. Since the Report ID is mandatory, calls to
* contain the report data. Since the Report ID is mandatory, * SDL_hid_send_feature_report() will always contain one more byte than the
* calls to SDL_hid_send_feature_report() will always contain one * report contains. For example, if a hid report is 16 bytes long, 17 bytes
* more byte than the report contains. For example, if a hid * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for
* report is 16 bytes long, 17 bytes must be passed to * devices which do not use numbered reports), followed by the report data (16
* SDL_hid_send_feature_report(): the Report ID (or 0x0, for * bytes). In this example, the length passed in would be 17.
* 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 dev A device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as * \param data The data to send, including the report number as the first
* the first byte. * byte.
* \param length The length in bytes of the data to send, including * \param length The length in bytes of the data to send, including the report
* the report number. * number.
*
* \returns the actual number of bytes written and -1 on error. * \returns the actual number of bytes written and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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. * Get a feature report from a HID device.
* *
* Set the first byte of `data` to the Report ID of the * Set the first byte of `data` to the Report ID of the report to be read.
* report to be read. Make sure to allow space for this * Make sure to allow space for this extra byte in `data`. Upon return, the
* extra byte in `data`. Upon return, the first byte will * first byte will still contain the Report ID, and the report data will start
* still contain the Report ID, and the report data will * in data[1].
* start in data[1].
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev A device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into, including * \param data A buffer to put the read data into, including the Report ID.
* the Report ID. Set the first byte of `data` to the * Set the first byte of `data` to the Report ID of the report to
* Report ID of the report to be read, or set it to zero * be read, or set it to zero if your device does not use numbered
* if your device does not use numbered reports. * reports.
* \param length The number of bytes to read, including an * \param length The number of bytes to read, including an extra byte for the
* extra byte for the report ID. The buffer can be longer * report ID. The buffer can be longer than the actual report.
* 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.
* \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. * \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 dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen The length of the buffer in multiples of wchar_t.
*
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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 dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen The length of the buffer in multiples of wchar_t.
*
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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 dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen The length of the buffer in multiples of wchar_t.
*
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \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_index The index of the string to get.
* \param string A wide string buffer to put the data into. * \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen The length of the buffer in multiples of wchar_t.
*
* \returns 0 on success and -1 on error. * \returns 0 on success and -1 on error.
* *
* \since This function is available since SDL 2.0.18. * \since This function is available since SDL 2.0.18.

21
include/SDL_render.h
View File

@@ -980,17 +980,21 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
float *scaleX, float *scaleY); float *scaleX, float *scaleY);
/** /**
* Get logical coordinates of point in renderer when given real coordinates of point in window. * Get logical coordinates of point in renderer when given real coordinates of
* Logical coordinates will differ from real coordinates when render is scaled and logical renderer size set * point in window.
* *
* \param renderer the renderer from which the logical coordinates should be calcualted * 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 windowX the real X coordinate in the window
* \param windowY the real Y coordinate in the window * \param windowY the real Y coordinate in the window
* \param logicalX the pointer filled with the logical x coordinate * \param logicalX the pointer filled with the logical x coordinate
* \param logicalY the pointer filled with the logical y coordinate * \param logicalY the pointer filled with the logical y coordinate
* *
* \since This function is available since SDL 2.0.18. * \since This function is available since SDL 2.0.18.
* *
* \sa SDL_RenderGetScale * \sa SDL_RenderGetScale
* \sa SDL_RenderSetScale * \sa SDL_RenderSetScale
* \sa SDL_RenderGetLogicalSize * \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, extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer,
float logicalX, float logicalY, float logicalX, float logicalY,
int *windowX, int *windowY); int *windowX, int *windowY);
/** /**
* Set the color used for drawing operations (Rect, Line and Clear). * 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 * This function returns `void *`, so SDL doesn't have to include Metal's
* headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`. * 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 * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give
* give SDL a drawable to render to, which might happen if the window is * SDL a drawable to render to, which might happen if the window is
* hidden/minimized/offscreen. This doesn't apply to command encoders for * hidden/minimized/offscreen. This doesn't apply to command encoders for
* render targets, just the window's backbacker. Check your return values! * render targets, just the window's backbacker. Check your return values!
* *

3
include/SDL_system.h
View File

@@ -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 threadID The Unix thread ID to change priority of.
* \param sdlPriority The new SDL_ThreadPriority value. * \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. * \returns 0 on success, or -1 on error.
*/ */
extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);

6
include/SDL_timer.h
View File

@@ -61,9 +61,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
* Get the number of milliseconds since SDL library initialization. * Get the number of milliseconds since SDL library initialization.
* *
* Note that you should not use the SDL_TICKS_PASSED macro with values * 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 * returned by this function, as that macro does clever math to compensate for
* for the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. * the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. 64-bit
* 64-bit values from this function can be safely compared directly. * values from this function can be safely compared directly.
* *
* For example, if you want to wait 100 ms, you could do this: * For example, if you want to wait 100 ms, you could do this:
* *

8
include/SDL_video.h
View File

@@ -1389,8 +1389,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
* *
* \param window The window that will be associated with the barrier. * \param window The window that will be associated with the barrier.
* \param rect A rectangle area in window-relative coordinates. If NULL the * \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 * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * 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. * Get the mouse confinement rectangle of a window.
* *
* \param window The window to query * \param window The window to query
* * \returns A pointer to the mouse confinement rectangle of a window, or NULL
* \returns A pointer to the mouse confinement rectangle of a window, * if there isn't one.
* or NULL if there isn't one.
* *
* \sa SDL_SetWindowMouseRect * \sa SDL_SetWindowMouseRect
*/ */