Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstrings #140

Merged
merged 1 commit into from
May 31, 2022
Merged

Add docstrings #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3,654 changes: 2,883 additions & 771 deletions src/sdl2.nim
View file
Open in desktop

Large diffs are not rendered by default.

928 changes: 533 additions & 395 deletions src/sdl2/audio.nim
View file
Open in desktop

Large diffs are not rendered by default.

284 changes: 116 additions & 168 deletions src/sdl2/gamecontroller.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
import "../sdl2"
import "joystick"

discard """
Simple DirectMedia Layer
Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
Expand All @@ -20,30 +17,27 @@ discard """
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
"""


## SDL game controller event handling
##
## In order to use these functions, `sdl.init()` must have been called
## with the `SDL_INIT_JOYSTICK` flag. This causes SDL to scan the system
## for game controllers, and load appropriate drivers.
##
## If you would like to receive controller updates while the application
## is in the background, you should set the following hint before calling
## init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS

\file SDL_gamecontroller.h

Include file for SDL game controller event handling
import "../sdl2"
import "joystick"

"""

##
# \file SDL_gamecontroller.h
#
# In order to use these functions, SDL_Init() must have been called
# with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system
# for game controllers, and load appropriate drivers.
#
# If you would like to receive controller updates while the application
# is in the background, you should set the following hint before calling
# SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
#

# The gamecontroller structure used to identify an SDL game controller# /
type
GameController* = object
## The gamecontroller structure used to identify an SDL game controller.

GameControllerPtr* = ptr GameController

GameControllerBindType* {.size: sizeof(cint).} = enum
Expand All @@ -56,6 +50,8 @@ type

type
GameControllerButtonBind* = object
## Get the SDL joystick layer binding
## for this controller button/axis mapping
case bindType*: GameControllerBindType
of SDL_CONTROLLER_BINDTYPE_NONE:
nil
Expand All @@ -71,128 +67,91 @@ when defined(SDL_Static):
else:
{.push callConv: cdecl, dynlib: LibName.}

##
# To count the number of game controllers in the system for the following:
# int nJoysticks = SDL_NumJoysticks();
# int nGameControllers = 0;
# for ( int i = 0; i < nJoysticks; i++ ) {
# if ( SDL_IsGameController(i) ) {
# nGameControllers++;
# }
# }
#
# Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
# guid,name,mappings
#
# Where GUID is the string value from SDL_JoystickGetGUIDString(), name is the human readable string for the device and mappings are controller mappings to joystick ones.
# Under Windows there is a reserved GUID of "xinput" that covers any XInput devices.
# The mapping format for joystick is:
# bX - a joystick button, index X
# hX.Y - hat X with value Y
# aX - axis X of the joystick
# Buttons can be used as a controller axis and vice versa.
#
# This string shows an example of a valid mapping for a controller
# "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
#
# /

##
# Add or update an existing mapping configuration
#
# \return 1 if mapping is added, 0 if updated, -1 on error
# /
proc gameControllerAddMapping* (mappingString: cstring): cint {.
proc gameControllerAddMapping*(mappingString: cstring): cint {.
importc: "SDL_GameControllerAddMapping".}
## Add or update an existing mapping configuration.
##
## `Return` `1` if mapping is added, `0` if updated, `-1` on error.

##
# Get a mapping string for a GUID
#
# \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available
# /
proc gameControllerMappingForGUID* (guid: JoystickGuid): cstring {.
proc gameControllerMappingForGUID*(guid: JoystickGuid): cstring {.
importc: "SDL_GameControllerMappingForGUID".}
## Get a mapping string for a GUID.
##
## `Return` the mapping string. Must be freed with `sdl.free()`.
## Returns `nil` if no mapping is available

##
# Get a mapping string for an open GameController
#
# \return the mapping string. Must be freed with SDL_free. Returns NULL if no mapping is available
# /
proc mapping* (gameController: GameControllerPtr): cstring {.
proc mapping*(gameController: GameControllerPtr): cstring {.
importc: "SDL_GameControllerMapping".}
## Get a mapping string for an open GameController.
##
## `Return` the mapping string. Must be freed with `sdl.free()`.
## Returns `nil` if no mapping is available

##
# Is the joystick on this index supported by the game controller interface?
# /
proc isGameController* (joystickIndex: cint): Bool32 {.
proc isGameController*(joystickIndex: cint): Bool32 {.
importc: "SDL_IsGameController".}
## Is the joystick on this index supported by the game controller interface?


##
# Get the implementation dependent name of a game controller.
# This can be called before any controllers are opened.
# If no name can be found, this function returns NULL.
# /
proc gameControllerNameForIndex* (joystickIndex: cint): cstring {.
proc gameControllerNameForIndex*(joystickIndex: cint): cstring {.
importc: "SDL_GameControllerNameForIndex".}
## Get the implementation dependent name of a game controller.
##
## This can be called before any controllers are opened.
## If no name can be found, this procedure returns `nil`.

##
# Open a game controller for use.
# The index passed as an argument refers to the N'th game controller on the system.
# This index is the value which will identify this controller in future controller
# events.
#
# \return A controller identifier, or NULL if an error occurred.
# /
proc gameControllerOpen* (joystickIndex: cint): GameControllerPtr {.
proc gameControllerOpen*(joystickIndex: cint): GameControllerPtr {.
importc: "SDL_GameControllerOpen".}

##
# Return the name for this currently opened controller
# /
proc name* (gameController: GameControllerPtr): cstring {.
## Open a game controller for use.
##
## The index passed as an argument refers to the N'th game controller
## on the system.
##
## This index is not the value which will identify this controller in future
## controller events. The joystick's instance id (`JoystickID`) will be
## used there instead.
##
## `Return` a controller identifier, or `nil` if an error occurred.

proc name*(gameController: GameControllerPtr): cstring {.
importc: "SDL_GameControllerName".}
## `Return` the name for this currently opened controller.

##
# Returns SDL_TRUE if the controller has been opened and currently connected,
# or SDL_FALSE if it has not.
# /
proc getAttached* (gameController: GameControllerPtr): Bool32 {.
proc getAttached*(gameController: GameControllerPtr): Bool32 {.
importc: "SDL_GameControllerGetAttached".}
## `Returns` `true` if the controller has been opened and currently
## connected, or `false` if it has not.

##
# Get the underlying joystick object used by a controller
# /
proc getJoystick* (gameController: GameControllerPtr): JoystickPtr {.
proc getJoystick*(gameController: GameControllerPtr): JoystickPtr {.
importc: "SDL_GameControllerGetJoystick".}
## Get the underlying joystick object used by a controller.

##
# Enable/disable controller event polling.
#
# If controller events are disabled, you must call SDL_GameControllerUpdate()
# yourself and check the state of the controller when you want controller
# information.
#
# The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
# /
proc gameControllerEventState* (state: cint): cint {.
proc gameControllerEventState*(state: cint): cint {.
importc: "SDL_GameControllerEventState".}
## Enable/disable controller event polling.
##
## If controller events are disabled, you must call
## `gameControllerUpdate()` yourself and check the state of the
## controller when you want controller information.
##
## The state can be one of `SDL_QUERY`, `SDL_ENABLE` or `SDL_IGNORE`.

##
# Update the current state of the open game controllers.
#
# This is called automatically by the event loop if any game controller
# events are enabled.
# /
proc gameControllerUpdate* () {.
importc: "SDL_GameControllerUpdate".}

proc gameControllerUpdate*() {.importc: "SDL_GameControllerUpdate".}
## Update the current state of the open game controllers.
##
## This is called automatically by the event loop if any game controller
## events are enabled.

##
# The list of axes available from a controller
# /
type
GameControllerAxis* {.size: sizeof(cint).} = enum
## The list of axes available from a controller.
##
## Thumbstick axis values range
## from `JOYSTICK_AXIS_MIN` to `JOYSTICK_AXIS_MAX`,
## and are centered within ~8000 of zero,
## though advanced UI will allow users to set
## or autodetect the dead zone, which varies between controllers.
##
## Trigger axis values range from `0` to `JOYSTICK_AXIS_MAX`.
SDL_CONTROLLER_AXIS_INVALID = -1,
SDL_CONTROLLER_AXIS_LEFTX,
SDL_CONTROLLER_AXIS_LEFTY,
Expand All @@ -202,41 +161,34 @@ type
SDL_CONTROLLER_AXIS_TRIGGERRIGHT,
SDL_CONTROLLER_AXIS_MAX

converter toInt* (some: GameControllerAxis): uint8 = uint8(some)
converter toInt*(some: GameControllerAxis): uint8 = uint8(some)

##
# turn this string into a axis mapping
# /
proc gameControllerGetAxisFromString* (pchString: cstring): GameControllerAxis {.
proc gameControllerGetAxisFromString*(pchString: cstring): GameControllerAxis {.
importc: "SDL_GameControllerGetAxisFromString".}
## Turn this string into a axis mapping.

##
# turn this axis enum into a string mapping
# /
proc gameControllerGetStringForAxis* (axis: GameControllerAxis): cstring {.
proc gameControllerGetStringForAxis*(axis: GameControllerAxis): cstring {.
importc: "SDL_GameControllerGetStringForAxis".}
## Turn this axis enum into a string mapping.

##
# Get the SDL joystick layer binding for this controller button mapping
# /
proc getBindForAxis* (gameController: GameControllerPtr, axis: GameControllerAxis): GameControllerButtonBind {.
importc: "SDL_GameControllerGetBindForAxis".}
proc getBindForAxis*(gameController: GameControllerPtr,
axis: GameControllerAxis): GameControllerButtonBind {.
importc: "SDL_GameControllerGetBindForAxis".}
## Get the SDL joystick layer binding for this controller button mapping.

##
# Get the current state of an axis control on a game controller.
#
# The state is a value ranging from -32768 to 32767.
#
# The axis indices start at index 0.
# /
proc getAxis* (gameController: GameControllerPtr, axis: GameControllerAxis): int16 {.
proc getAxis*(gameController: GameControllerPtr,
axis: GameControllerAxis): int16 {.
importc: "SDL_GameControllerGetAxis".}
## Get the current state of an axis control on a game controller.
##
## The state is a value ranging from `-32768` to `32767`
## (except for the triggers, which range from `0` to `32767`.
##
## The axis indices start at index `0`.

##
# The list of buttons available from a controller
# /
type
GameControllerButton* {.size: sizeof(cint).} = enum
## The list of buttons available from a controller
SDL_CONTROLLER_BUTTON_INVALID = -1,
SDL_CONTROLLER_BUTTON_A,
SDL_CONTROLLER_BUTTON_B,
Expand All @@ -255,40 +207,36 @@ type
SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
SDL_CONTROLLER_BUTTON_MAX

converter toInt* (some: GameControllerButton): uint8 = uint8(some)
converter toInt*(some: GameControllerButton): uint8 = uint8(some)

##
# turn this string into a button mapping
# /
proc gameControllerGetButtonFromString* (pchString: cstring): GameControllerButton {.
proc gameControllerGetButtonFromString*(
pchString: cstring): GameControllerButton {.
importc: "SDL_GameControllerGetButtonFromString".}
## Turn this string into a button mapping.

##
# turn this button enum into a string mapping
# /
proc gameControllerGetStringForButton* (button: GameControllerButton): cstring {.
proc gameControllerGetStringForButton*(
button: GameControllerButton): cstring {.
importc: "SDL_GameControllerGetStringForButton".}
## Turn this button enum into a string mapping.

##
# Get the SDL joystick layer binding for this controller button mapping
# /
proc getBindForButton* (gameController: GameControllerPtr, button: GameControllerButton): GameControllerButtonBind {.
proc getBindForButton*(
gameController: GameControllerPtr,
button: GameControllerButton): GameControllerButtonBind {.
importc: "SDL_GameControllerGetBindForButton".}
## Get the SDL joystick layer binding for this controller button mapping.


##
# Get the current state of a button on a game controller.
#
# The button indices start at index 0.
# /
proc getButton* (gameController: GameControllerPtr, button: GameControllerButton): uint8 {.
proc getButton*(
gameController: GameControllerPtr,
button: GameControllerButton): uint8 {.
importc: "SDL_GameControllerGetButton".}
## Get the current state of a button on a game controller.
##
## The button indices start at index `0`.

##
# Close a controller previously opened with SDL_GameControllerOpen().
# /
proc close* (gameController: GameControllerPtr) {.
proc close*(gameController: GameControllerPtr) {.
importc: "SDL_GameControllerClose".}
## Close a controller previously opened with `gameControllerOpen()`.


when not defined(SDL_Static):
{.pop.}
Loading