mirror of https://github.com/encounter/SDL.git
Sync wiki -> header
This commit is contained in:
Ryan C. Gordon
parent
98c9836287
commit
b42ae3dbfe
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue