diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4bd6b982..fd57e187 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,8 +7,8 @@ on: branches: [ master ] jobs: - macos-11: - runs-on: macos-11 + macos-14-sonoma: + runs-on: macos-14 steps: - name: Install FPC run: | @@ -17,37 +17,61 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Compile SDL2 unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2.pas verbosity: ewnh - name: Compile SDL2_gfx unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_gfx.pas verbosity: ewnh - name: Compile SDL2_image unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_image.pas verbosity: ewnh - name: Compile SDL2_mixer unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_mixer.pas verbosity: ewnh - name: Compile SDL2_net unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_net.pas verbosity: ewnh - name: Compile SDL2_ttf unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_ttf.pas verbosity: ewnh - ubuntu-20-04: - runs-on: ubuntu-20.04 + - name: Install SDL2 library + run: brew install sdl2 + - name: Get SDL2 library version and path(s) + run: | + sdl2-config --version + sdl2-config --libs + - name: Test 1 - Compile Init Test + uses: suve/GHActions-FPC@v0.4.0 + with: + source: tests/testinit.pas + flags: Fl/opt/homebrew/lib + verbosity: ewnh + - name: Test 1 - Run Init Test + run: | + ./tests/testinit + - name: Test 2 - Compile Version Test + uses: suve/GHActions-FPC@v0.4.0 + with: + source: tests/testversion.pas + flags: Fl/opt/homebrew/lib + verbosity: ewnh + - name: Test 2 - Run Version Test + run: | + ./tests/testversion + ubuntu-22-04: + runs-on: ubuntu-22.04 steps: - name: Install FPC run: | @@ -57,35 +81,55 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Compile SDL2 unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2.pas verbosity: ewnh - name: Compile SDL2_gfx unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_gfx.pas verbosity: ewnh - name: Compile SDL2_image unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_image.pas verbosity: ewnh - name: Compile SDL2_mixer unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_mixer.pas verbosity: ewnh - name: Compile SDL2_net unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_net.pas verbosity: ewnh - name: Compile SDL2_ttf unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_ttf.pas verbosity: ewnh + - name: Install SDL2 library + run: sudo apt-get install libsdl2-dev + - name: Test 1 - Compile Init Test + uses: suve/GHActions-FPC@v0.4.0 + with: + source: tests/testinit.pas + verbosity: ewnh + - name: Test 1 - Run Init Test + run: | + mkdir ~/tmp + export XDG_RUNTIME_DIR=~/tmp + ./tests/testinit + - name: Test 2 - Compile Version Test + uses: suve/GHActions-FPC@v0.4.0 + with: + source: tests/testversion.pas + verbosity: ewnh + - name: Test 2 - Run Version Test + run: | + ./tests/testversion windows-2022: runs-on: windows-2022 steps: @@ -95,33 +139,43 @@ jobs: - name: Checkout code uses: actions/checkout@v2 - name: Compile SDL2 unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2.pas verbosity: ewnh - name: Compile SDL2_gfx unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_gfx.pas verbosity: ewnh - name: Compile SDL2_image unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_image.pas verbosity: ewnh - name: Compile SDL2_mixer unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_mixer.pas verbosity: ewnh - name: Compile SDL2_net unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_net.pas verbosity: ewnh - name: Compile SDL2_ttf unit - uses: suve/GHActions-FPC@v0.3.2 + uses: suve/GHActions-FPC@v0.4.0 with: source: units/sdl2_ttf.pas verbosity: ewnh - + - name: Test 1 - Compile Init Test + uses: suve/GHActions-FPC@v0.4.0 + with: + source: tests/testinit.pas + flags: Flunits + verbosity: ewnh + # !!! Since no SDL2.DLL is available via chocolatey, the run will fail. + # TODO: Find solution to install SDL2 binary. + # - name: Test 1 - Run Init Test + # run: | + # ./tests/testinit.exe diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..033ce5e6 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,44 @@ +name: Build and deploy documentation + +on: + push: + branches: ["master"] + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-22.04 + steps: + - name: Install PasDoc + run: | + export DEBIAN_FRONTEND=noninteractive + sudo apt update + sudo apt install -y pasdoc + - name: Checkout + uses: actions/checkout@v3 + - name: Build documentation + run: | + mkdir gh-pages/ + pasdoc --output gh-pages/ --format html --ignore-leading '*' --sort constants,functions,types,structures --define FPC --include units/ units/*.pas + - name: Setup Pages + uses: actions/configure-pages@v2 + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: 'gh-pages/' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/.gitignore b/.gitignore index e76e9a2b..52b5ef85 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ bin/* *.ppu *.or *.lps +*.lpi *.compiled Win32/* Win64/* diff --git a/CHEATSHEET.md b/CHEATSHEET.md index c6f2a541..2cd31c84 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -8,7 +8,7 @@ conversion project. C: -``` +```c #define SDL_HAT_CENTERED 0x00 #define SDL_HAT_UP 0x01 #define SDL_HAT_RIGHT 0x02 @@ -22,7 +22,7 @@ C: Pascal: -``` +```pascal const SDL_HAT_CENTERED = $00; SDL_HAT_UP = $01; @@ -39,7 +39,7 @@ const C: -``` +```c typedef enum { SDL_JOYSTICK_POWER_UNKNOWN = -1, @@ -54,8 +54,10 @@ typedef enum Pascal: -``` +```pascal type + PPSDL_JoystickPowerLevel = ^PSDL_JoystickPowerLevel; + PSDL_JoystickPowerLevel = ^TSDL_JoystickPowerLevel; TSDL_JoystickPowerLevel = type Integer; const @@ -70,8 +72,14 @@ const Hint 1: C enums start at 0 if no explicit value is set. -Hint 2: The type should be Word if only unsigned values are possible. Otherwise -it should be Integer. +Hint 2: The type should always be cint. Most C compilers have the enum elements +> In C, each enumeration constant has type int and each enumeration type +> is compatible with some integer type. (The integer types include all three +> character types–plain, signed, and unsigned.) The choice of compatible +> type is implementation-defined. The C standard grants the freedom to +> use different integer types to represent different enumeration types, +> but most compilers just use int to represent all enumeration types. +Ref.: [https://www.embedded.com/enumerations-are-integers-except-when-theyre-not/](https://www.embedded.com/enumerations-are-integers-except-when-theyre-not/) Hint 3: Do not translate C enums to Pascal enums. C enums are handled like plain integers which will make bitwise operations (e. g. in macros) possible @@ -79,9 +87,11 @@ without typecasting. ## Structs +### Defined Structs + C: -``` +```c typedef struct SDL_version { Uint8 major; /**< major version */ @@ -92,8 +102,9 @@ typedef struct SDL_version Pascal: -``` +```pascal type + PPSDL_Version = ^PSDL_Version; PSDL_Version = ^TSDL_Version; TSDL_Version = record major: cuint8 { major version } @@ -102,14 +113,37 @@ type end; ``` -Hint 1: If you have something like ```typedef struct name name```. it is likely -that the declaration is somewhere else (even other file). +### Opaque Structs -## Unions +If you have something like ```typedef struct name name```. the concrete +structure is opaque, and the programmer is expected to only ever +interact with pointers to the struct. C: +```c +typedef struct SDL_Window SDL_Window; ``` + +Pascal: + +```pascal +type + PPSDL_Window = ^PSDL_Window; + PSDL_Window = type Pointer; +``` + +As shown above, for opaque structs, we avoid defining the base `TType` +and define only the pointer `PType`. +For the rationale behind this decision, read the discussion in +[issue #63](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/63). + + +## Unions + +C: + +```c typedef union { /** \brief A cutoff alpha value for binarization of the window shape's alpha channel. */ Uint8 binarizationCutoff; @@ -119,8 +153,9 @@ typedef union { Pascal: -``` +```pascal type + PPSDL_WindowShapeParams = ^PSDL_WindowShapeParams; PSDL_WindowShapeParams = ^TSDL_WindowShapeParams; TSDL_WindowShapeParams = record case cint of @@ -134,7 +169,7 @@ type C: -``` +```c extern DECLSPEC void SDLCALL SDL_LockJoysticks(void); extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); @@ -142,7 +177,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); Pascal: -``` +```pascal procedure SDL_LockJoysticks(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockJoysticks' {$ENDIF} {$ENDIF}; @@ -150,4 +185,77 @@ function SDL_JoystickNameForIndex(device_index: cint): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNameForIndex' {$ENDIF} {$ENDIF}; ``` +## C Macros + +Macros are pre-processed constructs in C which have no analogue in Pascal. +Usually a C macro is translated as a Pascal function and implemented in SDL2.pas. + +C: +```c +#define SDL_VERSION_ATLEAST(X, Y, Z) \ + (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z)) +``` + +Pascal: + +_sdlversion.inc (declaration)_: +```pascal +function SDL_VERSION_ATLEAST(X,Y,Z: cuint8): Boolean; +``` + +_sdl2.pas (implementation)_: +```pascal +function SDL_VERSION_ATLEAST(X,Y,Z: cuint8): Boolean; +begin + Result := SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X,Y,Z); +end; +``` +Hint: As can be seen from this example, the macro has no clearly defined +argument types and return value type. The types to be used for arguments and +return values depend on the context in which this macro is used. Here from the +context is known that X, Y and Z stand for the major version, minor version and +the patch level which are declared to be 8 bit unsigned integers. From the +context it is also clear, that the macro returns true or false, hence the +function should return a Boolean value. The context does not suggest to use, +e. g., TSDL_Bool here, although in a different context this could be the better +translation. + +## When to use TSDL_Bool? + +TSDL_Bool is memory compatible with C's bool (integer size, e. g. 2 or 4 bytes). +Pascal's Boolean is different and typically 1 byte in size. ([FPC Ref.](https://www.freepascal.org/docs-html/current/ref/refsu4.html#x26-270003.1.1)) + +* return values and paramters of original SDL functions which are of SDL_Bool type, should be translated with TSDL_Bool +* DO NOT use TSDL_Bool for macro functions which evaluate to a boolean value, use Pascal's Boolean instead (exception: the value is an argument for a SDL_Bool parameter) + +_Example code_ +```pascal +program SDLBoolTest; + +uses SDL2, ctypes, SysUtils; + +var + a, b: Integer; + +function BoolTest(a, b: Integer): TSDL_Bool; +begin + // works + //Result := TSDL_Bool(a > b); + + // works, too + Result := (a > b); +end; + +begin + writeln('Bool Test a > b'); + for a:= 0 to 3 do + for b := 0 to 3 do + begin + write('a = ' + IntToStr(a) + '; b = ' + IntToStr(b) +'; Result = '); + writeln(BoolTest(a, b)); + end; + + readln; +end. +``` diff --git a/LEGACYCHANGELOG.md b/LEGACYCHANGELOG.md index cdfee2cd..3f7d27ce 100644 --- a/LEGACYCHANGELOG.md +++ b/LEGACYCHANGELOG.md @@ -83,3 +83,11 @@ v.1.70-stable; 16.09.2013: Initial Commit v.1.72-stable; 29.09.2013: fixed bug with procedures without parameters (they must have brackets) v.1.70-stable; 11.09.2013: Initial Commit + +## Extracted from jedi.inc + +v. 1.63-stable; 16.09.13: since GPC isn't supported anymore, i've deleted it from here, too. + +v. 1.22-alpha; 24.07.13: fixed some bugs. special thanks to kotai from pascalgamedevelopment.com + +v. 1.00-alpha; 05.07.13: Initial Alpha-Release diff --git a/README.md b/README.md index 36c768b0..5426f796 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Unit files for building [Free Pascal](https://freepascal.org/) / [Delphi](https://www.embarcadero.com/products/delphi) applications using the [SDL2 library](https://libsdl.org). -This repository is a community-maintained fork of the [Pascal-SDL-2-Headers](https://github.com/ev1313/Pascal-SDL-2-Headers) repo. +The [SDL2-for-Pascal](https://github.com/PascalGameDevelopment/SDL2-for-Pascal) repository is a community-maintained fork of the [Pascal-SDL-2-Headers](https://github.com/ev1313/Pascal-SDL-2-Headers) repository. ## Installation @@ -15,27 +15,36 @@ Simply add the units to your include path. You can achieve this by: Use the `sdl2` unit for the main SDL2 library (should be always needed). Units for the other SDL2 libraries are also provided: - [`sdl2_gfx`](https://www.ferzkopp.net/wordpress/2016/01/02/sdl_gfx-sdl2_gfx/) - - [`sdl2_image`](https://www.libsdl.org/projects/SDL_image/) - - [`sdl2_mixer`](https://www.libsdl.org/projects/SDL_mixer/) - - [`sdl2_net`](https://www.libsdl.org/projects/SDL_net/) - - [`sdl2_ttf`](https://www.libsdl.org/projects/SDL_ttf/) + - [`sdl2_image`](https://github.com/libsdl-org/SDL_image) + - [`sdl2_mixer`](https://github.com/libsdl-org/SDL_mixer) + - [`sdl2_net`](https://github.com/libsdl-org/SDL_net) + - [`sdl2_ttf`](https://github.com/libsdl-org/SDL_ttf) + +## Documentation + +[Official SDL2-for-Pascal Documentation](https://pascalgamedevelopment.github.io/SDL2-for-Pascal) + +### Further Resources + +[Free Pascal meets SDL](https://www.freepascal-meets-sdl.net) + +[PGD SDL2 Forum](https://www.pascalgamedevelopment.com/forumdisplay.php?26-SDL-SDL-2) ## Bugs / Contributions / ToDos If you have any contributions or bugfixes, feel free to drop a pull request or send in a patch. +Please use the GitHub [issue tracker](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues). -Please use the GitHub issue tracker for bug reports. ### ToDos - (Continously) Update files by new SDL2 functions and types which are present in more recent SDL2 versions. - (Continously atm.) Translate integer aliases into typed enums. See part Enums on the [Cheat sheet](CHEATSHEET.md) for reference. -- (Continously) Check FPC/Delphi compatibility. +- (Continously) improve Delphi-compatibility (and even more important, DO NOT break it) - (Continously) Adapt comments to [PasDoc format](https://pasdoc.github.io). (See issue [#22](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/22)) -- Update sdlthread.inc -## Code style guidelines +### Code style guidelines The main principle is to stay as tight as possible at the names in the C headers. These guidelines aim to have better consistency in this community project and make @@ -50,13 +59,21 @@ Ex.: `type` in C function `SDL_HasEvent(Uint32 type)` changes into `type_` in Pascal function `SDL_HasEvent(type_: TSDL_EventType)`. 3. Use C data types like `cuint8`, `cuint16`, `cuint32`, `cint8`, `cint16`, -`cint32`, `cfloat` and so on as often as possible if it is used in the -original code. Do not replace them by Pascal equivalents. -Ex.: Use `cuint32` (if `Uint32` is used in +`cint32`, `cfloat` and so on if native C data types are used in the +original code. Note: For FPC you need to add the unit `ctypes` to use these C +data types. For Delphi we have a temporary solution provided. (see issue [#67](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/67)) + +**Example:** Use `cuint32` (if `Uint32` is used in the original code) instead of `UInt32`, `Cardinal`, `LongWord` or `DWord`. -Exceptions: Replace `*char` by `PAnsiChar` (see issue [#26](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/26)) and `SDL_bool` by `Boolean` (see issue [#30](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/30)). +Exception: Replace `*char` by `PAnsiChar`! (see issue [#26](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/26)) + +**Hint:** Use `TSDL_Bool` to translate `SDL_bool`. For [macro functions](CHEATSHEET.md) use `Boolean`. (see issue [#30](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/30)). + +4. If an identifier or a function declaration is gone, mark them as `deprecated`. (see issue [#34](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/34)) -4. Have a look at our [Translation Cheat Sheet](CHEATSHEET.md) for reference. +5. For convenience we encourage to add single and double pointers for any SDL type. (see issue [#105](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/105)) + +6. Have a look at our [Translation Cheat Sheet](CHEATSHEET.md) for reference. ## Versions @@ -64,14 +81,33 @@ The version tag (see [tags](https://github.com/PascalGameDevelopment/SDL2-for-Pa ### v2.x (work in progress) -- be up-to-date with version 2.0.14 of the `SDL2 library` -- replaced all aliases by typed enums -- improve Delphi-compatibility (and even more important, DO NOT break it) -- (done) replace data types by c data types (see PR [#29](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/pull/29)) -- (done) add folders to project -- (done) shift all units into unit folder (see PR [#27](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/pull/27)) - -### v2.1 (Compatibility Release) +- updates + +### v2.3 Stable (16/03/2025) + +- updates sdl2_mixer unit to v2.8.1 +- updates sdl2_ttf unit to v2.24.0 +- major update of sdlthreads.inc +- update of sdlvideo.inc +- update of sdlrenderer.inc +- update of sdlgamecontroller.inc +- patches, cleanups and bugfixes in many other inc files +- bugfixes in sdl2_gfx unit +- deletes obsolete files +- improve CI workflow +- improve Delphi compatibility + +### v2.2 Stable (02/01/2024) + +- SDL2 unit is up-to-date with _at least_ version 2.0.14 of the `SDL2 library` +- many aliases got replaced by typed enums +- add single and double pointers for all types (thanks furious-programming) +- update SDL_ttf.pas to latest version 2.21.0 +- replace data types by c data types (see PR [#29](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/pull/29)) +- add folder structure (see PR [#27](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/pull/27)) +- many bugfixes + +### v2.1 Compatibility Release (25/09/2021) - This release has all commits until the change of the project folder structure (see PR [#27](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/pull/27)). Compare the disucssion in issue #22. - Moving the units to a new location may (1) raise difficulties in committing new changes if the branch was started before and (2) make updates of project research pathes necessary. diff --git a/tests/testinit.pas b/tests/testinit.pas new file mode 100644 index 00000000..eefd363d --- /dev/null +++ b/tests/testinit.pas @@ -0,0 +1,56 @@ +program testinit; + +{ + + Test initilization of SDL2 system with a sample of flags. + + This file is part of + + SDL2-for-Pascal + Copyright (C) 2020-2022 PGD Community + Visit: https://github.com/PascalGameDevelopment/SDL2-for-Pascal + +} + +{$I testsettings.inc} + +uses + Classes, SysUtils, SDL2; + +type + ESDL2Error = class(Exception); + +const + Flags: array[0..12] of TSDL_Init = ( + { single flags } + SDL_INIT_TIMER, SDL_INIT_AUDIO, SDL_INIT_VIDEO, + SDL_INIT_JOYSTICK, SDL_INIT_HAPTIC, SDL_INIT_GAMECONTROLLER, + SDL_INIT_EVENTS, SDL_INIT_SENSOR, SDL_INIT_NOPARACHUTE, + SDL_INIT_EVERYTHING, + { typically combined flags } + SDL_INIT_AUDIO or SDL_INIT_VIDEO, + SDL_INIT_VIDEO or SDL_INIT_JOYSTICK, + SDL_INIT_VIDEO or SDL_INIT_GAMECONTROLLER or SDL_INIT_AUDIO); + +var + Flag: TSDL_Init; +begin + write('Start SDL2 inilization test... '); + for Flag in Flags do + begin + try + if SDL_Init(Flag) <> 0 then + raise ESDL2Error.Create('SDL_Init failed: Flag = ' + IntToStr(Flag)); + except + on E: ESDL2Error do + try + SDL_Quit; + except + raise; + end; + end; + SDL_Quit; + end; + writeln(' finished.'); +end. + diff --git a/tests/testsettings.inc b/tests/testsettings.inc new file mode 100644 index 00000000..b07c4143 --- /dev/null +++ b/tests/testsettings.inc @@ -0,0 +1,5 @@ +{$IFDEF FPC} + {$MODE DELPHI}{$H+} + {$UNITPATH ../units} // Does this work in Delphi? +{$ENDIF} + diff --git a/tests/testversion.pas b/tests/testversion.pas new file mode 100644 index 00000000..5526b28c --- /dev/null +++ b/tests/testversion.pas @@ -0,0 +1,56 @@ +program testversion; + +{ + + Test version macros/functions of SDL2 system. + + This file is part of + + SDL2-for-Pascal + Copyright (C) 2020-2022 PGD Community + Visit: https://github.com/PascalGameDevelopment/SDL2-for-Pascal + +} + +{$I testsettings.inc} + +uses + Classes, SysUtils, SDL2; + +type + ESDL2Error = class(Exception); + +var + CompiledVersion: TSDL_Version = (major: 0; minor: 0; patch: 0); + LinkedVersion: TSDL_Version = (major: 0; minor: 0; patch: 0); + VersionNum: Cardinal = 0; +begin + write('Start SDL2 version test... '); + + try + VersionNum := SDL_VERSIONNUM(1,2,3); + if (VersionNum <> 1203) then + raise ESDL2Error.Create('SDL_VERSIONNUM failed: 1203 expected, found: ' + IntToStr(VersionNum)); + + SDL_VERSION(CompiledVersion); + if (SDL_COMPILEDVERSION <> SDL_VERSIONNUM(CompiledVersion.major, CompiledVersion.minor, CompiledVersion.patch)) then + raise ESDL2Error.Create('SDL_VERSION or SDL_COMPILEDVERSION failed: Version results do not match!'); + + if not SDL_VERSION_ATLEAST(2,0,0) then + raise ESDL2Error.Create('SDL_VERSION_ATLEAST failed: Version at least 2.0.0 should be true!'); + + if SDL_VERSION_ATLEAST(3,0,0) then + raise ESDL2Error.Create('SDL_VERSION_ATLEAST failed: Version at least 3.0.0 should be false!'); + + SDL_GetVersion(@LinkedVersion); + if @LinkedVersion = nil then + raise ESDL2Error.Create('SDL_GetVersion failed: ' + SDL_GetError()); + + if SDL_VERSIONNUM(LinkedVersion.major, LinkedVersion.minor, LinkedVersion.patch) = 0 then + raise ESDL2Error.Create('SDL_GetVersion failed: Returns 0.0.0 .'); + except + end; + + writeln('finished.'); +end. + diff --git a/units/ctypes.inc b/units/ctypes.inc index 6b596d2a..cd0b26ff 100644 --- a/units/ctypes.inc +++ b/units/ctypes.inc @@ -24,10 +24,12 @@ type DWord = LongWord; - pcint = ^cint; - cint = Integer; - {$EXTERNALSYM cint} + ppcbool = ^pcbool; + pcbool = ^cbool; + cbool = LongBool; + {$EXTERNALSYM cbool} + ppcint8 = ^pcint8; pcint8 = ^cint8; cint8 = ShortInt; {$EXTERNALSYM cint8} @@ -36,29 +38,33 @@ type cuint8 = Byte; {$EXTERNALSYM cuint8} + ppcint16 = ^pcint16; pcint16 = ^cint16; cint16 = SmallInt; {$EXTERNALSYM cint16} + ppcuint16 = ^pcuint16; pcuint16 = ^cuint16; cuint16 = Word; {$EXTERNALSYM cuint16} + ppcushort = ^pcushort; + pcushort = ^cushort; + cushort = Word; + {$EXTERNALSYM cushort} + + ppcint32 = ^pcint32; pcint32 = ^cint32; cint32 = LongInt; {$EXTERNALSYM cint32} + ppcuint32 = ^pcuint32; pcuint32 = ^cuint32; cuint32 = LongWord; {$EXTERNALSYM cuint32} - culong = LongWord; - {$EXTERNALSYM culong} - - cuint = LongWord; - {$EXTERNALSYM cuint} - {$IFNDEF Has_Int64} + ppcint64 = ^pcint64; pcint64 = ^cint64; cint64 = record hi: cuint32; @@ -66,6 +72,7 @@ type end; {$EXTERNALSYM cint64} + ppcuint64 = ^pcuint64; pcuint64 = ^cuint64; cuint64 = record hi: cuint32; @@ -73,31 +80,124 @@ type end; {$EXTERNALSYM cuint64} {$ELSE} + ppcint64 = ^pcint64; pcint64 = ^cint64; cint64 = Int64; {$EXTERNALSYM cint64} + ppcuint64 = ^pcuint64; pcuint64 = ^cuint64; cuint64 = UInt64; {$EXTERNALSYM cuint64} {$ENDIF} + ppcsize_t = ^pcsize_t; + pcsize_t = ^csize_t; {$IFNDEF WIN64} csize_t = cuint32; {$ELSE} csize_t = cuint64; {$ENDIF} - {$EXTERNALSYM SIZE_T} + {$EXTERNALSYM csize_t} + ppcfloat = ^pcfloat; pcfloat = ^cfloat; cfloat = Single; {$EXTERNALSYM cfloat} + + ppcdouble = ^pcdouble; + pcdouble = ^cdouble; + cdouble = Double; + {$EXTERNALSYM cfloat} + + ppcint = ^pcint; + pcint = ^cint; + + ppcuint = ^pcuint; + pcuint = ^cuint; + + ppclong = ^pclong; + pclong = ^clong; + + ppculong = ^pculong; + pculong = ^culong; + { + Integer type sizes based on: + https://en.cppreference.com/w/c/language/arithmetic_types#Data_models + } + cint = cint32; + cuint = cuint32; + {$IF DEFINED(CPU32) OR DEFINED(CPU32BITS)} + clong = cint32; + culong = cuint32; + {$ELSE} // 64-bit + {$IFDEF MSWINDOWS} + clong = cint32; + culong = cuint32; + {$ELSE} + clong = cint64; + culong = cuint64; + {$ENDIF} + {$ENDIF} + {$EXTERNALSYM cint} + {$EXTERNALSYM cuint} + {$EXTERNALSYM clong} + {$EXTERNALSYM culong} + {$ENDIF} { Data types for all compilers } type + PPUInt8Array = ^PUInt8Array; PUInt8Array = ^TUInt8Array; TUInt8Array = array [0..MAXINT shr 1] of cuint8; ppcuint8 = ^pcuint8; + { "The following type designates an unsigned integer type [or signed respectivly] + with the property that any valid pointer to void can be + converted to this type, then converted back to a pointer + to void, and the result will compare equal to the original + pointer: uintptr_t" + Source: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/stdint.h.html + } + {$IFNDEF FPC} + cuintptr_t = UIntPtr; + {$EXTERNALSYM cuintptr_t} + cintptr_t = IntPtr; + {$EXTERNALSYM cintptr_t} + {$ELSE} + cuintptr_t = PtrUInt; + {$EXTERNALSYM cuintptr_t} + cintptr_t = PtrInt; + {$EXTERNALSYM cintptr_t} + {$ENDIF} + + {$IFDEF WANT_CWCHAR_T} + (* wchar_t is the "wide character" type of the C language. + * The size of this type is platform- and compiler-dependent. + * + * While FPC does have it's own "wide character" type, System.WideChar, + * that one is defined as always being 16-bits, so we can't re-use it here. + * + * When using FPC on Unices, the UnixType unit provides a wchar_t definition. + * + * On other systems/compiler combos, let's just go + * by what the CPP reference wiki claims, i.e: + * - wchar_t is 16-bits on Windows + * - wchar_t is 32-bits on Linux "and many other non-Windows systems" + * + * See: https://en.cppreference.com/w/cpp/language/types#Character_types + *) + {$IF DEFINED(FPC) AND DEFINED(UNIX)} + cwchar_t = UnixType.wchar_t; + {$ELSE} + {$IF DEFINED(WIN32) OR DEFINED(WIN64)} + cwchar_t = cuint16; + {$ELSE} + cwchar_t = cuint32; + {$ENDIF} + {$ENDIF} + {$EXTERNALSYM cwchar_t} + pcwchar_t = ^cwchar_t; + {$ENDIF} diff --git a/units/jedi.inc b/units/jedi.inc index 0f443fcb..0e305e70 100644 --- a/units/jedi.inc +++ b/units/jedi.inc @@ -1,22 +1,15 @@ { - Simple DirectMedia Layer - Copyright (C) 1997-2013 Sam Lantinga + This file (jedi.inc) is part of SDL2-for-Pascal. + It defines some variables for several Pascal-Compilers and OS-versions. - Pascal-Header-Conversion - Copyright (c) 2012/13 Tim Blume aka End + It is based upon: - sdl.inc is based on the files: - "begin_code.h", - "close_code.h", - "sdl_config.h", - "sdl_config_windows.h", - ... - it defines some variables for several Pascal-Compilers and OS-versions. + Pascal-Header-Conversion + Copyright (c) 2012/13 Tim Blume aka End - It is based on mine updated version of jedi-sdl.inc from the SDL 1.2 Headers, - they can be found at delphigl.com or on my github-repository: - - https://github.com/ev1313/ + jedi-sdl.inc: Global Conditional Definitions for JEDI-SDL cross-compilation + Copyright (C) 2000 - 2013 Prof. Abimbola Olowofoyeku and Tim Blume + See: https://github.com/ev1313/ This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -35,14 +28,6 @@ 3. This notice may not be removed or altered from any source distribution. } -{ - Changelog: - ---------- - v. 1.63-stable; 16.09.13: since GPC isn't supported anymore, i've deleted it from here, too. - v. 1.22-alpha; 24.07.13: fixed some bugs. special thanks to kotai from pascalgamedevelopment.com - v. 1.00-alpha; 05.07.13: Initial Alpha-Release -} - {.$define Debug} { uncomment for debugging } {$IFNDEF FPC} diff --git a/units/sdl.inc b/units/sdl.inc index 3a0e4b9f..0f0a1b31 100644 --- a/units/sdl.inc +++ b/units/sdl.inc @@ -1,6 +1,8 @@ // based on "sdl.h" type + PPSDL_Init = ^PSDL_Init; + PSDL_Init = ^TSDL_Init; TSDL_Init = type cuint32; const diff --git a/units/sdl2.pas b/units/sdl2.pas index d9b86f69..c6077030 100644 --- a/units/sdl2.pas +++ b/units/sdl2.pas @@ -1,70 +1,37 @@ unit sdl2; { + SDL2-for-Pascal + ================= + Pascal units for SDL2 - Simple Direct MediaLayer, Version 2 + + Copyright (C) 2020-2023 PGD Community + Maintainers: M. J. Molski and suve + Visit: https://github.com/PascalGameDevelopment/SDL2-for-Pascal + Simple DirectMedia Layer - Copyright (C) 1997-2013 Sam Lantinga - - Pascal-Header-Conversion - Copyright (C) 2012-2020 Tim Blume aka End/EV1313 - - SDL2-for-Pascal - Copyright (C) 2020-2021 PGD Community - - SDL.pas is based on the files: - "sdl.h", - "sdl_audio.h", - "sdl_blendmode.h", - "sdl_clipboard.h", - "sdl_cpuinfo.h", - "sdl_events.h", - "sdl_error.h", - "sdl_filesystem.h", - "sdl_gamecontroller.h", - "sdl_gesture.h", - "sdl_haptic.h", - "sdl_hints.h", - "sdl_joystick.h", - "sdl_keyboard.h", - "sdl_keycode.h", - "sdl_loadso.h", - "sdl_log.h", - "sdl_pixels.h", - "sdl_power.h", - "sdl_main.h", - "sdl_messagebox.h", - "sdl_mouse.h", - "sdl_mutex.h", - "sdl_rect.h", - "sdl_render.h", - "sdl_rwops.h", - "sdl_scancode.h", - "sdl_shape.h", - "sdl_stdinc.h", - "sdl_surface.h", - "sdl_system.h", - "sdl_syswm.h", - "sdl_thread.h", - "sdl_timer.h", - "sdl_touch.h", - "sdl_version.h", - "sdl_video.h" - - I will not translate: - "sdl_opengl.h", - "sdl_opengles.h" - "sdl_opengles2.h" + Copyright (C) 1997-2023 Sam Lantinga + Visit: http://libsdl.org + + SDL2-for-Pascal is based upon: - cause there's a much better OpenGL-Header avaible at delphigl.com: + Pascal-Header-Conversion + Copyright (C) 2012-2020 Tim Blume aka End/EV1313 - the dglopengl.pas + JEDI-SDL : Pascal units for SDL + Copyright (C) 2000 - 2004 Dominique Louis - You'll find it nowadays here: https://github.com/SaschaWillems/dglOpenGL + sdl2.pas is based on the C header files in the include folder + of the original Simple DirectMedia Layer repository. + See: https://github.com/libsdl-org/SDL - Parts of the SDL.pas are from the SDL-1.2-Headerconversion from the JEDI-Team, - written by Domenique Louis and others. + OpenGL header files are not translated: + "sdl_opengl.h", + "sdl_opengles.h" + "sdl_opengles2.h" - I've changed the names of the dll for 32 & 64-Bit, so theres no conflict - between 32 & 64 bit Libraries. + There is a much better OpenGL-Header avaible at delphigl.com: dglopengl.pas + See: https://github.com/SaschaWillems/dglOpenGL This software is provided 'as-is', without any express or implied warranty. In no case will the authors be held liable for any damages @@ -84,6 +51,7 @@ Special Thanks to: + - Tim Blume and everyone else contributing to the "Pascal-Header-Conversion" - DelphiGL.com - Community - Domenique Louis and everyone else from the JEDI-Team - Sam Latinga and everyone else from the SDL-Team @@ -107,6 +75,7 @@ interface uses {$IFDEF FPC} ctypes, + UnixType, {$ENDIF} {$IFDEF DARWIN} CocoaAll; @@ -116,6 +85,12 @@ interface {$ENDIF} {$ENDIF} + {$IF DEFINED(UNIX) AND DEFINED(ANDROID) AND DEFINED(FPC)} + uses + ctypes, + UnixType; + {$ENDIF} + const {$IFDEF WINDOWS} @@ -125,12 +100,16 @@ interface {$IFDEF UNIX} {$IFDEF DARWIN} SDL_LibName = 'libSDL2.dylib'; + {$IFDEF FPC} + {$LINKLIB libSDL2} + {$ENDIF} {$ELSE} {$IFDEF FPC} SDL_LibName = 'libSDL2.so'; {$ELSE} SDL_LibName = 'libSDL2.so.0'; {$ENDIF} + {$MESSAGE HINT 'Known MESA bug may generate float-point exception in software graphics mode! See https://github.com/PascalGameDevelopment/SDL2-for-Pascal/issues/56 for reference.'} {$ENDIF} {$ENDIF} @@ -142,50 +121,70 @@ interface {$ENDIF} +{$DEFINE WANT_CWCHAR_T} {$I ctypes.inc} // C data types {SDL2 version of the represented header file} {$I sdlstdinc.inc} {$I sdlversion.inc} // 2.0.14 -{$I sdlerror_c.inc} // 2.0.14 {$I sdlerror.inc} // 2.0.14 {$I sdlplatform.inc} // 2.0.14 {$I sdlpower.inc} // 2.0.14 -{$I sdlthread.inc} -{$I sdlmutex.inc} // 2.0.14 WIP +{$I sdlthread.inc} // 2.30.2 +{$I sdlatomic.inc} // 2.0.20 +{$I sdlmutex.inc} // 2.26.5 {$I sdltimer.inc} // 2.0.18 -{$I sdlpixels.inc} // 2.0.14 WIP -{$I sdlrect.inc} // 2.0.14 +{$I sdlpixels.inc} // 2.26.5 +{$I sdlrect.inc} // 2.24.0 {$I sdlrwops.inc} // 2.0.14 -{$I sdlaudio.inc} +{$I sdlaudio.inc} // 2.26.3 {$I sdlblendmode.inc} // 2.0.14 {$I sdlsurface.inc} // 2.0.14 -{$I sdlshape.inc} // 2.0.14 -{$I sdlvideo.inc} // 2.0.14 -{$I sdlhints.inc} // 2.0.20 -{$I sdlloadso.inc} +{$I sdlvideo.inc} // 2.28.0 +{$I sdlshape.inc} // 2.24.0 +{$I sdlhints.inc} // 2.26.0 +{$I sdlloadso.inc} // 2.24.1 {$I sdlmessagebox.inc} // 2.0.14 -{$I sdlrenderer.inc} -{$I sdlscancode.inc} -{$I sdlkeyboard.inc} -{$I sdlmouse.inc} -{$I sdljoystick.inc} -{$I sdlgamecontroller.inc} -{$I sdlhaptic.inc} -{$I sdltouch.inc} -{$I sdlgesture.inc} -{$I sdlsensor.inc} -{$I sdlsyswm.inc} -{$I sdlevents.inc} -{$I sdlclipboard.inc} -{$I sdlcpuinfo.inc} -{$I sdlfilesystem.inc} +{$I sdlrenderer.inc} // 2.0.22 +{$I sdlscancode.inc} // 2.26.2 +{$I sdlkeycode.inc} // 2.26.2 +{$I sdlkeyboard.inc} // 2.24.1 +{$I sdlmouse.inc} // 2.0.24 +{$I sdlguid.inc} // 2.24.0 +{$I sdljoystick.inc} // 2.24.0 +{$I sdlsensor.inc} // 2.26.0 +{$I sdlgamecontroller.inc} // 2.30.0 +{$I sdlhaptic.inc} // 2.26.2 +{$I sdlhidapi.inc} // 2.0.18 +{$I sdltouch.inc} // 2.24.0 +{$I sdlgesture.inc} // 2.26.2 +{$I sdlsyswm.inc} // 2.26.5 +{$I sdlevents.inc} // 2.24.0 +{$I sdllocale.inc} // 2.0.14 +{$I sdlclipboard.inc} // 2.24.1 +{$I sdlcpuinfo.inc} // 2.0.14 +{$I sdlfilesystem.inc} // 2.24.1 {$I sdllog.inc} // 2.0.14 -{$I sdlsystem.inc} +{$I sdlmisc.inc} // 2.0.14 +{$I sdlsystem.inc} // 2.24.0 {$I sdl.inc} // 2.0.14 implementation +(* + * We need an strlen() implementation for some operations on C-strings. + * FPC ships one in the Strings unit; Delphi has one in the AnsiStrings unit. + * Since FPC defines "DELPHI" when building in Delphi-compatibility mode, + * check if "FPC" is defined to determine which compiler is used. + *) +uses + {$IFDEF FPC} + Strings + {$ELSE} + AnsiStrings + {$ENDIF} + ; + // Macros from "sdl_version.h" procedure SDL_VERSION(out x: TSDL_Version); begin @@ -211,20 +210,29 @@ function SDL_VERSION_ATLEAST(X,Y,Z: cuint8): Boolean; Result := SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X,Y,Z); end; -//from "sdl_mouse.h" -function SDL_Button(button: cint32): cint32; +//Macros from "sdl_mouse.h" +function SDL_Button(X: cint): cint; begin - Result := 1 shl (button - 1); + Result := 1 shl (X - 1); end; {$IFDEF WINDOWS} //from "sdl_thread.h" -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; overload; +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; + data: Pointer): PSDL_Thread; overload; begin Result := SDL_CreateThread(fn,name,data,nil,nil); end; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; + name: PAnsiChar; const stacksize: csize_t; data: Pointer + ): PSDL_Thread; overload; +begin + Result := SDL_CreateThreadWithStackSize( + fn,name,stacksize,data,nil,nil); +end; + {$ENDIF} //from "sdl_rect.h" @@ -238,7 +246,7 @@ function SDL_PointInRect(const p: PSDL_Point; const r: PSDL_Rect): Boolean; function SDL_RectEmpty(const r: PSDL_Rect): Boolean; begin - Result := (r^.w <= 0) or (r^.h <= 0); + Result := (r = NIL) or (r^.w <= 0) or (r^.h <= 0); end; function SDL_RectEquals(const a, b: PSDL_Rect): Boolean; @@ -246,11 +254,74 @@ function SDL_RectEquals(const a, b: PSDL_Rect): Boolean; Result := (a^.x = b^.x) and (a^.y = b^.y) and (a^.w = b^.w) and (a^.h = b^.h); end; +function SDL_PointInFRect(const p: PSDL_FPoint; const r: PSDL_FRect): Boolean; +begin + Result := + (p^.x >= r^.x) and (p^.x < (r^.x + r^.w)) + and + (p^.y >= r^.y) and (p^.y < (r^.y + r^.h)) +end; + +function SDL_FRectEmpty(const r: PSDL_FRect): Boolean; +begin + Result := (r = NIL) or (r^.w <= cfloat(0.0)) or (r^.h <= cfloat(0.0)) +end; + +function SDL_FRectEqualsEpsilon(const a, b: PSDL_FRect; const epsilon: cfloat): Boolean; +begin + Result := + (a <> NIL) and + (b <> NIL) and + ( + (a = b) + or + ( + (SDL_fabsf(a^.x - b^.x) <= epsilon) + and + (SDL_fabsf(a^.y - b^.y) <= epsilon) + and + (SDL_fabsf(a^.w - b^.w) <= epsilon) + and + (SDL_fabsf(a^.h - b^.h) <= epsilon) + ) + ) +end; + +function SDL_FRectEquals(const a, b: PSDL_FRect): Boolean; Inline; +begin + Result := SDL_FRectEqualsEpsilon(a, b, SDL_FLT_EPSILON) +end; + +//from "sdl_atomic.h" +function SDL_AtomicIncRef(atomic: PSDL_Atomic): cint; +begin + Result := SDL_AtomicAdd(atomic, 1) +end; + +function SDL_AtomicDecRef(atomic: PSDL_Atomic): Boolean; +begin + Result := SDL_AtomicAdd(atomic, -1) = 1 +end; + +procedure SDL_CompilerBarrier(); +{$IFDEF FPC} +begin + ReadWriteBarrier() +{$ELSE} +var + lock: TSDL_SpinLock; +begin + lock := 0; + SDL_AtomicLock(@lock); + SDL_AtomicUnlock(@lock) +{$ENDIF} +end; + //from "sdl_audio.h" -function SDL_LoadWAV(_file: PAnsiChar; spec: PSDL_AudioSpec; audio_buf: ppcuint8; audio_len: pcuint32): PSDL_AudioSpec; +function SDL_LoadWAV(file_: PAnsiChar; spec: PSDL_AudioSpec; audio_buf: ppcuint8; audio_len: pcuint32): PSDL_AudioSpec; begin - Result := SDL_LoadWAV_RW(SDL_RWFromFile(_file, 'rb'), 1, spec, audio_buf, audio_len); + Result := SDL_LoadWAV_RW(SDL_RWFromFile(file_, 'rb'), 1, spec, audio_buf, audio_len); end; function SDL_AUDIO_BITSIZE(x: Cardinal): Cardinal; @@ -280,7 +351,7 @@ function SDL_AUDIO_ISINT(x: Cardinal): Cardinal; function SDL_AUDIO_ISLITTLEENDIAN(x: Cardinal): Cardinal; begin - Result := not SDL_AUDIO_ISLITTLEENDIAN(x); + Result := not SDL_AUDIO_ISBIGENDIAN(x); end; function SDL_AUDIO_ISUNSIGNED(x: Cardinal): Cardinal; @@ -290,27 +361,27 @@ function SDL_AUDIO_ISUNSIGNED(x: Cardinal): Cardinal; //from "sdl_pixels.h" -function SDL_PIXELFLAG(X: Cardinal): Cardinal; +function SDL_PIXELFLAG(X: cuint32): cuint32; begin Result := (X shr 28) and $0F; end; -function SDL_PIXELTYPE(X: Cardinal): Cardinal; +function SDL_PIXELTYPE(X: cuint32): cuint32; begin Result := (X shr 24) and $0F; end; -function SDL_PIXELORDER(X: Cardinal): Cardinal; +function SDL_PIXELORDER(X: cuint32): cuint32; begin Result := (X shr 20) and $0F; end; -function SDL_PIXELLAYOUT(X: Cardinal): Cardinal; +function SDL_PIXELLAYOUT(X: cuint32): cuint32; begin Result := (X shr 16) and $0F; end; -function SDL_BITSPERPIXEL(X: Cardinal): Cardinal; +function SDL_BITSPERPIXEL(X: cuint32): cuint32; begin Result := (X shr 8) and $FF; end; @@ -346,11 +417,22 @@ function SDL_SHAPEMODEALPHA(mode: TWindowShapeMode): Boolean; Result := (mode = ShapeModeDefault) or (mode = ShapeModeBinarizeAlpha) or (mode = ShapeModeReverseBinarizeAlpha); end; -//from "sdl_sysvideo.h" +// from "sdl_stdinc.h" + +// Note: We're using FPC's Strings.strlen() here, not SDL_strlen(). +function SDL_iconv_utf8_locale(Const str: PAnsiChar): PAnsiChar; cdecl; +begin + Result := SDL_iconv_string('', 'UTF-8', str, strlen(str)+1) +end; + +function SDL_iconv_utf8_ucs2(Const str: PAnsiChar): pcUint16; cdecl; +begin + Result := pcUint16(SDL_iconv_string('UCS-2-INTERNAL', 'UTF-8', str, strlen(str)+1)) +end; -function FULLSCREEN_VISIBLE(W: PSDL_Window): Variant; +function SDL_iconv_utf8_ucs4(Const str: PAnsiChar): pcUint32; cdecl; begin - Result := ((W^.flags and SDL_WINDOW_FULLSCREEN) and (W^.flags and SDL_WINDOW_SHOWN) and not (W^.flags and SDL_WINDOW_MINIMIZED)); + Result := pcUint32(SDL_iconv_string('UCS-4-INTERNAL', 'UTF-8', str, strlen(str)+1)) end; //from "sdl_video.h" diff --git a/units/sdl2_gfx.pas b/units/sdl2_gfx.pas index 7bc7591a..b5592470 100644 --- a/units/sdl2_gfx.pas +++ b/units/sdl2_gfx.pas @@ -107,19 +107,19 @@ TFPSManager = record PFPSManager = ^TFPSManager; -Procedure SDL_initFramerate(manager: PFPSManager); +Procedure SDL_initFramerate(manager: PFPSManager); cdecl; external GFX_LibName {$IFDEF DELMAC} name '_SDL_initFramerate' {$ENDIF}; -Function SDL_setFramerate(manager: PFPSManager; rate: cuint32):cint32; +Function SDL_setFramerate(manager: PFPSManager; rate: cuint32):cint32; cdecl; external GFX_LibName {$IFDEF DELMAC} name '_SDL_setFramerate' {$ENDIF}; -Function SDL_getFramerate(manager: PFPSManager):cint32; +Function SDL_getFramerate(manager: PFPSManager):cint32; cdecl; external GFX_LibName {$IFDEF DELMAC} name '_SDL_getFramerate' {$ENDIF}; -Function SDL_getFramecount(manager: PFPSManager):cint32; +Function SDL_getFramecount(manager: PFPSManager):cint32; cdecl; external GFX_LibName {$IFDEF DELMAC} name '_SDL_getFramecount' {$ENDIF}; -Function SDL_framerateDelay(manager: PFPSManager):cuint32; +Function SDL_framerateDelay(manager: PFPSManager):cuint32; cdecl; external GFX_LibName {$IFDEF DELMAC} name '_SDL_framerateDelay' {$ENDIF}; diff --git a/units/sdl2_image.pas b/units/sdl2_image.pas index ffbb7a49..f102a032 100644 --- a/units/sdl2_image.pas +++ b/units/sdl2_image.pas @@ -90,6 +90,8 @@ function IMG_Linked_Version: PSDL_Version cdecl; external IMG_LibName {$IFDEF DE IMG_INIT_WEBP = $00000008; type + PPIMG_InitFlags = ^PIMG_InitFlags; + PIMG_InitFlags = ^TIMG_InitFlags; TIMG_InitFlags = DWord; {* Loads dynamic libraries and prepares them for use. Flags should be @@ -167,8 +169,12 @@ function IMG_SaveJPG_RW(surface: PSDL_Surface; dst: PSDL_RWops; freedst: cint32; external IMG_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_IMG_SaveJPG_RW' {$ENDIF} {$ENDIF}; {* We'll use SDL for reporting errors *} -function IMG_SetError(fmt: PAnsiChar): cint32; cdecl; +function IMG_SetError(fmt: PAnsiChar; args: array of const): cint; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_SetError' {$ELSE} 'SDL_SetError' {$ENDIF}; function IMG_GetError: PAnsiChar; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_GetError' {$ELSE} 'SDL_GetError' {$ENDIF}; implementation @@ -179,14 +185,4 @@ procedure SDL_IMAGE_VERSION(Out X: TSDL_Version); X.patch := SDL_IMAGE_PATCHLEVEL; end; -function IMG_SetError(fmt: PAnsiChar): cint32; cdecl; -begin - Result := SDL_SetError(fmt); -end; - -function IMG_GetError: PAnsiChar; cdecl; -begin - Result := SDL_GetError(); -end; - end. diff --git a/units/sdl2_mixer.pas b/units/sdl2_mixer.pas index 79f390d3..c29d4a90 100644 --- a/units/sdl2_mixer.pas +++ b/units/sdl2_mixer.pas @@ -60,8 +60,8 @@ interface {* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL *} const SDL_MIXER_MAJOR_VERSION = 2; - SDL_MIXER_MINOR_VERSION = 0; - SDL_MIXER_PATCHLEVEL = 4; + SDL_MIXER_MINOR_VERSION = 8; + SDL_MIXER_PATCHLEVEL = 1; {* This macro can be used to fill a version structure with the compile-time * version of the SDL_mixer library. @@ -82,26 +82,29 @@ procedure MIX_VERSION(Out X: TSDL_Version); *} function Mix_Linked_Version: PSDL_Version cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Linked_Version' {$ENDIF} {$ENDIF}; -const - MIX_INIT_FLAC = $00000001; - MIX_INIT_MOD = $00000002; - MIX_INIT_MP3 = $00000008; - MIX_INIT_OGG = $00000010; - MIX_INIT_MID = $00000020; - MIX_INIT_OPUS = $00000040; - -{ // Removed in SDL2_mixer 2.0.2 - MIX_INIT_MODPLUG = $00000004; - MIX_INIT_FLUIDSYNTH = $00000020; -} type - TMIX_InitFlags = cint; + PPMix_InitFlags = ^PMix_InitFlags; + PMix_InitFlags = ^TMix_InitFlags; + TMix_InitFlags = type cint; + +const + MIX_INIT_FLAC = TMix_InitFlags($00000001); + MIX_INIT_MOD = TMix_InitFlags($00000002); + MIX_INIT_MP3 = TMix_InitFlags($00000008); + MIX_INIT_OGG = TMix_InitFlags($00000010); + MIX_INIT_MID = TMix_InitFlags($00000020); + MIX_INIT_OPUS = TMix_InitFlags($00000040); + MIX_INIT_WAVPACK = TMix_InitFlags($00000080); + +// Removed in SDL2_mixer 2.0.2: +// MIX_INIT_MODPLUG = TMix_InitFlags($00000004); +// MIX_INIT_FLUIDSYNTH = TMix_InitFlags($00000020); {* Loads dynamic libraries and prepares them for use. Flags should be one or more flags from MIX_InitFlags OR'd together. It returns the flags successfully initialized, or 0 on failure. *} -function Mix_Init(flags: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Init' {$ENDIF} {$ENDIF}; +function Mix_Init(flags: TMix_InitFlags): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Init' {$ENDIF} {$ENDIF}; {* Unloads libraries loaded with Mix_Init *} procedure Mix_Quit() cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Quit' {$ENDIF} {$ENDIF}; @@ -115,22 +118,18 @@ procedure Mix_Quit() cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} {* Good default values for a PC soundcard *} const - MIX_DEFAULT_FREQUENCY = 22050; + MIX_DEFAULT_FREQUENCY = 44100; MIX_DEFAULT_CHANNELS = 2; MIX_MAX_VOLUME = SDL2.SDL_MIX_MAXVOLUME; {* Volume of a chunk *} {$IFDEF FPC} - {$IF DEFINED(ENDIAN_LITTLE)} - MIX_DEFAULT_FORMAT = AUDIO_S16LSB; - {$ELSEIF DEFINED(ENDIAN_BIG)} - MIX_DEFAULT_FORMAT = AUDIO_S16MSB; - {$ELSE} - {$FATAL Unable to determine endianness.} - {$IFEND} + // This is hidden behind IFDEF because AUDIO_S16SYS is also hidden. + MIX_DEFAULT_FORMAT = SDL2.AUDIO_S16SYS; {$ENDIF} {* The internal format for an audio chunk *} type + PPMix_Chunk = ^PMix_Chunk; PMix_Chunk = ^TMix_Chunk; TMix_Chunk = record allocated: cint; @@ -141,29 +140,51 @@ TMix_Chunk = record {* The different fading types supported *} type - TMix_Fading = (MIX_NO_FADING, MIX_FADING_OUT, MIX_FADING_IN); - - TMix_MusicType = ( - MUS_NONE, - MUS_CMD, - MUS_WAV, - MUS_MOD, - MUS_MID, - MUS_OGG, - MUS_MP3, - MUS_MP3_MAD_UNUSED, - MUS_FLAC, - MUS_MODPLUG_UNUSED, - MUS_OPUS - ); + PPMix_Fading = ^PMix_Fading; + PMix_Fading = ^TMix_Fading; + TMix_Fading = type cint; + +const + MIX_NO_FADING = TMix_Fading(0); + MIX_FADING_OUT = TMix_Fading(1); + MIX_FADING_IN = TMix_Fading(2); + +type + PPMix_MusicType = ^PMix_MusicType; + PMix_MusicType = ^TMix_MusicType; + TMix_MusicType = type cint; +const + MUS_NONE = TMix_MusicType(0); + MUS_CMD = TMix_MusicType(1); + MUS_WAV = TMix_MusicType(2); + MUS_MOD = TMix_MusicType(3); + MUS_MID = TMix_MusicType(4); + MUS_OGG = TMix_MusicType(5); + MUS_MP3 = TMix_MusicType(6); + MUS_MP3_MAD_UNUSED = TMix_MusicType(7); + MUS_FLAC = TMix_MusicType(8); + MUS_MODPLUG_UNUSED = TMix_MusicType(9); + MUS_OPUS = TMix_MusicType(10); + MUS_WAVPACK = TMix_MusicType(11); + MUS_GM = TMix_MusicType(12); + +type {* The internal format for a music chunk interpreted via mikmod *} - PMix_Music = ^TMix_Music; - TMix_Music = record end; + PPMix_Music = ^PMix_Music; + PMix_Music = type Pointer; {* Open the mixer with a certain audio format *} function Mix_OpenAudio(frequency: cint; format: cuint16; channels: cint; chunksize: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_OpenAudio' {$ENDIF} {$ENDIF}; + { * Open a specific audio device for playback. *} +function Mix_OpenAudioDevice(frequency: cint; format: cuint16; channels: cint; chunksize: cint; device: PAnsiChar; allowed_changes: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_OpenAudioDevice' {$ENDIF} {$ENDIF}; + + {* Pause (1) or resume (0) the whole audio output. *} +procedure Mix_PauseAudio(pause_on: cint); cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PauseAudio' {$ENDIF} {$ENDIF}; + {* Dynamically change the number of channels managed by the mixer. If decreasing the number of channels, the upper channels are stopped. @@ -178,7 +199,7 @@ function Mix_QuerySpec(frequency: pcint; format: pcuint16; channels: pcint): cin {* Load a wave file or a music (.mod .s3m .it .xm) file *} function Mix_LoadWAV_RW(src: PSDL_RWops; freesrc: cint): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadWAV_RW' {$ENDIF} {$ENDIF}; -function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk; +function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadWAV' {$ENDIF} {$ENDIF}; function Mix_LoadMUS(_file: PAnsiChar): PMix_Music cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadMUS' {$ENDIF} {$ENDIF}; {* Load a music file from an SDL_RWop object (Ogg and MikMod specific currently) @@ -233,13 +254,67 @@ function Mix_HasMusicDecoder(const name: PAnsiChar): TSDL_Bool cdecl; {* Find out the music format of a mixer music, or the currently playing music, if 'music' is NULL. *} -function Mix_GetMusicType(music: TMix_Music): TMix_MusicType cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicType' {$ENDIF} {$ENDIF}; +function Mix_GetMusicType(music: PMix_Music): TMix_MusicType cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicType' {$ENDIF} {$ENDIF}; + + {* Get the title for a music object, or its filename. + This returns format-specific metadata. Not all formats support this! + + If `music` is NULL, this will query the currently-playing music. + + If the music's title tag is missing or empty, the filename will be returned instead. + + This function never returns NIL! If no data is available, it will return an empty string. + *} +function Mix_GetMusicTitle(music: PMix_Music): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicTitle' {$ENDIF} {$ENDIF}; + + {* Get the title for a music object. + This returns format-specific metadata. Not all formats support this! + + If `music` is NULL, this will query the currently-playing music. + + This function never returns NIL! If no data is available, it will return an empty string. + *} +function Mix_GetMusicTitleTag(music: PMix_Music): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicTitleTag' {$ENDIF} {$ENDIF}; + + {* Get the artist name for a music object. + This returns format-specific metadata. Not all formats support this! + + If `music` is NULL, this will query the currently-playing music. + + This function never returns NIL! If no data is available, it will return an empty string. + *} +function Mix_GetMusicArtistTag(music: PMix_Music): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicArtistTag' {$ENDIF} {$ENDIF}; + + {* Get the album name for a music object. + This returns format-specific metadata. Not all formats support this! + + If `music` is NULL, this will query the currently-playing music. + + This function never returns NIL! If no data is available, it will return an empty string. + *} +function Mix_GetMusicAlbumTag(music: PMix_Music): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicAlbumTag' {$ENDIF} {$ENDIF}; + + {* Get the copyright text for a music object. + This returns format-specific metadata. Not all formats support this! + + If `music` is NULL, this will query the currently-playing music. + + This function never returns NIL! If no data is available, it will return an empty string. + *} +function Mix_GetMusicCopyrightTag(music: PMix_Music): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicCopyrightTag' {$ENDIF} {$ENDIF}; {* Set a function that is called after all mixing is performed. This can be used to provide real-time visual display of the audio stream or add a custom mixer filter for the stream data. *} type + PPMix_Func = ^PMix_Func; + PMix_Func = ^TMix_Func; TMix_Func = procedure(udata: Pointer; stream: pcuint8; len: cint) cdecl; procedure Mix_SetPostMix(func: TMix_Func; arg: Pointer) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetPostMix' {$ENDIF} {$ENDIF}; @@ -253,6 +328,7 @@ procedure Mix_HookMusic(func: TMix_Func; arg: Pointer) cdecl; external MIX_LibNa * or when it is stopped from a call to Mix_HaltMusic. *} type + PPMix_Music_Finished = ^PMix_Music_Finished; PMix_Music_Finished = ^TMix_Music_Finished; TMix_Music_Finished = procedure() cdecl; @@ -270,6 +346,8 @@ function Mix_GetMusicHookData: Pointer cdecl; external MIX_LibName {$IFDEF DELPH * before calling your callback. *} type + PPMix_Channel_Finished = ^PMix_Channel_Finished; + PMix_Channel_Finished = ^TMix_Channel_Finished; TMix_Channel_Finished = procedure(channel: cint) cdecl; procedure Mix_ChannelFinished(channel_finished: TMix_Channel_Finished) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ChannelFinished' {$ENDIF} {$ENDIF}; @@ -296,6 +374,8 @@ procedure Mix_ChannelFinished(channel_finished: TMix_Channel_Finished) cdecl; ex * DO NOT EVER call SDL_LockAudio() from your callback function! *} type + PPMix_EffectFunc_t = ^PMix_EffectFunc_t; + PMix_EffectFunc_t = ^TMix_EffectFunc_t; TMix_EffectFunc_t = procedure(chan: cint; stream: Pointer; len: cint; udata: Pointer) cdecl; {* @@ -308,6 +388,8 @@ procedure Mix_ChannelFinished(channel_finished: TMix_Channel_Finished) cdecl; ex * DO NOT EVER call SDL_LockAudio() from your callback function! *} type + PPMix_EffectDone_t = ^PMix_EffectDone_t; + PMix_EffectDone_t = ^TMix_EffectDone_t; TMix_EffectDone_t = procedure(chan: cint; udata: Pointer) cdecl; {* Register a special effect function. At mixing time, the channel data is @@ -572,15 +654,17 @@ function Mix_GroupNewer(tag: cint): cint cdecl; external MIX_LibName {$IFDEF DEL If 'loops' is -1, loop inifinitely (~65000 times). Returns which channel was used to play the sound. *} -function Mix_PlayChannel(channel: cint; chunk: PMix_Chunk; loops: cint): cint; +function Mix_PlayChannel(channel: cint; chunk: PMix_Chunk; loops: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayChannel' {$ENDIF} {$ENDIF}; {* The same as above, but the sound is played at most 'ticks' milliseconds *} function Mix_PlayChannelTimed(channel: cint; chunk: PMix_Chunk; loops: cint; ticks: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayChannelTimed' {$ENDIF} {$ENDIF}; function Mix_PlayMusic(music: PMix_Music; loops: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayMusic' {$ENDIF} {$ENDIF}; {* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions *} function Mix_FadeInMusic(music: PMix_Music; loops: cint; ms: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInMusic' {$ENDIF} {$ENDIF}; -function Mix_FadeInMusicPos(music: PMix_Music; loops: cint; ms: cint; position: Double): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInMusicPos' {$ENDIF} {$ENDIF}; -function Mix_FadeInChannel(channel: cint; chunk: PMix_Chunk; loops: cint; ms: cint): cint; +function Mix_FadeInMusicPos(music: PMix_Music; loops: cint; ms: cint; position: cdouble): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInMusicPos' {$ENDIF} {$ENDIF}; +function Mix_FadeInChannel(channel: cint; chunk: PMix_Chunk; loops: cint; ms: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInChannel' {$ENDIF} {$ENDIF}; function Mix_FadeInChannelTimed(channel: cint; chunk: PMix_Chunk; loops: cint; ms: cint; ticks: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInChannelTimed' {$ENDIF} {$ENDIF}; {* Set the volume in the range of 0-128 of a specific channel or chunk. @@ -592,6 +676,23 @@ function Mix_Volume(channel: cint; volume: cint): cint cdecl; external MIX_LibNa function Mix_VolumeChunk(chunk: PMix_Chunk; volume: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_VolumeChunk' {$ENDIF} {$ENDIF}; function Mix_VolumeMusic(volume: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_VolumeMusic' {$ENDIF} {$ENDIF}; + {* Query the current volume for a music object. *} +function Mix_GetMusicVolume(music: PMix_Music): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicVolume' {$ENDIF} {$ENDIF}; + + {* Set the master volume for all channels. + + SDL_Mixer keeps a per-channel volume, a per-chunk volume, and a master volume. + All three are considered when mixing audio. + + Note that the master volume does not affect any playing music; + it is only applied when mixing chunks. Use Mix_VolumeMusic() for that. + + If the specified volume is -1, this returns the current volume. + *} +function Mix_MasterVolume(volume: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_MasterVolume' {$ENDIF} {$ENDIF}; + {* Halt playing of a particular channel *} function Mix_HaltChannel(channel: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HaltChannel' {$ENDIF} {$ENDIF}; function Mix_HaltGroup(tag: cint): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HaltGroup' {$ENDIF} {$ENDIF}; @@ -626,13 +727,59 @@ procedure Mix_ResumeMusic cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MA procedure Mix_RewindMusic cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_RewindMusic' {$ENDIF} {$ENDIF}; function Mix_PausedMusic: cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PausedMusic' {$ENDIF} {$ENDIF}; + {* Jump to a given order in MOD music. *} +function Mix_ModMusicJumpToOrder(order: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ModMusicJumpToOrder' {$ENDIF} {$ENDIF}; + + {* Set a track in a GME music object. *} +function Mix_StartTrack(music: PMix_Music; track: cint): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_StartTrack' {$ENDIF} {$ENDIF}; + + {* Get number of tracks in a GME music object. *} +function Mix_GetNumTracks(music: PMix_Music): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetNumTracks' {$ENDIF} {$ENDIF}; + {* Set the current position in the music stream. This returns 0 if successful, or -1 if it failed or isn't implemented. This function is only implemented for MOD music formats (set pattern order number) and for OGG, FLAC, MP3_MAD, MP3_MPG and MODPLUG music (set position in seconds), at the moment. *} -function Mix_SetMusicPosition(position: Double): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetMusicPosition' {$ENDIF} {$ENDIF}; +function Mix_SetMusicPosition(position: cdouble): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetMusicPosition' {$ENDIF} {$ENDIF}; + + {* Get the current position of a music stream, in seconds. + Returns -1.0 if this feature is not supported for some codec. + *} +function Mix_GetMusicPosition(music: PMix_Music): cdouble; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicPosition' {$ENDIF} {$ENDIF}; + + {* Get a music object's duration, in seconds. + If NIL is passed, returns duration of currently playing music. + Returns -1.0 on error. + *} +function Mix_MusicDuration(music: PMix_Music): cdouble; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_MusicDuration' {$ENDIF} {$ENDIF}; + + {* Get the loop start time position of a music stream, in seconds. + Returns -1.0 if this feature is not used by this music + or unsupported by the codec. + *} +function Mix_GetMusicLoopStartTime(music: PMix_Music): cdouble; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicLoopStartTime' {$ENDIF} {$ENDIF}; + + {* Get the loop end time position of a music stream, in seconds. + Returns -1.0 if this feature is not used by this music + or unsupported by the codec. + *} +function Mix_GetMusicLoopEndTime(music: PMix_Music): cdouble; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicLoopEndTime' {$ENDIF} {$ENDIF}; + + {* Get the loop time length of a music stream, in seconds. + Returns -1.0 if this feature is not used by this music + or unsupported by the codec. + *} +function Mix_GetMusicLoopLengthTime(music: PMix_Music): cdouble; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicLoopLengthTime' {$ENDIF} {$ENDIF}; {* Check the status of a specific channel. If the specified channel is -1, check all channels. @@ -652,10 +799,27 @@ function Mix_SetSoundFonts(paths: PAnsiChar): cint cdecl; external MIX_LibName { function Mix_GetSoundFonts: PAnsiChar cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetSoundFonts' {$ENDIF} {$ENDIF}; type + PPMix_SoundFunc = ^PMix_SoundFunc; + PMix_SoundFunc = ^TMix_SoundFunc; TMix_SoundFunc = function(c: PAnsiChar; p: Pointer): cint cdecl; function Mix_EachSoundFont(func: TMix_SoundFunc; data: Pointer): cint cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_EachSoundFont' {$ENDIF} {$ENDIF}; + {* Set full path of the Timidity config file. + This is only useful if SDL_Mixer is using Timidity to play MIDI files. + *} +function Mix_SetTimidityCfg(path: PAnsiChar): cint; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetTimidityCfg' {$ENDIF} {$ENDIF}; + + {* Get full path of previously specified Timidity config file. + If a path has never been specified, this returns NIL. + + This returns a pointer to internal memory; + it must not be modified nor freed by the caller. + *} +function Mix_GetTimidityCfg(): PAnsiChar; cdecl; + external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetTimidityCfg' {$ENDIF} {$ENDIF}; + {* Get the Mix_Chunk currently associated with a mixer channel Returns NULL if it's an invalid channel, or there's no chunk associated. *} @@ -665,9 +829,15 @@ function Mix_GetChunk(channel: cint): PMix_Chunk cdecl; external MIX_LibName {$I procedure Mix_CloseAudio cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_CloseAudio' {$ENDIF} {$ENDIF}; {* We'll use SDL for reporting errors *} -function Mix_SetError(const fmt: PAnsiChar): cint32; cdecl; +function Mix_SetError(const fmt: PAnsiChar; args: array of const): cint; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_SetError' {$ELSE} 'SDL_SetError' {$ENDIF}; function Mix_GetError: PAnsiChar; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_GetError' {$ELSE} 'SDL_GetError' {$ENDIF}; procedure Mix_ClearError(); cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_ClearError' {$ELSE} 'SDL_ClearError' {$ENDIF}; implementation @@ -683,34 +853,4 @@ procedure MIX_VERSION(Out X: TSDL_Version); SDL_MIXER_VERSION(X); end; -function Mix_FadeInChannel(channel: cint; chunk: PMix_Chunk; loops: cint; ms: cint): cint; -begin - Result := Mix_FadeInChannelTimed(channel, chunk, loops, ms, -1); -end; - -function Mix_PlayChannel(channel: cint; chunk: PMix_Chunk; loops: cint): cint; -begin - Result := Mix_PlayChannelTimed(channel, chunk, loops, -1); -end; - -function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk; -begin - Result := Mix_LoadWAV_RW(SDL_RWFromFile(_file, 'rb'), 1); -end; - -function Mix_SetError(const fmt: PAnsiChar): cint32; cdecl; -begin - Result := SDL_SetError(fmt); -end; - -function Mix_GetError: PAnsiChar; cdecl; -begin - Result := SDL_GetError(); -end; - -procedure Mix_ClearError; cdecl; -begin - SDL_ClearError() -end; - end. diff --git a/units/sdl2_net.pas b/units/sdl2_net.pas index 2fb158e3..aa00627e 100644 --- a/units/sdl2_net.pas +++ b/units/sdl2_net.pas @@ -59,7 +59,9 @@ interface type - TSDLNet_Version = TSDL_Version; + PPSDLNet_Version = ^PSDLNet_Version; + PSDLNet_Version = ^TSDLNet_Version; + TSDLNet_Version = TSDL_Version; const {* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL *} @@ -89,11 +91,12 @@ procedure SDLNet_Quit() cdecl; external SDLNet_LibName {$IFDEF DELPHI} {$IFDEF M {***********************************************************************} {* IPv4 hostname resolution API *} {***********************************************************************} + PPIPaddress = ^PIPaddress; + PIPaddress = ^TIPaddress; TIPaddress = record host: cuint32; {* 32-bit IPv4 host address *} port: cuint16; {* 16-bit protocol port *} end; - PIPaddress = ^TIPaddress; {* Resolve a host name and port to an IP address in network form. If the function succeeds, it will return 0. @@ -178,10 +181,13 @@ procedure SDLNet_TCP_Close(sock: TTCPSocket) cdecl; external SDLNet_LibName {$IF SDLNET_MAX_UDPADDRESSES = 4; type + PPUDPSocket = ^PUDPSocket; + PUDPSocket = ^TUDPSocket; TUDPSocket = record end; - PUDPSocket = ^TUDPSocket; + PPUDPPacket = ^PUDPPacket; + PUDPPacket = ^TUDPPacket; TUDPPacket = record channel: cint; {* The src/dst channel of the packet *} data: pcuint8; {* The packet data *} @@ -190,8 +196,6 @@ TUDPPacket = record status: cint; {* packet status after sending *} address: TIPaddress; {* The source/dest address of an incoming/outgoing packet *} end; - PUDPPacket = ^TUDPPacket; - PPUDPPacket = ^PUDPPacket; {* Allocate/resize/free a single UDP packet 'size' bytes long. The new packet is returned, or NULL if the function ran out of memory. @@ -297,15 +301,17 @@ procedure SDLNet_UDP_Close(sock: TUDPSocket) cdecl; external SDLNet_LibName {$IF {***********************************************************************} type + PPSDLNet_SocketSet = ^PSDLNet_SocketSet; + PSDLNet_SocketSet = ^TSDLNet_SocketSet; TSDLNet_SocketSet = record end; - PSDLNet_SocketSet = ^TSDLNet_SocketSet; {* Any network socket can be safely cast to this socket type *} + PPSDLNet_GenericSocket = ^PSDLNet_GenericSocket; + PSDLNet_GenericSocket = ^TSDLNet_GenericSocket; TSDLNet_GenericSocket = record ready: cint; end; - PSDLNet_GenericSocket = ^TSDLNet_GenericSocket; {* Allocate a socket set for use with SDLNet_CheckSockets() This returns a socket set for up to 'maxsockets' sockets, or NULL if @@ -345,8 +351,11 @@ procedure SDLNet_FreeSocketSet(set_: TSDLNet_SocketSet) cdecl; external SDLNet_L {* Error reporting functions *} {***********************************************************************} -procedure SDLNet_SetError(const fmt: PAnsiChar); cdecl; +procedure SDLNet_SetError(const fmt: PAnsiChar; args: array of const); cdecl; +external SDLNet_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDLNet_SetError' {$ENDIF} {$ENDIF}; + function SDLNet_GetError(): PAnsiChar; cdecl; +external SDLNet_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDLNet_GetError' {$ENDIF} {$ENDIF}; {***********************************************************************} {* Inline functions to read/write network data *} @@ -397,16 +406,6 @@ function SDLNet_SocketReady(sock: TSDLNet_GenericSocket): cint; Result := sock.ready; end; -procedure SDLNet_SetError(const fmt: PAnsiChar); cdecl; -begin - SDL_SetError(fmt); -end; - -function SDLNet_GetError(): PAnsiChar; cdecl; -begin - Result := SDL_GetError(); -end; - (* procedure SDLNet_Write16(value: cuint16; areap: Pointer); begin diff --git a/units/sdl2_ttf.pas b/units/sdl2_ttf.pas index 3b4c1895..48c0039b 100644 --- a/units/sdl2_ttf.pas +++ b/units/sdl2_ttf.pas @@ -21,10 +21,19 @@ 3. This notice may not be removed or altered from any source distribution. *} -{* This library is a wrapper around the excellent FreeType 2.0 library, - available at: - http://www.freetype.org/ -*} +{* + * \file SDL_ttf.h + * + * Header file for SDL_ttf library + * + * This library is a wrapper around the excellent FreeType 2.0 library, + * available at: https://www.freetype.org/ + * + * Note: In many places, SDL_ttf will say "glyph" when it means "code point." + * Unicode is hard, we learn as we go, and we apologize for adding to the + * confusion. + * + } interface @@ -62,57 +71,389 @@ interface {$ENDIF} {$ENDIF} -{* Set up for C function definitions, even when using C++ *} - {* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL *} const SDL_TTF_MAJOR_VERSION = 2; - SDL_TTF_MINOR_VERSION = 0; - SDL_TTF_PATCHLEVEL = 15; + SDL_TTF_MINOR_VERSION = 24; + SDL_TTF_PATCHLEVEL = 0; -Procedure SDL_TTF_VERSION(Out X:TSDL_Version); +procedure SDL_TTF_VERSION(Out X: TSDL_Version); {* Backwards compatibility *} const TTF_MAJOR_VERSION = SDL_TTF_MAJOR_VERSION; TTF_MINOR_VERSION = SDL_TTF_MINOR_VERSION; TTF_PATCHLEVEL = SDL_TTF_PATCHLEVEL; +procedure TTF_VERSION(Out X: TSDL_Version); - {* This function gets the version of the dynamically linked SDL_ttf library. - it should NOT be used to fill a version structure, instead you should - use the SDL_TTF_VERSION() macro. +{** + * This is the version number macro for the current SDL_ttf version. + * + * In versions higher than 2.9.0, the minor version overflows into + * the thousands digit: for example, 2.23.0 is encoded as 4300. + * This macro will not be available in SDL 3.x or SDL_ttf 3.x. + * + * \deprecated, use SDL_TTF_VERSION_ATLEAST or SDL_TTF_VERSION instead. *} -function TTF_Linked_Version: PSDL_Version cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Linked_Version' {$ENDIF} {$ENDIF}; + { SDL2-for-Pascal: This conditional and deprecated macro is not translated. + It could be done easily but nobody ever asked for it and + it is probably for little use. } +// function SDL_TTF_COMPILEDVERSION: Integer; + +{** + * This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z. + *} +function SDL_TTF_VERSION_ATLEAST(X, Y, Z: Integer): Boolean; + +{* + * Query the version of SDL_ttf that the program is linked against. + * + * This function gets the version of the dynamically linked SDL_ttf library. + * This is separate from the SDL_TTF_VERSION() macro, which tells you what + * version of the SDL_ttf headers you compiled against. + * + * This returns static internal data; do not free or modify it! + * + * \returns a pointer to the version information. + * + * \since This function is available since SDL_ttf 2.0.12. + } +(* Const before type ignored *) +function TTF_Linked_Version: PSDL_version; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Linked_Version' {$ENDIF} {$ENDIF}; -{* ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) *} +{* + * Query the version of the FreeType library in use. + * + * TTF_Init() should be called before calling this function. + * + * \param major to be filled in with the major version number. Can be nil. + * \param minor to be filled in with the minor version number. Can be nil. + * \param patch to be filled in with the param version number. Can be nil. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_Init + } +procedure TTF_GetFreeTypeVersion(major: pcint; minor: pcint; patch: pcint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFreeTypeVersion' {$ENDIF} {$ENDIF}; + +{* + * Query the version of the HarfBuzz library in use. + * + * If HarfBuzz is not available, the version reported is 0.0.0. + * + * \param major to be filled in with the major version number. Can be nil. + * \param minor to be filled in with the minor version number. Can be nil. + * \param patch to be filled in with the param version number. Can be nil. + * + * \since This function is available since SDL_ttf 2.0.18. + } +procedure TTF_GetHarfBuzzVersion(major: pcint; minor: pcint; patch: pcint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetHarfBuzzVersion' {$ENDIF} {$ENDIF}; + +{* + * ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) + } const UNICODE_BOM_NATIVE = $FEFF; UNICODE_BOM_SWAPPED = $FFFE; -{* This function tells the library whether UNICODE text is generally - byteswapped. A UNICODE BOM character in a string will override - this setting for the remainder of that string. -*} -procedure TTF_ByteSwappedUNICODE(swapped: cint) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_ByteSwappedUNICODE' {$ENDIF} {$ENDIF}; +{* + * Tell SDL_ttf whether UNICODE text is generally byteswapped. + * + * A UNICODE BOM character in a string will override this setting for the + * remainder of that string. + * + * \param swapped boolean to indicate whether text is byteswapped + * + * \since This function is available since SDL_ttf 2.0.12. + } +procedure TTF_ByteSwappedUNICODE(swapped: TSDL_bool); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_ByteSwappedUNICODE' {$ENDIF} {$ENDIF}; {* The internal structure containing font information *} type - PTTF_Font = ^TTTF_Font; - TTTF_Font = record end; //todo? - -{* Initialize the TTF engine - returns 0 if successful, -1 on error *} -function TTF_Init(): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Init' {$ENDIF} {$ENDIF}; - -{* Open a font file and create a font of the specified point size. - * Some .fon fonts will have several sizes embedded in the file, so the - * point size becomes the index of choosing which size. If the value - * is too high, the last indexed size will be the default. *} -function TTF_OpenFont(_file: PAnsiChar; ptsize: cint): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFont' {$ENDIF} {$ENDIF}; -function TTF_OpenFontIndex(_file: PAnsiChar; ptsize: cint; index: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndex' {$ENDIF} {$ENDIF}; -function TTF_OpenFontRW(src: PSDL_RWops; freesrc: cint; ptsize: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontRW' {$ENDIF} {$ENDIF}; -function TTF_OpenFontIndexRW(src: PSDL_RWops; freesrc: cint; ptsize: cint; index: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndexRW' {$ENDIF} {$ENDIF}; - -{* Set and retrieve the font style *} + PPTTF_Font = ^PTTF_Font; + PTTF_Font = type Pointer; + +{* + * Initialize SDL_ttf. + * + * You must successfully call this function before it is safe to call any + * other function in this library, with one exception: a human-readable error + * message can be retrieved from TTF_GetError() if this function fails. + * + * SDL must be initialized before calls to functions in this library, because + * this library uses utility functions from the SDL library. + * + * It is safe to call this more than once; the library keeps a counter of init + * calls, and decrements it on each call to TTF_Quit, so you must pair your + * init and quit calls. + * + * \returns 0 on success, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_Quit + * \sa TTF_WasInit + } +function TTF_Init(): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Init' {$ENDIF} {$ENDIF}; + +{* + * Create a font from a file, using a specified point size. + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param file path to font file. + * \param ptsize point size to use for the newly-opened font. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_CloseFont + } +function TTF_OpenFont(file_: PAnsiChar; ptsize: cint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFont' {$ENDIF} {$ENDIF}; + +{* + * Create a font from a file, using a specified face index. + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * Some fonts have multiple "faces" included. The index specifies which face + * to use from the font file. Font files with only one face should specify + * zero for the index. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param file path to font file. + * \param ptsize point size to use for the newly-opened font. + * \param index index of the face in the font file. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontIndex(file_: PAnsiChar; ptsize: cint; index: clong): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndex' {$ENDIF} {$ENDIF}; + +{* + * Create a font from an SDL_RWops, using a specified point size. + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * If `freesrc` is non-zero, the RWops will be automatically closed once the + * font is closed. Otherwise you should close the RWops yourself after closing + * the font. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param src an SDL_RWops to provide a font file's data. + * \param freesrc non-zero to close the RWops when the font is closed, zero to + * leave it open. + * \param ptsize point size to use for the newly-opened font. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontRW(src: PSDL_RWops; freesrc: cint; ptsize: cint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontRW' {$ENDIF} {$ENDIF}; + +{* + * Create a font from an SDL_RWops, using a specified face index. + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * If `freesrc` is non-zero, the RWops will be automatically closed once the + * font is closed. Otherwise you should close the RWops yourself after closing + * the font. + * + * Some fonts have multiple "faces" included. The index specifies which face + * to use from the font file. Font files with only one face should specify + * zero for the index. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param src an SDL_RWops to provide a font file's data. + * \param freesrc non-zero to close the RWops when the font is closed, zero to + * leave it open. + * \param ptsize point size to use for the newly-opened font. + * \param index index of the face in the font file. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontIndexRW(src: PSDL_RWops; freesrc: cint; ptsize: cint; index: clong): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndexRW' {$ENDIF} {$ENDIF}; + +{* + * Create a font from a file, using target resolutions (in DPI). + * + * DPI scaling only applies to scalable fonts (e.g. TrueType). + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param file path to font file. + * \param ptsize point size to use for the newly-opened font. + * \param hdpi the target horizontal DPI. + * \param vdpi the target vertical DPI. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontDPI(file_: PAnsiChar; ptsize: cint; hdpi: cuint; vdpi: cuint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontDPI' {$ENDIF} {$ENDIF}; + +{* + * Create a font from a file, using target resolutions (in DPI). + * + * DPI scaling only applies to scalable fonts (e.g. TrueType). + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * Some fonts have multiple "faces" included. The index specifies which face + * to use from the font file. Font files with only one face should specify + * zero for the index. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param file path to font file. + * \param ptsize point size to use for the newly-opened font. + * \param index index of the face in the font file. + * \param hdpi the target horizontal DPI. + * \param vdpi the target vertical DPI. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontIndexDPI(file_: PAnsiChar; ptsize: cint; index: clong; hdpi: cuint; vdpi: cuint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndexDPI' {$ENDIF} {$ENDIF}; + +{* + * Opens a font from an SDL_RWops with target resolutions (in DPI). + * + * DPI scaling only applies to scalable fonts (e.g. TrueType). + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * If `freesrc` is non-zero, the RWops will be automatically closed once the + * font is closed. Otherwise you should close the RWops yourself after closing + * the font. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param src an SDL_RWops to provide a font file's data. + * \param freesrc non-zero to close the RWops when the font is closed, zero to + * leave it open. + * \param ptsize point size to use for the newly-opened font. + * \param hdpi the target horizontal DPI. + * \param vdpi the target vertical DPI. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontDPIRW(src: PSDL_RWops; freesrc: cint; ptsize: cint; hdpi: cuint; vdpi: cuint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontDPIRW' {$ENDIF} {$ENDIF}; + +{* + * Opens a font from an SDL_RWops with target resolutions (in DPI). + * + * DPI scaling only applies to scalable fonts (e.g. TrueType). + * + * Some .fon fonts will have several sizes embedded in the file, so the point + * size becomes the index of choosing which size. If the value is too high, + * the last indexed size will be the default. + * + * If `freesrc` is non-zero, the RWops will be automatically closed once the + * font is closed. Otherwise you should close the RWops yourself after closing + * the font. + * + * Some fonts have multiple "faces" included. The index specifies which face + * to use from the font file. Font files with only one face should specify + * zero for the index. + * + * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it. + * + * \param src an SDL_RWops to provide a font file's data. + * \param freesrc non-zero to close the RWops when the font is closed, zero to + * leave it open. + * \param ptsize point size to use for the newly-opened font. + * \param index index of the face in the font file. + * \param hdpi the target horizontal DPI. + * \param vdpi the target vertical DPI. + * \returns a valid TTF_Font, or nil on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_CloseFont + } +function TTF_OpenFontIndexDPIRW(src: PSDL_RWops; freesrc: cint; ptsize: cint; index: clong; hdpi: cuint; vdpi: cuint): PTTF_Font; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndexDPIRW' {$ENDIF} {$ENDIF}; + +{* + * Set a font's size dynamically. + * + * This clears already-generated glyphs, if any, from the cache. + * + * \param font the font to resize. + * \param ptsize the new point size. + * \returns 0 if successful, -1 on error + * + * \since This function is available since SDL_ttf 2.0.18. + } +function TTF_SetFontSize(font: PTTF_Font; ptsize: cint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontSize' {$ENDIF} {$ENDIF}; + +{* + * Set font size dynamically with target resolutions (in DPI). + * + * This clears already-generated glyphs, if any, from the cache. + * + * \param font the font to resize. + * \param ptsize the new point size. + * \param hdpi the target horizontal DPI. + * \param vdpi the target vertical DPI. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + } +function TTF_SetFontSizeDPI(font: PTTF_Font; ptsize: cint; hdpi: cuint; vdpi: cuint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontSizeDPI' {$ENDIF} {$ENDIF}; + +{* + * Font style flags + } const TTF_STYLE_NORMAL = $00; TTF_STYLE_BOLD = $01; @@ -120,194 +461,1975 @@ function TTF_OpenFontIndexRW(src: PSDL_RWops; freesrc: cint; ptsize: cint; index TTF_STYLE_UNDERLINE = $04; TTF_STYLE_STRIKETHROUGH = $08; -function TTF_GetFontStyle(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontStyle' {$ENDIF} {$ENDIF}; -procedure TTF_SetFontStyle(font: PTTF_Font; style: cint) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontStyle' {$ENDIF} {$ENDIF}; -function TTF_GetFontOutline(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontOutline' {$ENDIF} {$ENDIF}; -procedure TTF_SetFontOutline(font: PTTF_Font; outline: cint) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontOutline' {$ENDIF} {$ENDIF}; +{* + * Query a font's current style. + * + * The font styles are a set of bit flags, OR'd together: + * + * - `TTF_STYLE_NORMAL` (is zero) + * - `TTF_STYLE_BOLD` + * - `TTF_STYLE_ITALIC` + * - `TTF_STYLE_UNDERLINE` + * - `TTF_STYLE_STRIKETHROUGH` + * + * \param font the font to query. + * \returns the current font style, as a set of bit flags. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SetFontStyle + } +function TTF_GetFontStyle(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontStyle' {$ENDIF} {$ENDIF}; + +{* + * Set a font's current style. + * + * Setting the style clears already-generated glyphs, if any, from the cache. + * + * The font styles are a set of bit flags, OR'd together: + * + * - `TTF_STYLE_NORMAL` (is zero) + * - `TTF_STYLE_BOLD` + * - `TTF_STYLE_ITALIC` + * - `TTF_STYLE_UNDERLINE` + * - `TTF_STYLE_STRIKETHROUGH` + * + * \param font the font to set a new style on. + * \param style the new style values to set, OR'd together. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GetFontStyle + } +procedure TTF_SetFontStyle(font: PTTF_Font; style: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontStyle' {$ENDIF} {$ENDIF}; + +{* + * Query a font's current outline. + * + * \param font the font to query. + * \returns the font's current outline value. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SetFontOutline + } +function TTF_GetFontOutline(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontOutline' {$ENDIF} {$ENDIF}; + +{* + * Set a font's current outline. + * + * \param font the font to set a new outline on. + * \param outline positive outline value, 0 to default. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GetFontOutline + } +procedure TTF_SetFontOutline(font: PTTF_Font; outline: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontOutline' {$ENDIF} {$ENDIF}; -{* Set and retrieve FreeType hinter settings *} +{* + * Hinting flags + } const - TTF_HINTING_NORMAL = 0; - TTF_HINTING_LIGHT = 1; - TTF_HINTING_MONO = 2; - TTF_HINTING_NONE = 3; + TTF_HINTING_NORMAL = 0; + TTF_HINTING_LIGHT = 1; + TTF_HINTING_MONO = 2; + TTF_HINTING_NONE = 3; + TTF_HINTING_LIGHT_SUBPIXEL = 4; -function TTF_GetFontHinting(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontHinting' {$ENDIF} {$ENDIF}; -procedure TTF_SetFontHinting(font: PTTF_Font; hinting: cint) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontHinting' {$ENDIF} {$ENDIF}; +{* + * Query a font's current FreeType hinter setting. + * + * The hinter setting is a single value: + * + * - `TTF_HINTING_NORMAL` + * - `TTF_HINTING_LIGHT` + * - `TTF_HINTING_MONO` + * - `TTF_HINTING_NONE` + * - `TTF_HINTING_LIGHT_SUBPIXEL` (available in SDL_ttf 2.0.18 and later) + * + * \param font the font to query. + * \returns the font's current hinter value. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SetFontHinting + } +function TTF_GetFontHinting(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontHinting' {$ENDIF} {$ENDIF}; -{* Get the total height of the font - usually equal to point size *} -function TTF_FontHeight(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontHeight' {$ENDIF} {$ENDIF}; +{* + * Set a font's current hinter setting. + * + * Setting it clears already-generated glyphs, if any, from the cache. + * + * The hinter setting is a single value: + * + * - `TTF_HINTING_NORMAL` + * - `TTF_HINTING_LIGHT` + * - `TTF_HINTING_MONO` + * - `TTF_HINTING_NONE` + * - `TTF_HINTING_LIGHT_SUBPIXEL` (available in SDL_ttf 2.0.18 and later) + * + * \param font the font to set a new hinter setting on. + * \param hinting the new hinter setting. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GetFontHinting + } +procedure TTF_SetFontHinting(font: PTTF_Font; hinting: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontHinting' {$ENDIF} {$ENDIF}; -{* Get the offset from the baseline to the top of the font - This is a positive value, relative to the baseline. - *} -function TTF_FontAscent(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontAscent' {$ENDIF} {$ENDIF}; +{* + * Special layout option for rendering wrapped text + } +const + TTF_WRAPPED_ALIGN_LEFT = 0; + TTF_WRAPPED_ALIGN_CENTER = 1; + TTF_WRAPPED_ALIGN_RIGHT = 2; -{* Get the offset from the baseline to the bottom of the font - This is a negative value, relative to the baseline. - *} -function TTF_FontDescent(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontDescent' {$ENDIF} {$ENDIF}; +{* + * Query a font's current wrap alignment option. + * + * The wrap alignment option can be one of the following: + * + * - `TTF_WRAPPED_ALIGN_LEFT` + * - `TTF_WRAPPED_ALIGN_CENTER` + * - `TTF_WRAPPED_ALIGN_RIGHT` + * + * \param font the font to query. + * \returns the font's current wrap alignment option. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_SetFontWrappedAlign + } +function TTF_GetFontWrappedAlign(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontWrappedAlign' {$ENDIF} {$ENDIF}; -{* Get the recommended spacing between lines of text for this font *} -function TTF_FontLineSkip(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontLineSkip' {$ENDIF} {$ENDIF}; +{* + * Set a font's current wrap alignment option. + * + * The wrap alignment option can be one of the following: + * + * - `TTF_WRAPPED_ALIGN_LEFT` + * - `TTF_WRAPPED_ALIGN_CENTER` + * - `TTF_WRAPPED_ALIGN_RIGHT` + * + * \param font the font to set a new wrap alignment option on. + * \param align the new wrap alignment option. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_GetFontWrappedAlign + } +procedure TTF_SetFontWrappedAlign(font: PTTF_Font; align: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontWrappedAlign' {$ENDIF} {$ENDIF}; -{* Get/Set whether or not kerning is allowed for this font *} -function TTF_GetFontKerning(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerning' {$ENDIF} {$ENDIF}; -procedure TTF_SetFontKerning(font: PTTF_Font; allowed: cint) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontKerning' {$ENDIF} {$ENDIF}; +{* + * Query the total height of a font. + * + * This is usually equal to point size. + * + * \param font the font to query. + * \returns the font's height. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontHeight(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontHeight' {$ENDIF} {$ENDIF}; -{* Get the number of faces of the font *} -function TTF_FontFaces(font: PTTF_Font): LongInt cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaces' {$ENDIF} {$ENDIF}; +{* + * Query the offset from the baseline to the top of a font. + * + * This is a positive value, relative to the baseline. + * + * \param font the font to query. + * \returns the font's ascent. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontAscent(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontAscent' {$ENDIF} {$ENDIF}; -{* Get the font face attributes, if any *} -function TTF_FontFaceIsFixedWidth(font: PTTF_Font): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceIsFixedWidth' {$ENDIF} {$ENDIF}; -function TTF_FontFaceFamilyName(font: PTTF_Font): PAnsiChar cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceFamilyName' {$ENDIF} {$ENDIF}; -function TTF_FontFaceStyleName(font: PTTF_Font): PAnsiChar cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceStyleName' {$ENDIF} {$ENDIF}; +{* + * Query the offset from the baseline to the bottom of a font. + * + * This is a negative value, relative to the baseline. + * + * \param font the font to query. + * \returns the font's descent. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontDescent(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontDescent' {$ENDIF} {$ENDIF}; -{* Check wether a glyph is provided by the font or not *} -function TTF_GlyphIsProvided(font: PTTF_Font; ch: cuint16): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphIsProvided' {$ENDIF} {$ENDIF}; +{* + * Query the spacing between lines of text for a font. + * + * \param font the font to query. + * \returns the font's line spacing. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontLineSkip(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontLineSkip' {$ENDIF} {$ENDIF}; -{* Get the metrics (dimensions) of a glyph - To understand what these metrics mean, here is a useful link: - http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html +{** + * Set the spacing between lines of text for a font. + * + * \param font the font to modify. + * \param lineskip the new line spacing for the font. + * + * \since This function is available since SDL_ttf 2.22.0. *} -function TTF_GlyphMetrics(font: PTTF_Font; ch: cuint16; - minx, maxx: pcint; - miny, maxy: pcint; advance: pcint): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphMetrics' {$ENDIF} {$ENDIF}; - -{* Get the dimensions of a rendered string of text *} -function TTF_SizeText(font: PTTF_Font; text: PAnsiChar; w, h: pcint): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeText' {$ENDIF} {$ENDIF}; -function TTF_SizeUTF8(font: PTTF_Font; text: PAnsiChar; w, h: pcint): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUTF8' {$ENDIF} {$ENDIF}; -function TTF_SizeUNICODE(font: PTTF_Font; text: pcuint16; w, h: pcint): cint cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUNICODE' {$ENDIF} {$ENDIF}; - -{* Create an 8-bit palettized surface and render the given text at - fast quality with the given font and color. The 0 pixel is the - colorkey, giving a transparent background, and the 1 pixel is set - to the text color. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderText_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Solid' {$ENDIF} {$ENDIF}; -function TTF_RenderUTF8_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Solid' {$ENDIF} {$ENDIF}; -function TTF_RenderUNICODE_Solid(font: PTTF_Font; text: pcuint16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Solid' {$ENDIF} {$ENDIF}; - -{* Create an 8-bit palettized surface and render the given glyph at - fast quality with the given font and color. The 0 pixel is the - colorkey, giving a transparent background, and the 1 pixel is set - to the text color. The glyph is rendered without any padding or - centering in the X direction, and aligned normally in the Y direction. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderGlyph_Solid(font: PTTF_Font; ch: cuint16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Solid' {$ENDIF} {$ENDIF}; +procedure TTF_SetFontLineSkip(font: PTTF_Font; lineskip: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontLineSkip' {$ENDIF} {$ENDIF}; -{* Create an 8-bit palettized surface and render the given text at - high quality with the given font and colors. The 0 pixel is background, - while other pixels have varying degrees of the foreground color. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderText_Shaded(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Shaded' {$ENDIF} {$ENDIF}; -function TTF_RenderUTF8_Shaded(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Shaded' {$ENDIF} {$ENDIF}; -function TTF_RenderUNICODE_Shaded(font: PTTF_Font; text: pcuint16; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Shaded' {$ENDIF} {$ENDIF}; - -{* Create an 8-bit palettized surface and render the given glyph at - high quality with the given font and colors. The 0 pixel is background, - while other pixels have varying degrees of the foreground color. - The glyph is rendered without any padding or centering in the X - direction, and aligned normally in the Y direction. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderGlyph_Shaded(font: PTTF_Font; ch: cuint16; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Shaded' {$ENDIF} {$ENDIF}; +{* + * Query whether or not kerning is allowed for a font. + * + * \param font the font to query. + * \returns non-zero if kerning is enabled, zero otherwise. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_GetFontKerning(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerning' {$ENDIF} {$ENDIF}; -{* Create a 32-bit ARGB surface and render the given text at high quality, - using alpha blending to dither the font with the given color. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderText_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended' {$ENDIF} {$ENDIF}; -function TTF_RenderUTF8_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended' {$ENDIF} {$ENDIF}; -function TTF_RenderUNICODE_Blended(font: PTTF_Font; text: pcuint16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended' {$ENDIF} {$ENDIF}; - -{* Create a 32-bit ARGB surface and render the given text at high quality, - using alpha blending to dither the font with the given color. - Text is wrapped to multiple lines on line endings and on word boundaries - if it extends beyond wrapLength in pixels. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderText_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended_Wrapped' {$ENDIF} {$ENDIF}; -function TTF_RenderUTF8_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended_Wrapped' {$ENDIF} {$ENDIF}; -function TTF_RenderUNICODE_Blended_Wrapped(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended_Wrapped' {$ENDIF} {$ENDIF}; - -{* Create a 32-bit ARGB surface and render the given glyph at high quality, - using alpha blending to dither the font with the given color. - The glyph is rendered without any padding or centering in the X - direction, and aligned normally in the Y direction. - This function returns the new surface, or NULL if there was an error. -*} -function TTF_RenderGlyph_Blended(font: PTTF_Font; ch: cuint16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Blended' {$ENDIF} {$ENDIF}; +{* + * Set if kerning is allowed for a font. + * + * Newly-opened fonts default to allowing kerning. This is generally a good + * policy unless you have a strong reason to disable it, as it tends to + * produce better rendering (with kerning disabled, some fonts might render + * the word `kerning` as something that looks like `keming` for example). + * + * \param font the font to set kerning on. + * \param allowed non-zero to allow kerning, zero to disallow. + * + * \since This function is available since SDL_ttf 2.0.12. + } +procedure TTF_SetFontKerning(font: PTTF_Font; allowed: cint); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontKerning' {$ENDIF} {$ENDIF}; -{* For compatibility with previous versions, here are the old functions *} -function TTF_RenderText(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; -function TTF_RenderUTF8(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; -function TTF_RenderUNICODE(font: PTTF_Font; text: pcuint16; fg, bg: TSDL_Color): PSDL_Surface; +{* + * Query the number of faces of a font. + * + * \param font the font to query. + * \returns the number of FreeType font faces. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontFaces(font: PTTF_Font): clong; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaces' {$ENDIF} {$ENDIF}; -{* Close an opened font file *} -procedure TTF_CloseFont(font: PTTF_Font) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_CloseFont' {$ENDIF} {$ENDIF}; +{* + * Query whether a font is fixed-width. + * + * A "fixed-width" font means all glyphs are the same width across; a + * lowercase 'i' will be the same size across as a capital 'W', for example. + * This is common for terminals and text editors, and other apps that treat + * text as a grid. Most other things (WYSIWYG word processors, web pages, etc) + * are more likely to not be fixed-width in most cases. + * + * \param font the font to query. + * \returns non-zero if fixed-width, zero if not. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontFaceIsFixedWidth(font: PTTF_Font): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceIsFixedWidth' {$ENDIF} {$ENDIF}; -{* De-initialize the TTF engine *} -procedure TTF_Quit() cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Quit' {$ENDIF} {$ENDIF}; +{* + * Query a font's family name. + * + * This string is dictated by the contents of the font file. + * + * Note that the returned string is to internal storage, and should not be + * modifed or free'd by the caller. The string becomes invalid, with the rest + * of the font, when `font` is handed to TTF_CloseFont(). + * + * \param font the font to query. + * \returns the font's family name. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontFaceFamilyName(font: PTTF_Font): PAnsiChar; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceFamilyName' {$ENDIF} {$ENDIF}; -{* Check if the TTF engine is initialized *} -function TTF_WasInit: Boolean cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_WasInit' {$ENDIF} {$ENDIF}; +{* + * Query a font's style name. + * + * This string is dictated by the contents of the font file. + * + * Note that the returned string is to internal storage, and should not be + * modifed or free'd by the caller. The string becomes invalid, with the rest + * of the font, when `font` is handed to TTF_CloseFont(). + * + * \param font the font to query. + * \returns the font's style name. + * + * \since This function is available since SDL_ttf 2.0.12. + } +function TTF_FontFaceStyleName(font: PTTF_Font): PAnsiChar; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceStyleName' {$ENDIF} {$ENDIF}; -{* Get the kerning size of two glyphs +{* + * Check whether a glyph is provided by the font for a 16-bit codepoint. + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_GlyphIsProvided32() instead, which offers the same functionality + * but takes a 32-bit codepoint instead. + * + * The only reason to use this function is that it was available since the + * beginning of time, more or less. + * + * \param font the font to query. + * \param ch the character code to check. + * \returns non-zero if font provides a glyph for this character, zero if not. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GlyphIsProvided32 + } +function TTF_GlyphIsProvided(font: PTTF_Font; ch: cuint16): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphIsProvided' {$ENDIF} {$ENDIF}; - DEPRECATED: this function requires FreeType font indexes, not glyphs, - by accident, which we don't expose through this API, so it could give - wildly incorrect results, especially with non-ASCII values. - Going forward, please use TTF_GetFontKerningSizeGlyphs() instead, which - does what you probably expected this function to do. -*} -function TTF_GetFontKerningSize(font: PTTF_Font; prev_index, index: cint): cint cdecl; +{* + * Check whether a glyph is provided by the font for a 32-bit codepoint. + * + * This is the same as TTF_GlyphIsProvided(), but takes a 32-bit character + * instead of 16-bit, and thus can query a larger range. If you are sure + * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason + * not to use this function exclusively. + * + * \param font the font to query. + * \param ch the character code to check. + * \returns non-zero if font provides a glyph for this character, zero if not. + * + * \since This function is available since SDL_ttf 2.0.18. + } +function TTF_GlyphIsProvided32(font: PTTF_Font; ch: cuint32): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphIsProvided32' {$ENDIF} {$ENDIF}; + +{* + * Query the metrics (dimensions) of a font's 16-bit glyph. + * + * To understand what these metrics mean, here is a useful link: + * + * https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_GlyphMetrics32() instead, which offers the same functionality but + * takes a 32-bit codepoint instead. + * + * The only reason to use this function is that it was available since the + * beginning of time, more or less. + * + * \param font the font to query. + * \param ch the character code to check. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GlyphMetrics32 + } +function TTF_GlyphMetrics(font: PTTF_Font; ch: cuint16; minx: pcint; maxx: pcint; miny: pcint; maxy: pcint; advance: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphMetrics' {$ENDIF} {$ENDIF}; + +{* + * Query the metrics (dimensions) of a font's 32-bit glyph. + * + * To understand what these metrics mean, here is a useful link: + * + * https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html + * + * This is the same as TTF_GlyphMetrics(), but takes a 32-bit character + * instead of 16-bit, and thus can query a larger range. If you are sure + * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason + * not to use this function exclusively. + * + * \param font the font to query. + * \param ch the character code to check. + * + * \since This function is available since SDL_ttf 2.0.18. + } +function TTF_GlyphMetrics32(font: PTTF_Font; ch: cuint32; minx: pcint; maxx: pcint; miny: pcint; maxy: pcint; advance: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphMetrics32' {$ENDIF} {$ENDIF}; + +{* + * Calculate the dimensions of a rendered string of Latin1 text. + * + * This will report the width and height, in pixels, of the space that the + * specified string will take to fully render. + * + * This does not need to render the string to do this calculation. + * + * You almost certainly want TTF_SizeUTF8() unless you're sure you have a + * 1-byte Latin1 encoding. US ASCII characters will work with either function, + * but most other Unicode characters packed into a `const char *` will need + * UTF-8. + * + * \param font the font to query. + * \param text text to calculate, in Latin1 encoding. + * \param w will be filled with width, in pixels, on return. + * \param h will be filled with height, in pixels, on return. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SizeUTF8 + * \sa TTF_SizeUNICODE + } +function TTF_SizeText(font: PTTF_Font; text: PAnsiChar; w: pcint; h: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeText' {$ENDIF} {$ENDIF}; + +{* + * Calculate the dimensions of a rendered string of UTF-8 text. + * + * This will report the width and height, in pixels, of the space that the + * specified string will take to fully render. + * + * This does not need to render the string to do this calculation. + * + * \param font the font to query. + * \param text text to calculate, in UTF-8 encoding. + * \param w will be filled with width, in pixels, on return. + * \param h will be filled with height, in pixels, on return. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SizeUNICODE + } +function TTF_SizeUTF8(font: PTTF_Font; text: PAnsiChar; w: pcint; h: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUTF8' {$ENDIF} {$ENDIF}; + +{* + * Calculate the dimensions of a rendered string of UCS-2 text. + * + * This will report the width and height, in pixels, of the space that the + * specified string will take to fully render. + * + * This does not need to render the string to do this calculation. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * \param font the font to query. + * \param text text to calculate, in UCS-2 encoding. + * \param w will be filled with width, in pixels, on return. + * \param h will be filled with height, in pixels, on return. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_SizeUTF8 + } +function TTF_SizeUNICODE(font: PTTF_Font; text: pcuint16; w: pcint; h: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUNICODE' {$ENDIF} {$ENDIF}; + +{* + * Calculate how much of a Latin1 string will fit in a given width. + * + * This reports the number of characters that can be rendered before reaching + * `measure_width`. + * + * This does not need to render the string to do this calculation. + * + * You almost certainly want TTF_MeasureUTF8() unless you're sure you have a + * 1-byte Latin1 encoding. US ASCII characters will work with either function, + * but most other Unicode characters packed into a `const char *` will need + * UTF-8. + * + * \param font the font to query. + * \param text text to calculate, in Latin1 encoding. + * \param measure_width maximum width, in pixels, available for the string. + * \param extent on return, filled with latest calculated width. + * \param count on return, filled with number of characters that can be + * rendered. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_MeasureText + * \sa TTF_MeasureUTF8 + * \sa TTF_MeasureUNICODE + } +function TTF_MeasureText(font: PTTF_Font; text: PAnsiChar; measure_width: cint; extent: pcint; count: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_MeasureText' {$ENDIF} {$ENDIF}; + +{* + * Calculate how much of a UTF-8 string will fit in a given width. + * + * This reports the number of characters that can be rendered before reaching + * `measure_width`. + * + * This does not need to render the string to do this calculation. + * + * \param font the font to query. + * \param text text to calculate, in UTF-8 encoding. + * \param measure_width maximum width, in pixels, available for the string. + * \param extent on return, filled with latest calculated width. + * \param count on return, filled with number of characters that can be + * rendered. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_MeasureText + * \sa TTF_MeasureUTF8 + * \sa TTF_MeasureUNICODE + } +function TTF_MeasureUTF8(font: PTTF_Font; text: PAnsiChar; measure_width: cint; extent: pcint; count: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_MeasureUTF8' {$ENDIF} {$ENDIF}; + +{* + * Calculate how much of a UCS-2 string will fit in a given width. + * + * This reports the number of characters that can be rendered before reaching + * `measure_width`. + * + * This does not need to render the string to do this calculation. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * \param font the font to query. + * \param text text to calculate, in UCS-2 encoding. + * \param measure_width maximum width, in pixels, available for the string. + * \param extent on return, filled with latest calculated width. + * \param count on return, filled with number of characters that can be + * rendered. + * \returns 0 if successful, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_MeasureText + * \sa TTF_MeasureUTF8 + * \sa TTF_MeasureUNICODE + } +function TTF_MeasureUNICODE(font: PTTF_Font; text: pcuint16; measure_width: cint; extent: pcint; count: pcint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_MeasureUNICODE' {$ENDIF} {$ENDIF}; + +{* + * Render Latin1 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderText_Solid_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Solid() unless you're sure you + * have a 1-byte Latin1 encoding. US ASCII characters will work with either + * function, but most other Unicode characters packed into a `const char *` + * will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Shaded, + * TTF_RenderText_Blended, and TTF_RenderText_LCD. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Solid + * \sa TTF_RenderUNICODE_Solid + } +function TTF_RenderText_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Solid' {$ENDIF} {$ENDIF}; + +{* + * Render UTF-8 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUTF8_Solid_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Shaded, + * TTF_RenderUTF8_Blended, and TTF_RenderUTF8_LCD. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Shaded + * \sa TTF_RenderUTF8_Blended + * \sa TTF_RenderUTF8_LCD + } +function TTF_RenderUTF8_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Solid' {$ENDIF} {$ENDIF}; + +{* + * Render UCS-2 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUNICODE_Solid_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with TTF_RenderUNICODE_Shaded, + * TTF_RenderUNICODE_Blended, and TTF_RenderUNICODE_LCD. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Solid + } +function TTF_RenderUNICODE_Solid(font: PTTF_Font; text: pcuint16; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Solid' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped Latin1 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Solid_Wrapped() unless you're sure + * you have a 1-byte Latin1 encoding. US ASCII characters will work with + * either function, but most other Unicode characters packed into a `const + * char *` will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Shaded_Wrapped, + * TTF_RenderText_Blended_Wrapped, and TTF_RenderText_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Solid_Wrapped + * \sa TTF_RenderUNICODE_Solid_Wrapped + } +function TTF_RenderText_Solid_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Solid_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UTF-8 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Shaded_Wrapped, + * TTF_RenderUTF8_Blended_Wrapped, and TTF_RenderUTF8_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Shaded_Wrapped + * \sa TTF_RenderUTF8_Blended_Wrapped + * \sa TTF_RenderUTF8_LCD_Wrapped + } +function TTF_RenderUTF8_Solid_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Solid_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UCS-2 text at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with + * TTF_RenderUNICODE_Shaded_Wrapped, TTF_RenderUNICODE_Blended_Wrapped, and + * TTF_RenderUNICODE_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Solid_Wrapped + } +function TTF_RenderUNICODE_Solid_Wrapped(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Solid_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render a single 16-bit glyph at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_RenderGlyph32_Solid() instead, which offers the same functionality + * but takes a 32-bit codepoint instead. + * + * The only reason to use this function is that it was available since the + * beginning of time, more or less. + * + * You can render at other quality levels with TTF_RenderGlyph_Shaded, + * TTF_RenderGlyph_Blended, and TTF_RenderGlyph_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderGlyph32_Solid + } +function TTF_RenderGlyph_Solid(font: PTTF_Font; ch: cuint16; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Solid' {$ENDIF} {$ENDIF}; + +{* + * Render a single 32-bit glyph at fast quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the colorkey, giving a transparent background. The 1 pixel + * will be set to the text color. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * This is the same as TTF_RenderGlyph_Solid(), but takes a 32-bit character + * instead of 16-bit, and thus can render a larger range. If you are sure + * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason + * not to use this function exclusively. + * + * You can render at other quality levels with TTF_RenderGlyph32_Shaded, + * TTF_RenderGlyph32_Blended, and TTF_RenderGlyph32_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderGlyph32_Shaded + * \sa TTF_RenderGlyph32_Blended + * \sa TTF_RenderGlyph32_LCD + } +function TTF_RenderGlyph32_Solid(font: PTTF_Font; ch: cuint32; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph32_Solid' {$ENDIF} {$ENDIF}; + +{* + * Render Latin1 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderText_Shaded_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Shaded() unless you're sure you + * have a 1-byte Latin1 encoding. US ASCII characters will work with either + * function, but most other Unicode characters packed into a `const char *` + * will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid, + * TTF_RenderText_Blended, and TTF_RenderText_LCD. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Shaded + * \sa TTF_RenderUNICODE_Shaded + } +function TTF_RenderText_Shaded(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Shaded' {$ENDIF} {$ENDIF}; + +{* + * Render UTF-8 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUTF8_Shaded_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid, + * TTF_RenderUTF8_Blended, and TTF_RenderUTF8_LCD. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUNICODE_Shaded + } +function TTF_RenderUTF8_Shaded(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Shaded' {$ENDIF} {$ENDIF}; + +{* + * Render UCS-2 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUNICODE_Shaded_Wrapped() instead if you need to wrap the output + * to multiple lines. + * + * This will not wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with TTF_RenderUNICODE_Solid, + * TTF_RenderUNICODE_Blended, and TTF_RenderUNICODE_LCD. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Shaded + } +function TTF_RenderUNICODE_Shaded(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Shaded' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped Latin1 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Shaded_Wrapped() unless you're + * sure you have a 1-byte Latin1 encoding. US ASCII characters will work with + * either function, but most other Unicode characters packed into a `const + * char *` will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid_Wrapped, + * TTF_RenderText_Blended_Wrapped, and TTF_RenderText_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Shaded_Wrapped + * \sa TTF_RenderUNICODE_Shaded_Wrapped + } +function TTF_RenderText_Shaded_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Shaded_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UTF-8 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, + * TTF_RenderUTF8_Blended_Wrapped, and TTF_RenderUTF8_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Solid_Wrapped + * \sa TTF_RenderUTF8_Blended_Wrapped + * \sa TTF_RenderUTF8_LCD_Wrapped + } +function TTF_RenderUTF8_Shaded_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Shaded_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UCS-2 text at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with + * TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Blended_Wrapped, and + * TTF_RenderUNICODE_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Shaded_Wrapped + } +function TTF_RenderUNICODE_Shaded_Wrapped(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Shaded_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render a single 16-bit glyph at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_RenderGlyph32_Shaded() instead, which offers the same functionality + * but takes a 32-bit codepoint instead. + * + * The only reason to use this function is that it was available since the + * beginning of time, more or less. + * + * You can render at other quality levels with TTF_RenderGlyph_Solid, + * TTF_RenderGlyph_Blended, and TTF_RenderGlyph_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderGlyph32_Shaded + } +function TTF_RenderGlyph_Shaded(font: PTTF_Font; ch: cuint16; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Shaded' {$ENDIF} {$ENDIF}; + +{* + * Render a single 32-bit glyph at high quality to a new 8-bit surface. + * + * This function will allocate a new 8-bit, palettized surface. The surface's + * 0 pixel will be the specified background color, while other pixels have + * varying degrees of the foreground color. This function returns the new + * surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * This is the same as TTF_RenderGlyph_Shaded(), but takes a 32-bit character + * instead of 16-bit, and thus can render a larger range. If you are sure + * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason + * not to use this function exclusively. + * + * You can render at other quality levels with TTF_RenderGlyph32_Solid, + * TTF_RenderGlyph32_Blended, and TTF_RenderGlyph32_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 8-bit, palettized surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderGlyph32_Solid + * \sa TTF_RenderGlyph32_Blended + * \sa TTF_RenderGlyph32_LCD + } +function TTF_RenderGlyph32_Shaded(font: PTTF_Font; ch: cuint32; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph32_Shaded' {$ENDIF} {$ENDIF}; + +{* + * Render Latin1 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderText_Blended_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Blended() unless you're sure you + * have a 1-byte Latin1 encoding. US ASCII characters will work with either + * function, but most other Unicode characters packed into a `const char *` + * will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid, + * TTF_RenderText_Blended, and TTF_RenderText_LCD. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Shaded + * \sa TTF_RenderUNICODE_Shaded + } +function TTF_RenderText_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended' {$ENDIF} {$ENDIF}; + +{* + * Render UTF-8 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUTF8_Blended_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid, + * TTF_RenderUTF8_Shaded, and TTF_RenderUTF8_LCD. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUNICODE_Blended + } +function TTF_RenderUTF8_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended' {$ENDIF} {$ENDIF}; + +{* + * Render UCS-2 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUNICODE_Blended_Wrapped() instead if you need to wrap the output + * to multiple lines. + * + * This will not wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with TTF_RenderUNICODE_Solid, + * TTF_RenderUNICODE_Shaded, and TTF_RenderUNICODE_LCD. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderUTF8_Blended + } +function TTF_RenderUNICODE_Blended(font: PTTF_Font; text: pcuint16; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped Latin1 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_Blended_Wrapped() unless you're + * sure you have a 1-byte Latin1 encoding. US ASCII characters will work with + * either function, but most other Unicode characters packed into a `const + * char *` will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid_Wrapped, + * TTF_RenderText_Shaded_Wrapped, and TTF_RenderText_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \param wrapLength the text is wrapped to multiple lines on line endings and + * on word boundaries if it extends beyond this value in + * pixels. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Blended_Wrapped + * \sa TTF_RenderUNICODE_Blended_Wrapped + } +function TTF_RenderText_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UTF-8 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, + * TTF_RenderUTF8_Shaded_Wrapped, and TTF_RenderUTF8_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \param wrapLength the text is wrapped to multiple lines on line endings and + * on word boundaries if it extends beyond this value in + * pixels. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Solid_Wrapped + * \sa TTF_RenderUTF8_Shaded_Wrapped + * \sa TTF_RenderUTF8_LCD_Wrapped + } +function TTF_RenderUTF8_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UCS-2 text at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with + * TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Shaded_Wrapped, and + * TTF_RenderUNICODE_LCD_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \param wrapLength the text is wrapped to multiple lines on line endings and + * on word boundaries if it extends beyond this value in + * pixels. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderUTF8_Blended_Wrapped + } +function TTF_RenderUNICODE_Blended_Wrapped(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render a single 16-bit glyph at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_RenderGlyph32_Blended() instead, which offers the same + * functionality but takes a 32-bit codepoint instead. + * + * The only reason to use this function is that it was available since the + * beginning of time, more or less. + * + * You can render at other quality levels with TTF_RenderGlyph_Solid, + * TTF_RenderGlyph_Shaded, and TTF_RenderGlyph_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_RenderGlyph32_Blended + } +function TTF_RenderGlyph_Blended(font: PTTF_Font; ch: cuint16; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Blended' {$ENDIF} {$ENDIF}; + +{* + * Render a single 32-bit glyph at high quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, using alpha + * blending to dither the font with the given color. This function returns the + * new surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * This is the same as TTF_RenderGlyph_Blended(), but takes a 32-bit character + * instead of 16-bit, and thus can render a larger range. If you are sure + * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason + * not to use this function exclusively. + * + * You can render at other quality levels with TTF_RenderGlyph32_Solid, + * TTF_RenderGlyph32_Shaded, and TTF_RenderGlyph32_LCD. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_RenderGlyph32_Solid + * \sa TTF_RenderGlyph32_Shaded + * \sa TTF_RenderGlyph32_LCD + } +function TTF_RenderGlyph32_Blended(font: PTTF_Font; ch: cuint32; fg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph32_Blended' {$ENDIF} {$ENDIF}; + +{* + * Render Latin1 text at LCD subpixel quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderText_LCD_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_LCD() unless you're sure you have + * a 1-byte Latin1 encoding. US ASCII characters will work with either + * function, but most other Unicode characters packed into a `const char *` + * will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid, + * TTF_RenderText_Shaded, and TTF_RenderText_Blended. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUTF8_LCD + * \sa TTF_RenderUNICODE_LCD + } +function TTF_RenderText_LCD(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_LCD' {$ENDIF} {$ENDIF}; + +{* + * Render UTF-8 text at LCD subpixel quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUTF8_LCD_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid, + * TTF_RenderUTF8_Shaded, and TTF_RenderUTF8_Blended. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUNICODE_LCD + } +function TTF_RenderUTF8_LCD(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_LCD' {$ENDIF} {$ENDIF}; + +{* + * Render UCS-2 text at LCD subpixel quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * This will not word-wrap the string; you'll get a surface with a single line + * of text, as long as the string requires. You can use + * TTF_RenderUNICODE_LCD_Wrapped() instead if you need to wrap the output to + * multiple lines. + * + * This will not wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with TTF_RenderUNICODE_Solid, + * TTF_RenderUNICODE_Shaded, and TTF_RenderUNICODE_Blended. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUTF8_LCD + } +function TTF_RenderUNICODE_LCD(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_LCD' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped Latin1 text at LCD subpixel quality to a new ARGB + * surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You almost certainly want TTF_RenderUTF8_LCD_Wrapped() unless you're sure + * you have a 1-byte Latin1 encoding. US ASCII characters will work with + * either function, but most other Unicode characters packed into a `const + * char *` will need UTF-8. + * + * You can render at other quality levels with TTF_RenderText_Solid_Wrapped, + * TTF_RenderText_Shaded_Wrapped, and TTF_RenderText_Blended_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in Latin1 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUTF8_LCD_Wrapped + * \sa TTF_RenderUNICODE_LCD_Wrapped + } +function TTF_RenderText_LCD_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_LCD_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UTF-8 text at LCD subpixel quality to a new ARGB + * surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, + * TTF_RenderUTF8_Shaded_Wrapped, and TTF_RenderUTF8_Blended_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UTF-8 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUTF8_Solid_Wrapped + * \sa TTF_RenderUTF8_Shaded_Wrapped + * \sa TTF_RenderUTF8_Blended_Wrapped + } +function TTF_RenderUTF8_LCD_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_LCD_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render word-wrapped UCS-2 text at LCD subpixel quality to a new ARGB + * surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * Text is wrapped to multiple lines on line endings and on word boundaries if + * it extends beyond `wrapLength` in pixels. + * + * If wrapLength is 0, this function will only wrap on newline characters. + * + * Please note that this function is named "Unicode" but currently expects + * UCS-2 encoding (16 bits per codepoint). This does not give you access to + * large Unicode values, such as emoji glyphs. These codepoints are accessible + * through the UTF-8 version of this function. + * + * You can render at other quality levels with + * TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Shaded_Wrapped, and + * TTF_RenderUNICODE_Blended_Wrapped. + * + * \param font the font to render with. + * \param text text to render, in UCS-2 encoding. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderUTF8_LCD_Wrapped + } +function TTF_RenderUNICODE_LCD_Wrapped(font: PTTF_Font; text: pcuint16; fg: TSDL_Color; bg: TSDL_Color; wrapLength: cuint32): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_LCD_Wrapped' {$ENDIF} {$ENDIF}; + +{* + * Render a single 16-bit glyph at LCD subpixel quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * Note that this version of the function takes a 16-bit character code, which + * covers the Basic Multilingual Plane, but is insufficient to cover the + * entire set of possible Unicode values, including emoji glyphs. You should + * use TTF_RenderGlyph32_LCD() instead, which offers the same functionality + * but takes a 32-bit codepoint instead. + * + * This function only exists for consistency with the existing API at the time + * of its addition. + * + * You can render at other quality levels with TTF_RenderGlyph_Solid, + * TTF_RenderGlyph_Shaded, and TTF_RenderGlyph_Blended. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderGlyph32_LCD + } +function TTF_RenderGlyph_LCD(font: PTTF_Font; ch: cuint16; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_LCD' {$ENDIF} {$ENDIF}; + +{* + * Render a single 32-bit glyph at LCD subpixel quality to a new ARGB surface. + * + * This function will allocate a new 32-bit, ARGB surface, and render + * alpha-blended text using FreeType's LCD subpixel rendering. This function + * returns the new surface, or nil if there was an error. + * + * The glyph is rendered without any padding or centering in the X direction, + * and aligned normally in the Y direction. + * + * This is the same as TTF_RenderGlyph_LCD(), but takes a 32-bit character + * instead of 16-bit, and thus can render a larger range. Between the two, you + * should always use this function. + * + * You can render at other quality levels with TTF_RenderGlyph32_Solid, + * TTF_RenderGlyph32_Shaded, and TTF_RenderGlyph32_Blended. + * + * \param font the font to render with. + * \param ch the character to render. + * \param fg the foreground color for the text. + * \param bg the background color for the text. + * \returns a new 32-bit, ARGB surface, or nil if there was an error. + * + * \since This function is available since SDL_ttf 2.20.0. + * + * \sa TTF_RenderGlyph32_Solid + * \sa TTF_RenderGlyph32_Shaded + * \sa TTF_RenderGlyph32_Blended + } +function TTF_RenderGlyph32_LCD(font: PTTF_Font; ch: cuint32; fg: TSDL_Color; bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph32_LCD' {$ENDIF} {$ENDIF}; + +{* For compatibility with previous versions, here are the old functions *} +function TTF_RenderText(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_TTF_RenderText_Shaded' {$ELSE} 'TTF_RenderText_Shaded' {$ENDIF}; +function TTF_RenderUTF8(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_TTF_RenderUTF8_Shaded' {$ELSE} 'TTF_RenderUTF8_Shaded' {$ENDIF}; +function TTF_RenderUNICODE(font: PTTF_Font; text: pcuint16; fg, bg: TSDL_Color): PSDL_Surface; cdecl; + external TTF_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_TTF_RenderUNICODE_Shaded' {$ELSE} 'TTF_RenderUNICODE_Shaded' {$ENDIF}; + +{* + * Dispose of a previously-created font. + * + * Call this when done with a font. This function will free any resources + * associated with it. It is safe to call this function on nil, for example + * on the result of a failed call to TTF_OpenFont(). + * + * The font is not valid after being passed to this function. String pointers + * from functions that return information on this font, such as + * TTF_FontFaceFamilyName() and TTF_FontFaceStyleName(), are no longer valid + * after this call, as well. + * + * \param font the font to dispose of. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_OpenFont + * \sa TTF_OpenFontIndexDPIRW + * \sa TTF_OpenFontRW + * \sa TTF_OpenFontDPI + * \sa TTF_OpenFontDPIRW + * \sa TTF_OpenFontIndex + * \sa TTF_OpenFontIndexDPI + * \sa TTF_OpenFontIndexDPIRW + * \sa TTF_OpenFontIndexRW + } +procedure TTF_CloseFont(font: PTTF_Font); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_CloseFont' {$ENDIF} {$ENDIF}; + +{* + * Deinitialize SDL_ttf. + * + * You must call this when done with the library, to free internal resources. + * It is safe to call this when the library isn't initialized, as it will just + * return immediately. + * + * Once you have as many quit calls as you have had successful calls to + * TTF_Init, the library will actually deinitialize. + * + * Please note that this does not automatically close any fonts that are still + * open at the time of deinitialization, and it is possibly not safe to close + * them afterwards, as parts of the library will no longer be initialized to + * deal with it. A well-written program should call TTF_CloseFont() on any + * open fonts before calling this function! + * + * \since This function is available since SDL_ttf 2.0.12. + } +procedure TTF_Quit(); cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Quit' {$ENDIF} {$ENDIF}; + +{* + * Check if SDL_ttf is initialized. + * + * This reports the number of times the library has been initialized by a call + * to TTF_Init(), without a paired deinitialization request from TTF_Quit(). + * + * In short: if it's greater than zero, the library is currently initialized + * and ready to work. If zero, it is not initialized. + * + * Despite the return value being a signed integer, this function should not + * return a negative number. + * + * \returns the current number of initialization calls, that need to + * eventually be paired with this many calls to TTF_Quit(). + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_Init + * \sa TTF_Quit + } +function TTF_WasInit: cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_WasInit' {$ENDIF} {$ENDIF}; + +{* + * Query the kerning size of two glyphs indices. + * + * \deprecated This function accidentally requires FreeType font indexes, + * not codepoints, which we don't expose through this API, so + * it could give wildly incorrect results, especially with + * non-ASCII values. Going forward, please use + * TTF_GetFontKerningSizeGlyphs() instead, which does what you + * probably expected this function to do. + * + * \param font the font to query. + * \param prev_index the font index, NOT codepoint, of the previous character. + * \param index the font index, NOT codepoint, of the current character. + * \returns The kerning size between the two specified characters, in pixels, or -1 on error. + * + * \since This function is available since SDL_ttf 2.0.12. + * + * \sa TTF_GetFontKerningSizeGlyphs + } +function TTF_GetFontKerningSize(font: PTTF_Font; prev_index: cint; index: cint): cint; cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerningSize' {$ENDIF} {$ENDIF}; deprecated 'This function requires FreeType font indexes, not glyphs. Use TTF_GetFontKerningSizeGlyphs() instead'; -{* Get the kerning size of two glyphs *} -function TTF_GetFontKerningSizeGlyphs(font: PTTF_Font; previous_ch, ch: cuint16): cint cdecl; +{* + * Query the kerning size of two 16-bit glyphs. + * + * Note that this version of the function takes 16-bit character + * codes, which covers the Basic Multilingual Plane, but is insufficient + * to cover the entire set of possible Unicode values, including emoji + * glyphs. You should use TTF_GetFontKerningSizeGlyphs32() instead, which + * offers the same functionality but takes a 32-bit codepoints instead. + * + * The only reason to use this function is that it was available since + * the beginning of time, more or less. + * + * \param font the font to query. + * \param previous_ch the previous character's code, 16 bits. + * \param ch the current character's code, 16 bits. + * \returns The kerning size between the two specified characters, in pixels, or -1 on error. + * + * \since This function is available since SDL_ttf 2.0.14. + * + * \sa TTF_GetFontKerningSizeGlyphs32 + } +function TTF_GetFontKerningSizeGlyphs(font: PTTF_Font; previous_ch: cuint16; ch: cuint16): cint; cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerningSizeGlyphs' {$ENDIF} {$ENDIF}; -{* We'll use SDL for reporting errors *} -function TTF_SetError(const fmt: PAnsiChar): cint32; cdecl; +{* + * Query the kerning size of two 32-bit glyphs. + * + * This is the same as TTF_GetFontKerningSizeGlyphs(), but takes 32-bit + * characters instead of 16-bit, and thus can manage a larger range. If + * you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, + * there's no reason not to use this function exclusively. + * + * \param font the font to query. + * \param previous_ch the previous character's code, 32 bits. + * \param ch the current character's code, 32 bits. + * \returns The kerning size between the two specified characters, in pixels, or -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + } +function TTF_GetFontKerningSizeGlyphs32(font: PTTF_Font; previous_ch: cuint32; ch: cuint32): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerningSizeGlyphs32' {$ENDIF} {$ENDIF}; + +{* + * Enable Signed Distance Field rendering for a font. + * + * This works with the Blended APIs. SDF is a technique that + * helps fonts look sharp even when scaling and rotating. + * + * This clears already-generated glyphs, if any, from the cache. + * + * \param font the font to set SDF support on. + * \param on_off SDL_TRUE to enable SDF, SDL_FALSE to disable. + * + * \returns 0 on success, -1 on error. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_GetFontSDF + } +function TTF_SetFontSDF(font: PTTF_Font; on_off: TSDL_bool): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontSDF' {$ENDIF} {$ENDIF}; + +{* + * Query whether Signed Distance Field rendering is enabled for a font. + * + * \param font the font to query + * + * \returns SDL_TRUE if enabled, SDL_FALSE otherwise. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_SetFontSDF + } +(* Const before type ignored *) +function TTF_GetFontSDF(font: PTTF_Font): TSDL_bool; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontSDF' {$ENDIF} {$ENDIF}; + +{* + * Report SDL_ttf errors + * + * \sa TTF_GetError + } +function TTF_SetError(const fmt: PAnsiChar; args: array of const): cint; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_SetError' {$ELSE} 'SDL_SetError' {$ENDIF}; + +{* + * Get last SDL_ttf error + * + * \sa TTF_SetError + } function TTF_GetError: PAnsiChar; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_GetError' {$ELSE} 'SDL_GetError' {$ENDIF}; + +{* + * Direction flags + * + * \sa TTF_SetFontDirection + } +type + PPTTF_Direction = ^PTTF_Direction; + PTTF_Direction = ^TTTF_Direction; + TTTF_Direction = type Integer; + +const + TTF_DIRECTION_LTR = TTTF_Direction(0); { Left to Right } + TTF_DIRECTION_RTL = TTTF_Direction(1); { Right to Left } + TTF_DIRECTION_TTB = TTTF_Direction(2); { Top to Bottom } + TTF_DIRECTION_BTT = TTTF_Direction(3); { Bottom to Top } + +{* + * Set a global direction to be used for text shaping. + * + * \deprecated This function expects an hb_direction_t value, from HarfBuzz, + * cast to an int, and affects all fonts globally. Please use + * TTF_SetFontDirection() instead, which uses an enum supplied by + * SDL_ttf itself and operates on a per-font basis. + * + * This is a global setting; fonts will favor a value set with + * TTF_SetFontDirection(), but if they have not had one explicitly + * set, they will use the value specified here. + * + * The default value is `HB_DIRECTION_LTR` (left-to-right text + * flow). + * + * \param direction an hb_direction_t value. + * \returns 0, or -1 if SDL_ttf is not compiled with HarfBuzz support. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_SetFontDirection + } +function TTF_SetDirection(direction: cint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetDirection' {$ENDIF} {$ENDIF}; + deprecated; { hb_direction_t } + + +{* + * Set a global script to be used for text shaping. + * + * \deprecated This function expects an hb_script_t value, from HarfBuzz, cast + * to an int, and affects all fonts globally. Please use + * TTF_SetFontScriptName() instead, which accepts a string that is + * converted to an equivalent int internally, and operates on a + * per-font basis. + * + * This is a global setting; fonts will favor a value set with + * TTF_SetFontScriptName(), but if they have not had one + * explicitly set, they will use the value specified here. + * + * The default value is `HB_SCRIPT_UNKNOWN`. + * + * \returns 0, or -1 if SDL_ttf is not compiled with HarfBuzz support. + * + * \since This function is available since SDL_ttf 2.0.18. + * + * \sa TTF_SetFontScriptName + } +function TTF_SetScript(script: cint): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetScript' {$ENDIF} {$ENDIF}; + deprecated; { hb_script_t } + +{* + * Set direction to be used for text shaping by a font. + * + * Any value supplied here will override the global direction set with the + * deprecated TTF_SetDirection(). + * + * Possible direction values are: + * + * - `TTF_DIRECTION_LTR` (Left to Right) + * - `TTF_DIRECTION_RTL` (Right to Left) + * - `TTF_DIRECTION_TTB` (Top to Bottom) + * - `TTF_DIRECTION_BTT` (Bottom to Top) + * + * If SDL_ttf was not built with HarfBuzz support, this function returns -1. + * + * \param font the font to specify a direction for. + * \param direction the new direction for text to flow. + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL_ttf 2.20.0. + } +function TTF_SetFontDirection(font: PTTF_Font; direction: TTTF_Direction): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontDirection' {$ENDIF} {$ENDIF}; + +{* + * Set script to be used for text shaping by a font. + * + * Any value supplied here will override the global script set with the + * deprecated TTF_SetScript(). + * + * The supplied script value must be a null-terminated string of exactly four + * characters. + * + * If SDL_ttf was not built with HarfBuzz support, this function returns -1. + * + * \param font the font to specify a direction for. + * \param script null-terminated string of exactly 4 characters. + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL_ttf 2.20.0. + } +function TTF_SetFontScriptName(font: PTTF_Font; script: PAnsiChar): cint; cdecl; + external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontScriptName' {$ENDIF} {$ENDIF}; implementation -Procedure SDL_TTF_VERSION(Out X:TSDL_Version); +procedure SDL_TTF_VERSION(out X: TSDL_Version); begin x.major := SDL_TTF_MAJOR_VERSION; x.minor := SDL_TTF_MINOR_VERSION; x.patch := SDL_TTF_PATCHLEVEL; end; -function TTF_SetError(const fmt: PAnsiChar): cint32; cdecl; -begin - Result := SDL_SetError(fmt); -end; - -function TTF_GetError: PAnsiChar; cdecl; -begin - Result := SDL_GetError(); -end; - -function TTF_RenderText(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; -begin - Result := TTF_RenderText_Shaded(font, text, fg, bg); -end; - -function TTF_RenderUTF8(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface; +procedure TTF_VERSION(out X: TSDL_Version); begin - Result := TTF_RenderUTF8_Shaded(font, text, fg, bg); + SDL_TTF_VERSION(X); end; -function TTF_RenderUNICODE(font: PTTF_Font; text: pcuint16; fg, bg: TSDL_Color): PSDL_Surface; +function SDL_TTF_VERSION_ATLEAST(X, Y, Z: Integer): Boolean; begin - Result := TTF_RenderUNICODE_Shaded(font, text, fg, bg); + Result := (SDL_TTF_MAJOR_VERSION >= X) and + ((SDL_TTF_MAJOR_VERSION > X) or (SDL_TTF_MINOR_VERSION >= Y)) and + ((SDL_TTF_MAJOR_VERSION > X) or (SDL_TTF_MINOR_VERSION > Y) or (SDL_TTF_PATCHLEVEL >= Z)); end; end. diff --git a/units/sdlatomic.inc b/units/sdlatomic.inc new file mode 100644 index 00000000..d380ed40 --- /dev/null +++ b/units/sdlatomic.inc @@ -0,0 +1,109 @@ +// from SDL_atomic.h + +{** + * Atomic locks are efficient spinlocks using CPU instructions, + * but are vulnerable to starvation and can spin forever if a thread + * holding a lock has been terminated. For this reason you should + * minimize the code executed inside an atomic lock and never do + * expensive things like API or system calls while holding them. + * + * The atomic locks are not safe to lock recursively. + *} +type + PPSDL_SpinLock = ^PSDL_SpinLock; + PSDL_SpinLock = ^TSDL_SpinLock; + TSDL_SpinLock = type cint; + +{** + * Try to lock a spin lock by setting it to a non-zero value. + *} +function SDL_AtomicTryLock(lock: PSDL_SpinLock): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicTryLock' {$ENDIF} {$ENDIF}; + +{** + * Lock a spin lock by setting it to a non-zero value. + *} +function SDL_AtomicLock(lock: PSDL_SpinLock): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicLock' {$ENDIF} {$ENDIF}; + +{** + * Unlock a spin lock by setting it to 0. + * + * Always returns immediately. + *} +procedure SDL_AtomicUnlock(lock: PSDL_SpinLock); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicUnlock' {$ENDIF} {$ENDIF}; + +{** + * The compiler barrier prevents the compiler from reordering + * reads and writes to globally visible variables across the call. + *} +procedure SDL_CompilerBarrier(); + +type + {** + * A type representing an atomic integer value. It is a record + * so people don't accidentally use numeric operations on it. + *} + PPSDL_Atomic = ^PSDL_Atomic; + PSDL_Atomic = ^TSDL_Atomic; + TSDL_Atomic = record + Value: cint + end; + +{** + * Set an atomic variable to a new value if it is currently an old value. + *} +function SDL_AtomicCAS(atomic: PSDL_Atomic; oldValue, newValue: cint): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicCAS' {$ENDIF} {$ENDIF}; + +{** + * Set an atomic variable to a new value and return the old one. + * + * This function also acts as a full memory barrier. + *} +function SDL_AtomicSet(atomic: PSDL_Atomic; value: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicSet' {$ENDIF} {$ENDIF}; + +{** + * Get the value of an atomic variable. + *} +function SDL_AtomicGet(atomic: PSDL_Atomic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicGet' {$ENDIF} {$ENDIF}; + +{** + * Add to an atomic variable, and return the old value. + * + * This function also acts as a full memory barrier. + *} +function SDL_AtomicAdd(atomic: PSDL_Atomic; value: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicAdd' {$ENDIF} {$ENDIF}; + +{** + * Increment an atomic variable used as a reference count. + *} +function SDL_AtomicIncRef(atomic: PSDL_Atomic): cint; +{** + * Decrement an atomic variable used as a reference count + * and check if it reached zero after decrementing. + *} +function SDL_AtomicDecRef(atomic: PSDL_Atomic): Boolean; + +{** + * Set a pointer to a new value if it is currently an old value. + *} +function SDL_AtomicCASPtr(ptr: PPointer; oldValue, newValue: Pointer): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicCASPtr' {$ENDIF} {$ENDIF}; + +{** + * Set a pointer to a new value atomically, and return the old value. + *} +function SDL_AtomicSetPtr(ptr: PPointer; value: Pointer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicSetPtr' {$ENDIF} {$ENDIF}; + +{** + * Get the value of a pointer atomically. + *} +function SDL_AtomicGetPtr(ptr: PPointer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AtomicGetPtr' {$ENDIF} {$ENDIF}; + diff --git a/units/sdlaudio.inc b/units/sdlaudio.inc index 27fc1855..ce3ba352 100644 --- a/units/sdlaudio.inc +++ b/units/sdlaudio.inc @@ -19,6 +19,8 @@ * There are macros in SDL 2.0 and later to query these bits. *} type + PPSDL_AudioFormat = ^PSDL_AudioFormat; + PSDL_AudioFormat = ^TSDL_AudioFormat; TSDL_AudioFormat = cuint16; {** @@ -104,54 +106,88 @@ const {*Audio flags*} {** - * This function is called when the audio device needs more data. - * - * userdata An application-specific parameter saved in - * the SDL_AudioSpec structure - * stream A pointer to the audio data buffer. - * len The length of that buffer in bytes. - * - * Once the callback returns, the buffer will no longer be valid. - * Stereo samples are stored in a LRLRLR ordering. + * This function is called when the audio device needs more data. + * + * \param userdata An application-specific parameter saved in + * the SDL_AudioSpec structure + * \param stream A pointer to the audio data buffer. + * \param len The length of that buffer in bytes. + * + * Once the callback returns, the buffer will no longer be valid. + * Stereo samples are stored in a LRLRLR ordering. + * + * You can choose to avoid callbacks and use SDL_QueueAudio() instead, if + * you like. Just open your audio device with a NULL callback. *} type - TSDL_AudioCallback = procedure(userdata: Pointer; stream: pcuint8; len: cint) cdecl; + PPSDL_AudioCallback = ^PSDL_AudioCallback; + PSDL_AudioCallback = ^TSDL_AudioCallback; + TSDL_AudioCallback = procedure(userdata: Pointer; stream: pcuint8; len: cint); cdecl; {** * The calculated values in this structure are calculated by SDL_OpenAudio(). + * + * For multi-channel audio, the default SDL channel mapping is: + * 2: FL FR (stereo) + * 3: FL FR LFE (2.1 surround) + * 4: FL FR BL BR (quad) + * 5: FL FR LFE BL BR (4.1 surround) + * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) + * 7: FL FR FC LFE BC SL SR (6.1 surround) + * 8: FL FR FC LFE BL BR SL SR (7.1 surround) *} type + PPSDL_AudioSpec = ^PSDL_AudioSpec; PSDL_AudioSpec = ^TSDL_AudioSpec; TSDL_AudioSpec = record - freq: cint; {**< DSP frequency -- samples per second *} - format: TSDL_AudioFormat; {**< Audio data format *} + freq: cint; {**< DSP frequency -- samples per second *} + format: TSDL_AudioFormat; {**< Audio data format *} channels: cuint8; {**< Number of channels: 1 mono, 2 stereo *} silence: cuint8; {**< Audio buffer silence value (calculated) *} - samples: cuint16; {**< Audio buffer size in samples (power of 2) *} + samples: cuint16; {**< Audio buffer size in sample FRAMES (total samples divided by channel count) *} padding: cuint16; {**< Necessary for some compile environments *} size: cuint32; {**< Audio buffer size in bytes (calculated) *} - callback: TSDL_AudioCallback; - userdata: Pointer; + callback: TSDL_AudioCallback; {**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). *} + userdata: Pointer; {**< Userdata passed to callback (ignored for NULL callbacks). *} end; + {** + * \brief Upper limit of filters in SDL_AudioCVT + * + * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is + * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, + * one of which is the terminating NULL pointer. + *} +const + SDL_AUDIOCVT_MAX_FILTERS = 9; + +type + PPSDL_AudioCVT = ^PSDL_AudioCVT; PSDL_AudioCVT = ^TSDL_AudioCVT; - TSDL_AudioFilter = procedure(cvt: PSDL_AudioCVT; format: TSDL_AudioFormat) cdecl; + TSDL_AudioFilter = procedure(cvt: PSDL_AudioCVT; format: TSDL_AudioFormat); cdecl; {** - * A structure to hold a set of audio conversion filters and buffers. + * \struct SDL_AudioCVT + * \brief A structure to hold a set of audio conversion filters and buffers. + * + * Note that various parts of the conversion pipeline can take advantage + * of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require + * you to pass it aligned data, but can possibly run much faster if you + * set both its (buf) field to a pointer that is aligned to 16 bytes, and its + * (len) field to something that's a multiple of 16, if possible. *} TSDL_AudioCVT = record needed: cint; {**< Set to 1 if conversion possible *} - src_format: TSDL_AudioFormat; {**< Source audio format *} - dst_format: TSDL_AudioFormat; {**< Target audio format *} - rate_incr: Double; {**< Rate conversion increment *} - buf: pcuint8; {**< Buffer to hold entire audio data *} - len: cint; {**< Length of original audio buffer *} - len_cvt: cint; {**< Length of converted audio buffer *} - len_mult: cint; {**< buffer must be len*len_mult big *} - len_ratio: Double; {**< Given len, final size is len*len_ratio *} - filters: array[0..9] of TSDL_AudioFilter; {**< Filter list *} - filter_index: cint; {**< Current audio conversion function *} + src_format: TSDL_AudioFormat; {**< Source audio format *} + dst_format: TSDL_AudioFormat; {**< Target audio format *} + rate_incr: cdouble; {**< Rate conversion increment *} + buf: pcuint8; {**< Buffer to hold entire audio data *} + len: cint; {**< Length of original audio buffer *} + len_cvt: cint; {**< Length of converted audio buffer *} + len_mult: cint; {**< buffer must be len*len_mult big *} + len_ratio: cdouble; {**< Given len, final size is len*len_ratio *} + filters: array[0..SDL_AUDIOCVT_MAX_FILTERS] of TSDL_AudioFilter; {**< NULL-terminated list of filter functions *} + filter_index: cint; {**< Current audio conversion function *} end; @@ -164,8 +200,50 @@ type * order that they are normally initialized by default. *} -function SDL_GetNumAudioDrivers: cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumAudioDrivers' {$ENDIF} {$ENDIF}; -function SDL_GetAudioDriver(index: cint): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDriver' {$ENDIF} {$ENDIF}; + {** + * Use this function to get the number of built-in audio drivers. + * + * This function returns a hardcoded number. This never returns a negative + * value; if there are no drivers compiled into this build of SDL, this + * function returns zero. The presence of a driver in this list does not mean + * it will function, it just means SDL is capable of interacting with that + * interface. For example, a build of SDL might have esound support, but if + * there's no esound server available, SDL's esound driver would fail if used. + * + * By default, SDL tries all drivers, in its preferred order, until one is + * found to be usable. + * + * \returns the number of built-in audio drivers. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetAudioDriver + *} +function SDL_GetNumAudioDrivers: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumAudioDrivers' {$ENDIF} {$ENDIF}; + +{** + * Use this function to get the name of a built in audio driver. + * + * The list of audio drivers is given in the order that they are normally + * initialized by default; the drivers that seem more reasonable to choose + * first (as far as the SDL developers believe) are earlier in the list. + * + * The names of drivers are all simple, low-ASCII identifiers, like "alsa", + * "coreaudio" or "xaudio2". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of the audio driver; the value ranges from 0 to + * SDL_GetNumAudioDrivers() - 1 + * \returns the name of the audio driver at the requested index, or NULL if an + * invalid index was specified. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetNumAudioDrivers + *} +function SDL_GetAudioDriver(index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDriver' {$ENDIF} {$ENDIF}; {** * Initialization and cleanup @@ -174,59 +252,108 @@ function SDL_GetAudioDriver(index: cint): PAnsiChar cdecl; external SDL_LibName * you have a specific need to specify the audio driver you want to * use. You should normally use SDL_Init() or SDL_InitSubSystem(). *} - -function SDL_AudioInit(driver_name: PAnsiChar): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioInit' {$ENDIF} {$ENDIF}; -procedure SDL_AudioQuit cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioQuit' {$ENDIF} {$ENDIF}; - {** - * This function returns the name of the current audio driver, or NULL - * if no driver has been initialized. - *} -function SDL_GetCurrentAudioDriver: PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCurrentAudioDriver' {$ENDIF} {$ENDIF}; +{** + * Use this function to initialize a particular audio driver. + * + * This function is used internally, and should not be used unless you have a + * specific need to designate the audio driver you want to use. You should + * normally use SDL_Init() or SDL_InitSubSystem(). + * + * \param driver_name the name of the desired audio driver + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AudioQuit + *} +function SDL_AudioInit(driver_name: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioInit' {$ENDIF} {$ENDIF}; + +{** + * Use this function to shut down audio if you initialized it with + * SDL_AudioInit(). + * + * This function is used internally, and should not be used unless you have a + * specific need to specify the audio driver you want to use. You should + * normally use SDL_Quit() or SDL_QuitSubSystem(). + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AudioInit + *} +procedure SDL_AudioQuit; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioQuit' {$ENDIF} {$ENDIF}; {** - * This function opens the audio device with the desired parameters, and - * returns 0 if successful, placing the actual hardware parameters in the - * structure pointed to by obtained. If obtained is NULL, the audio - * data passed to the callback function will be guaranteed to be in the - * requested format, and will be automatically converted to the hardware - * audio format if necessary. This function returns -1 if it failed - * to open the audio device, or couldn't set up the audio thread. - * - * When filling in the desired audio spec structure, - * - desired->freq should be the desired audio frequency in samples-per- - * second. - * - desired->format should be the desired audio format. - * - desired->samples is the desired size of the audio buffer, in - * samples. This number should be a power of two, and may be adjusted by - * the audio driver to a value more suitable for the hardware. Good values - * seem to range between 512 and 8096 inclusive, depending on the - * application and CPU speed. Smaller values yield faster response time, - * but can lead to underflow if the application is doing heavy processing - * and cannot fill the audio buffer in time. A stereo sample consists of - * both right and left channels in LR ordering. - * Note that the number of samples is directly related to time by the - * following formula: ms := (samples*1000)/freq; - * - desired->size is the size in bytes of the audio buffer, and is - * calculated by SDL_OpenAudio(). - * - desired->silence is the value used to set the buffer to silence, - * and is calculated by SDL_OpenAudio(). - * - desired->callback should be set to a function that will be called - * when the audio device is ready for more data. It is passed a pointer - * to the audio buffer, and the length in bytes of the audio buffer. - * This function usually runs in a separate thread, and so you should - * protect data structures that it accesses by calling SDL_LockAudio() - * and SDL_UnlockAudio() in your code. - * - desired->userdata is passed as the first parameter to your callback - * function. - * - * The audio device starts out playing silence when it's opened, and should - * be enabled for playing by calling SDL_PauseAudio(0) when you are ready - * for your audio callback function to be called. Since the audio driver - * may modify the requested size of the audio buffer, you should allocate - * any local mixing buffers after you open the audio device. - *} -function SDL_OpenAudio(desired: PSDL_AudioSpec; obtained: PSDL_AudioSpec): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenAudio' {$ENDIF} {$ENDIF}; + * Get the name of the current audio driver. + * + * The returned string points to internal static memory and thus never becomes + * invalid, even if you quit the audio subsystem and initialize a new driver + * (although such a case would return a different static string from another + * call to this function, of course). As such, you should not modify or free + * the returned string. + * + * \returns the name of the current audio driver or NULL if no driver has been + * initialized. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AudioInit + *} +function SDL_GetCurrentAudioDriver: PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCurrentAudioDriver' {$ENDIF} {$ENDIF}; + +{** + * This function is a legacy means of opening the audio device. + * + * This function remains for compatibility with SDL 1.2, but also because it's + * slightly easier to use than the new functions in SDL 2.0. The new, more + * powerful, and preferred way to do this is SDL_OpenAudioDevice(). + * + * This function is roughly equivalent to: + * + * ```c + * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE); + * ``` + * + * With two notable exceptions: + * + * - If `obtained` is NULL, we use `desired` (and allow no changes), which + * means desired will be modified to have the correct values for silence, + * etc, and SDL will convert any differences between your app's specific + * request and the hardware behind the scenes. + * - The return value is always success or failure, and not a device ID, which + * means you can only have one device open at a time with this function. + * + * \param desired an SDL_AudioSpec structure representing the desired output + * format. Please refer to the SDL_OpenAudioDevice + * documentation for details on how to prepare this structure. + * \param obtained an SDL_AudioSpec structure filled in with the actual + * parameters, or NULL. + * \returns 0 if successful, placing the actual hardware parameters in the + * structure pointed to by `obtained`. + * + * If `obtained` is NULL, the audio data passed to the callback + * function will be guaranteed to be in the requested format, and + * will be automatically converted to the actual hardware audio + * format if necessary. If `obtained` is NULL, `desired` will have + * fields modified. + * + * This function returns a negative error code on failure to open the + * audio device or failure to set up the audio thread; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CloseAudio + * \sa SDL_LockAudio + * \sa SDL_PauseAudio + * \sa SDL_UnlockAudio + *} +function SDL_OpenAudio(desired: PSDL_AudioSpec; obtained: PSDL_AudioSpec): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenAudio' {$ENDIF} {$ENDIF}; {** * SDL Audio Device IDs. @@ -238,55 +365,261 @@ function SDL_OpenAudio(desired: PSDL_AudioSpec; obtained: PSDL_AudioSpec): cint * specific, or capture devices. *} type + PPSDL_AudioDeviceID = ^PSDL_AudioDeviceID; + PSDL_AudioDeviceID = ^TSDL_AudioDeviceID; TSDL_AudioDeviceID = cuint32; - {** - * Get the number of available devices exposed by the current driver. - * Only valid after a successfully initializing the audio subsystem. - * Returns -1 if an explicit list of devices can't be determined; this is - * not an error. For example, if SDL is set up to talk to a remote audio - * server, it can't list every one available on the Internet, but it will - * still allow a specific host to be specified to SDL_OpenAudioDevice(). - * - * In many common cases, when this function returns a value <= 0, it can still - * successfully open the default device (NULL for first argument of - * SDL_OpenAudioDevice()). - *} -function SDL_GetNumAudioDevices(iscapture: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumAudioDevices' {$ENDIF} {$ENDIF}; +{** + * Get the number of built-in audio devices. + * + * This function is only valid after successfully initializing the audio + * subsystem. + * + * Note that audio capture support is not implemented as of SDL 2.0.4, so the + * `iscapture` parameter is for future expansion and should always be zero for + * now. + * + * This function will return -1 if an explicit list of devices can't be + * determined. Returning -1 is not an error. For example, if SDL is set up to + * talk to a remote audio server, it can't list every one available on the + * Internet, but it will still allow a specific host to be specified in + * SDL_OpenAudioDevice(). + * + * In many common cases, when this function returns a value <= 0, it can still + * successfully open the default device (NULL for first argument of + * SDL_OpenAudioDevice()). + * + * This function may trigger a complete redetect of available hardware. It + * should not be called for each iteration of a loop, but rather once at the + * start of a loop: + * + * ```c + * // Don't do this: + * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++) + * + * // do this instead: + * const int count = SDL_GetNumAudioDevices(0); + * for (int i = 0; i < count; ++i) do_something_here(); + * ``` + * + * \param iscapture zero to request playback devices, non-zero to request + * recording devices + * \returns the number of available devices exposed by the current driver or + * -1 if an explicit list of devices can't be determined. A return + * value of -1 does not necessarily mean an error condition. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetAudioDeviceName + * \sa SDL_OpenAudioDevice + *} +function SDL_GetNumAudioDevices(iscapture: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumAudioDevices' {$ENDIF} {$ENDIF}; - {** - * Get the human-readable name of a specific audio device. - * Must be a value between 0 and (number of audio devices-1). - * Only valid after a successfully initializing the audio subsystem. - * The values returned by this function reflect the latest call to - * SDL_GetNumAudioDevices(); recall that function to redetect available - * hardware. - * - * The string returned by this function is UTF-8 encoded, read-only, and - * managed internally. You are not to free it. If you need to keep the - * string for any length of time, you should make your own copy of it, as it - * will be invalid next time any of several other SDL functions is called. - *} -function SDL_GetAudioDeviceName(index: cint; iscapture: cint): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDeviceName' {$ENDIF} {$ENDIF}; +{** + * Get the human-readable name of a specific audio device. + * + * This function is only valid after successfully initializing the audio + * subsystem. The values returned by this function reflect the latest call to + * SDL_GetNumAudioDevices(); re-call that function to redetect available + * hardware. + * + * The string returned by this function is UTF-8 encoded, read-only, and + * managed internally. You are not to free it. If you need to keep the string + * for any length of time, you should make your own copy of it, as it will be + * invalid next time any of several other SDL functions are called. + * + * \param index the index of the audio device; valid values range from 0 to + * SDL_GetNumAudioDevices() - 1 + * \param iscapture non-zero to query the list of recording devices, zero to + * query the list of output devices. + * \returns the name of the audio device at the requested index, or NULL on + * error. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetNumAudioDevices + * \sa SDL_GetDefaultAudioInfo + *} +function SDL_GetAudioDeviceName(index: cint; iscapture: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDeviceName' {$ENDIF} {$ENDIF}; - {** - * Open a specific audio device. Passing in a device name of NULL requests - * the most reasonable default (and is equivalent to calling SDL_OpenAudio()). - * - * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but - * some drivers allow arbitrary and driver-specific strings, such as a - * hostname/IP address for a remote audio server, or a filename in the - * diskaudio driver. - * - * 0 on error, a valid device ID that is >= 2 on success. - * - * SDL_OpenAudio(), unlike this function, always acts on device ID 1. - *} +{* + * Get the preferred audio format of a specific audio device. + * + * This function is only valid after a successfully initializing the audio + * subsystem. The values returned by this function reflect the latest call to + * SDL_GetNumAudioDevices(); re-call that function to redetect available + * hardware. + * + * `spec` will be filled with the sample rate, sample format, and channel + * count. + * + * \param index the index of the audio device; valid values range from 0 to + * SDL_GetNumAudioDevices() - 1 + * \param iscapture non-zero to query the list of recording devices, zero to + * query the list of output devices. + * \param spec The SDL_AudioSpec to be initialized by this function. + * \returns 0 on success, nonzero on error + * + * \since This function is available since SDL 2.0.16. + * + * \sa SDL_GetNumAudioDevices + * \sa SDL_GetDefaultAudioInfo + } +function SDL_GetAudioDeviceSpec(index: cint; iscapture: cint; spec: PSDL_AudioSpec): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDeviceSpec' {$ENDIF} {$ENDIF}; + +{* + * Get the name and preferred format of the default audio device. + * + * Some (but not all!) platforms have an isolated mechanism to get information + * about the "default" device. This can actually be a completely different + * device that's not in the list you get from SDL_GetAudioDeviceSpec(). It can + * even be a network address! (This is discussed in SDL_OpenAudioDevice().) + * + * As a result, this call is not guaranteed to be performant, as it can query + * the sound server directly every time, unlike the other query functions. You + * should call this function sparingly! + * + * `spec` will be filled with the sample rate, sample format, and channel + * count, if a default device exists on the system. If `name` is provided, + * will be filled with either a dynamically-allocated UTF-8 string or nil. + * + * \param name A pointer to be filled with the name of the default device (can + * be nil). Please call SDL_free() when you are done with this + * pointer! + * \param spec The SDL_AudioSpec to be initialized by this function. + * \param iscapture non-zero to query the default recording device, zero to + * query the default output device. + * \returns 0 on success, nonzero on error + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GetAudioDeviceName + * \sa SDL_GetAudioDeviceSpec + * \sa SDL_OpenAudioDevice + } +function SDL_GetDefaultAudioInfo(name: PPAnsiChar; spec: PSDL_AudioSpec; iscapture: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDefaultAudioInfo' {$ENDIF} {$ENDIF}; + +{** + * Open a specific audio device. + * + * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such, + * this function will never return a 1 so as not to conflict with the legacy + * function. + * + * Please note that SDL 2.0 before 2.0.5 did not support recording; as such, + * this function would fail if `iscapture` was not zero. Starting with SDL + * 2.0.5, recording is implemented and this value can be non-zero. + * + * Passing in a `device` name of NULL requests the most reasonable default + * (and is equivalent to what SDL_OpenAudio() does to choose a device). The + * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but + * some drivers allow arbitrary and driver-specific strings, such as a + * hostname/IP address for a remote audio server, or a filename in the + * diskaudio driver. + * + * An opened audio device starts out paused, and should be enabled for playing + * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio + * callback function to be called. Since the audio driver may modify the + * requested size of the audio buffer, you should allocate any local mixing + * buffers after you open the audio device. + * + * The audio callback runs in a separate thread in most cases; you can prevent + * race conditions between your callback and other threads without fully + * pausing playback with SDL_LockAudioDevice(). For more information about the + * callback, see SDL_AudioSpec. + * + * Managing the audio spec via 'desired' and 'obtained': + * + * When filling in the desired audio spec structure: + * + * - `desired->freq` should be the frequency in sample-frames-per-second (Hz). + * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc). + * - `desired->samples` is the desired size of the audio buffer, in _sample + * frames_ (with stereo output, two samples--left and right--would make a + * single sample frame). This number should be a power of two, and may be + * adjusted by the audio driver to a value more suitable for the hardware. + * Good values seem to range between 512 and 8096 inclusive, depending on + * the application and CPU speed. Smaller values reduce latency, but can + * lead to underflow if the application is doing heavy processing and cannot + * fill the audio buffer in time. Note that the number of sample frames is + * directly related to time by the following formula: `ms = + * (sampleframes*1000)/freq` + * - `desired->size` is the size in _bytes_ of the audio buffer, and is + * calculated by SDL_OpenAudioDevice(). You don't initialize this. + * - `desired->silence` is the value used to set the buffer to silence, and is + * calculated by SDL_OpenAudioDevice(). You don't initialize this. + * - `desired->callback` should be set to a function that will be called when + * the audio device is ready for more data. It is passed a pointer to the + * audio buffer, and the length in bytes of the audio buffer. This function + * usually runs in a separate thread, and so you should protect data + * structures that it accesses by calling SDL_LockAudioDevice() and + * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL + * pointer here, and call SDL_QueueAudio() with some frequency, to queue + * more audio samples to be played (or for capture devices, call + * SDL_DequeueAudio() with some frequency, to obtain audio samples). + * - `desired->userdata` is passed as the first parameter to your callback + * function. If you passed a NULL callback, this value is ignored. + * + * `allowed_changes` can have the following flags OR'd together: + * + * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE` + * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE` + * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE` + * - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE` + * - `SDL_AUDIO_ALLOW_ANY_CHANGE` + * + * These flags specify how SDL should behave when a device cannot offer a + * specific feature. If the application requests a feature that the hardware + * doesn't offer, SDL will always try to get the closest equivalent. + * + * For example, if you ask for float32 audio format, but the sound card only + * supports int16, SDL will set the hardware to int16. If you had set + * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained` + * structure. If that flag was *not* set, SDL will prepare to convert your + * callback's float32 audio to int16 before feeding it to the hardware and + * will keep the originally requested format in the `obtained` structure. + * + * The resulting audio specs, varying depending on hardware and on what + * changes were allowed, will then be written back to `obtained`. + * + * If your application can only handle one specific data format, pass a zero + * for `allowed_changes` and let SDL transparently handle any differences. + * + * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a + * driver-specific name as appropriate. NULL requests the most + * reasonable default device. + * \param iscapture non-zero to specify a device should be opened for + * recording, not playback + * \param desired an SDL_AudioSpec structure representing the desired output + * format; see SDL_OpenAudio() for more information + * \param obtained an SDL_AudioSpec structure filled in with the actual output + * format; see SDL_OpenAudio() for more information + * \param allowed_changes 0, or one or more flags OR'd together + * \returns a valid device ID that is > 0 on success or 0 on failure; call + * SDL_GetError() for more information. + * + * For compatibility with SDL 1.2, this will never return 1, since + * SDL reserves that ID for the legacy SDL_OpenAudio() function. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CloseAudioDevice + * \sa SDL_GetAudioDeviceName + * \sa SDL_LockAudioDevice + * \sa SDL_OpenAudio + * \sa SDL_PauseAudioDevice + * \sa SDL_UnlockAudioDevice + *} function SDL_OpenAudioDevice(device: PAnsiChar; iscapture: cint; desired: PSDL_AudioSpec; obtained: PSDL_AudioSpec; - allowed_changes: cint): TSDL_AudioDeviceID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenAudioDevice' {$ENDIF} {$ENDIF}; + allowed_changes: cint): TSDL_AudioDeviceID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenAudioDevice' {$ENDIF} {$ENDIF}; {** * Audio state @@ -295,12 +628,51 @@ function SDL_OpenAudioDevice(device: PAnsiChar; *} type - TSDL_AudioStatus = (SDL_AUDIO_STOPPED,SDL_AUDIO_PLAYING,SDL_AUDIO_PAUSED); + PPSDL_AudioStatus = ^PSDL_AudioStatus; + PSDL_AudioStatus = ^TSDL_AudioStatus; + TSDL_AudioStatus = type cint; + +const + SDL_AUDIO_STOPPED = TSDL_AudioStatus(0); + SDL_AUDIO_PLAYING = TSDL_AudioStatus(1); + SDL_AUDIO_PAUSED = TSDL_AudioStatus(2); + +{** + * This function is a legacy means of querying the audio device. + * + * New programs might want to use SDL_GetAudioDeviceStatus() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_GetAudioDeviceStatus(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio(). + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetAudioDeviceStatus + *} +function SDL_GetAudioStatus: TSDL_AudioStatus; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioStatus' {$ENDIF} {$ENDIF}; -function SDL_GetAudioStatus: TSDL_AudioStatus cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioStatus' {$ENDIF} {$ENDIF}; +{** + * Use this function to get the current audio state of an audio device. + * + * \param dev the ID of an audio device previously opened with + * SDL_OpenAudioDevice() + * \returns the SDL_AudioStatus of the specified audio device. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_PauseAudioDevice + *} +function SDL_GetAudioDeviceStatus(dev: TSDL_AudioDeviceID): TSDL_AudioStatus; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDeviceStatus' {$ENDIF} {$ENDIF}; -function SDL_GetAudioDeviceStatus(dev: TSDL_AudioDeviceID): TSDL_AudioStatus cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAudioDeviceStatus' {$ENDIF} {$ENDIF}; - {*Audio State*} +{*Audio State*} {** * Pause audio functions @@ -312,231 +684,625 @@ function SDL_GetAudioDeviceStatus(dev: TSDL_AudioDeviceID): TSDL_AudioStatus cde * Silence will be written to the audio device during the pause. *} -procedure SDL_PauseAudio(pause_on: cint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PauseAudio' {$ENDIF} {$ENDIF}; -procedure SDL_PauseAudioDevice(dev: TSDL_AudioDeviceID; pause_on: cint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PauseAudioDevice' {$ENDIF} {$ENDIF}; - {*Pause audio functions*} +{** + * This function is a legacy means of pausing the audio device. + * + * New programs might want to use SDL_PauseAudioDevice() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_PauseAudioDevice(1, pause_on); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \param pause_on non-zero to pause, 0 to unpause + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetAudioStatus + * \sa SDL_PauseAudioDevice + *} +procedure SDL_PauseAudio(pause_on: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PauseAudio' {$ENDIF} {$ENDIF}; + +{** + * Use this function to pause and unpause audio playback on a specified + * device. + * + * This function pauses and unpauses the audio callback processing for a given + * device. Newly-opened audio devices start in the paused state, so you must + * call this function with **pause_on**=0 after opening the specified audio + * device to start playing sound. This allows you to safely initialize data + * for your callback function after opening the audio device. Silence will be + * written to the audio device while paused, and the audio callback is + * guaranteed to not be called. Pausing one device does not prevent other + * unpaused devices from running their callbacks. + * + * Pausing state does not stack; even if you pause a device several times, a + * single unpause will start the device playing again, and vice versa. This is + * different from how SDL_LockAudioDevice() works. + * + * If you just need to protect a few variables from race conditions vs your + * callback, you shouldn't pause the audio device, as it will lead to dropouts + * in the audio playback. Instead, you should use SDL_LockAudioDevice(). + * + * \param dev a device opened by SDL_OpenAudioDevice() + * \param pause_on non-zero to pause, 0 to unpause + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LockAudioDevice + *} +procedure SDL_PauseAudioDevice(dev: TSDL_AudioDeviceID; pause_on: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PauseAudioDevice' {$ENDIF} {$ENDIF}; - {** - * This function loads a WAVE from the data source, automatically freeing - * that source if freesrc is non-zero. For example, to load a WAVE file, - * you could do: - * - * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); - * - * - * If this function succeeds, it returns the given SDL_AudioSpec, - * filled with the audio data format of the wave data, and sets - * *audio_buf to a malloc()'d buffer containing the audio data, - * and sets *audio_len to the length of that audio buffer, in bytes. - * You need to free the audio buffer with SDL_FreeWAV() when you are - * done with it. - * - * This function returns NULL and sets the SDL error message if the - * wave file cannot be opened, uses an unknown data format, or is - * corrupt. Currently raw and MS-ADPCM WAVE files are supported. - *} -function SDL_LoadWAV_RW(src: PSDL_RWops; freesrc: cint; spec: PSDL_AudioSpec; audio_buf: ppcuint8; audio_len: pcuint32): PSDL_AudioSpec cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadWAV_RW' {$ENDIF} {$ENDIF}; +{*Pause audio functions*} {** - * Loads a WAV from a file. - * Compatibility convenience function. - *} + * Load the audio data of a WAVE file into memory. + * + * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to + * be valid pointers. The entire data portion of the file is then loaded into + * memory and decoded if necessary. + * + * If `freesrc` is non-zero, the data source gets automatically closed and + * freed before the function returns. + * + * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and + * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and + * A-law and mu-law (8 bits). Other formats are currently unsupported and + * cause an error. + * + * If this function succeeds, the pointer returned by it is equal to `spec` + * and the pointer to the audio data allocated by the function is written to + * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec + * members `freq`, `channels`, and `format` are set to the values of the audio + * data in the buffer. The `samples` member is set to a sane default and all + * others are set to zero. + * + * It's necessary to use SDL_FreeWAV() to free the audio data returned in + * `audio_buf` when it is no longer used. + * + * Because of the underspecification of the .WAV format, there are many + * problematic files in the wild that cause issues with strict decoders. To + * provide compatibility with these files, this decoder is lenient in regards + * to the truncation of the file, the fact chunk, and the size of the RIFF + * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, + * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to + * tune the behavior of the loading process. + * + * Any file that is invalid (due to truncation, corruption, or wrong values in + * the headers), too big, or unsupported causes an error. Additionally, any + * critical I/O error from the data source will terminate the loading process + * with an error. The function returns NULL on error and in all cases (with + * the exception of `src` being NULL), an appropriate error message will be + * set. + * + * It is required that the data source supports seeking. + * + * Example: + * + * ```c + * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * ``` + * + * Note that the SDL_LoadWAV macro does this same thing for you, but in a less + * messy way: + * + * ```c + * SDL_LoadWAV("sample.wav", &spec, &buf, &len); + * ``` + * + * \param src The data source for the WAVE data + * \param freesrc If non-zero, SDL will _always_ free the data source + * \param spec An SDL_AudioSpec that will be filled in with the wave file's + * format details + * \param audio_buf A pointer filled with the audio data, allocated by the + * function. + * \param audio_len A pointer filled with the length of the audio data buffer + * in bytes + * \returns This function, if successfully called, returns `spec`, which will + * be filled with the audio data format of the wave source data. + * `audio_buf` will be filled with a pointer to an allocated buffer + * containing the audio data, and `audio_len` is filled with the + * length of that audio buffer in bytes. + * + * This function returns NULL if the .WAV file cannot be opened, uses + * an unknown data format, or is corrupt; call SDL_GetError() for + * more information. + * + * When the application is done with the data returned in + * `audio_buf`, it should call SDL_FreeWAV() to dispose of it. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_FreeWAV + * \sa SDL_LoadWAV + *} +function SDL_LoadWAV_RW(src: PSDL_RWops; + freesrc: cint; + spec: PSDL_AudioSpec; + audio_buf: ppcuint8; + audio_len: pcuint32): PSDL_AudioSpec; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadWAV_RW' {$ENDIF} {$ENDIF}; - function SDL_LoadWAV(_file: PAnsiChar; spec: PSDL_AudioSpec; audio_buf: ppcuint8; audio_len: pcuint32): PSDL_AudioSpec; +{** + * Loads a WAV from a file. + * Compatibility convenience function. + *} +function SDL_LoadWAV(file_: PAnsiChar; spec: PSDL_AudioSpec; audio_buf: ppcuint8; audio_len: pcuint32): PSDL_AudioSpec; - {** - * This function frees data previously allocated with SDL_LoadWAV_RW() - *} - procedure SDL_FreeWAV(audio_buf: pcuint8) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeWAV' {$ENDIF} {$ENDIF}; +{** + * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW(). + * + * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW() + * its data can eventually be freed with SDL_FreeWAV(). It is safe to call + * this function with a NULL pointer. + * + * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or + * SDL_LoadWAV_RW() + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadWAV + * \sa SDL_LoadWAV_RW + *} +procedure SDL_FreeWAV(audio_buf: pcuint8); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeWAV' {$ENDIF} {$ENDIF}; - {** - * This function takes a source format and rate and a destination format - * and rate, and initializes the cvt structure with information needed - * by SDL_ConvertAudio() to convert a buffer of audio data from one format - * to the other. - * - * -1 if the format conversion is not supported, 0 if there's - * no conversion needed, or 1 if the audio filter is set up. - *} +{** + * Initialize an SDL_AudioCVT structure for conversion. + * + * Before an SDL_AudioCVT structure can be used to convert audio data it must + * be initialized with source and destination information. + * + * This function will zero out every field of the SDL_AudioCVT, so it must be + * called before the application fills in the final buffer information. + * + * Once this function has returned successfully, and reported that a + * conversion is necessary, the application fills in the rest of the fields in + * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate, + * and then can call SDL_ConvertAudio() to complete the conversion. + * + * \param cvt an SDL_AudioCVT structure filled in with audio conversion + * information + * \param src_format the source format of the audio data; for more info see + * SDL_AudioFormat + * \param src_channels the number of channels in the source + * \param src_rate the frequency (sample-frames-per-second) of the source + * \param dst_format the destination format of the audio data; for more info + * see SDL_AudioFormat + * \param dst_channels the number of channels in the destination + * \param dst_rate the frequency (sample-frames-per-second) of the destination + * \returns 1 if the audio filter is prepared, 0 if no conversion is needed, + * or a negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_ConvertAudio + *} function SDL_BuildAudioCVT(cvt: PSDL_AudioCVT; src_format: TSDL_AudioFormat; src_channels: cuint8; src_rate: cint; dst_format: TSDL_AudioFormat; dst_channels: cuint8; - dst_rate: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BuildAudioCVT' {$ENDIF} {$ENDIF}; + dst_rate: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BuildAudioCVT' {$ENDIF} {$ENDIF}; {** - * Once you have initialized the cvt structure using SDL_BuildAudioCVT(), - * created an audio buffer cvt->buf, and filled it with cvt->len bytes of - * audio data in the source format, this function will convert it in-place - * to the desired format. - * - * The data conversion may expand the size of the audio data, so the buffer - * cvt->buf should be allocated after the cvt structure is initialized by - * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long. + * Convert audio data to a desired audio format. + * + * This function does the actual audio data conversion, after the application + * has called SDL_BuildAudioCVT() to prepare the conversion information and + * then filled in the buffer details. + * + * Once the application has initialized the `cvt` structure using + * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio + * data in the source format, this function will convert the buffer, in-place, + * to the desired format. + * + * The data conversion may go through several passes; any given pass may + * possibly temporarily increase the size of the data. For example, SDL might + * expand 16-bit data to 32 bits before resampling to a lower frequency, + * shrinking the data size after having grown it briefly. Since the supplied + * buffer will be both the source and destination, converting as necessary + * in-place, the application must allocate a buffer that will fully contain + * the data during its largest conversion pass. After SDL_BuildAudioCVT() + * returns, the application should set the `cvt->len` field to the size, in + * bytes, of the source data, and allocate a buffer that is `cvt->len * + * cvt->len_mult` bytes long for the `buf` field. + * + * The source data should be copied into this buffer before the call to + * SDL_ConvertAudio(). Upon successful return, this buffer will contain the + * converted audio, and `cvt->len_cvt` will be the size of the converted data, + * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once + * this function returns. + * + * \param cvt an SDL_AudioCVT structure that was previously set up by + * SDL_BuildAudioCVT(). + * \returns 0 if the conversion was completed successfully or a negative error + * code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_BuildAudioCVT *} -function SDL_ConvertAudio(cvt: PSDL_AudioCVT): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ConvertAudio' {$ENDIF} {$ENDIF}; +function SDL_ConvertAudio(cvt: PSDL_AudioCVT): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ConvertAudio' {$ENDIF} {$ENDIF}; + +{ SDL_AudioStream is a new audio conversion interface. + The benefits vs SDL_AudioCVT: + - it can handle resampling data in chunks without generating + artifacts, when it doesn't have the complete buffer available. + - it can handle incoming data in any variable size. + - You push data as you have it, and pull it when you need it + } +{ this is opaque to the outside world. } +type + PSDL_AudioStream = type Pointer; + +{* + * Create a new audio stream. + * + * \param src_format The format of the source audio + * \param src_channels The number of channels of the source audio + * \param src_rate The sampling rate of the source audio + * \param dst_format The format of the desired audio output + * \param dst_channels The number of channels of the desired audio output + * \param dst_rate The sampling rate of the desired audio output + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + } +function SDL_NewAudioStream(src_format: TSDL_AudioFormat; src_channels: cuint8; src_rate: cint; dst_format: TSDL_AudioFormat; dst_channels: cuint8; + dst_rate: cint): PSDL_AudioStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_NewAudioStream' {$ENDIF} {$ENDIF}; + +{* + * Add data to be converted/resampled to the stream. + * + * \param stream The stream the audio data is being added to + * \param buf A pointer to the audio data to add + * \param len The number of bytes to write to the stream + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + } +function SDL_AudioStreamPut(stream: PSDL_AudioStream; buf: pointer; len: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioStreamPut' {$ENDIF} {$ENDIF}; + +{* + * Get converted/resampled data from the stream + * + * \param stream The stream the audio is being requested from + * \param buf A buffer to fill with audio data + * \param len The maximum number of bytes to fill + * \returns the number of bytes read from the stream, or -1 on error + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + } +function SDL_AudioStreamGet(stream: PSDL_AudioStream; buf: pointer; len: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioStreamGet' {$ENDIF} {$ENDIF}; + +{* + * Get the number of converted/resampled bytes available. + * + * The stream may be buffering data behind the scenes until it has enough to + * resample correctly, so this number might be lower than what you expect, or + * even be zero. Add more data or flush the stream if you need the data now. + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + } +function SDL_AudioStreamAvailable(stream: PSDL_AudioStream): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioStreamAvailable' {$ENDIF} {$ENDIF}; + +{* + * Tell the stream that you're done sending data, and anything being buffered + * should be converted/resampled and made available immediately. + * + * It is legal to add more data to a stream after flushing, but there will be + * audio gaps in the output. Generally this is intended to signal the end of + * input, so the complete output becomes available. + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + } +function SDL_AudioStreamFlush(stream: PSDL_AudioStream): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioStreamFlush' {$ENDIF} {$ENDIF}; + +{* + * Clear any pending data in the stream without converting it + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_FreeAudioStream + } +procedure SDL_AudioStreamClear(stream: PSDL_AudioStream); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioStreamClear' {$ENDIF} {$ENDIF}; + +{* + * Free an audio stream + * + * \since This function is available since SDL 2.0.7. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + } +procedure SDL_FreeAudioStream(stream: PSDL_AudioStream); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeAudioStream' {$ENDIF} {$ENDIF}; const SDL_MIX_MAXVOLUME = 128; - {** - * This takes two audio buffers of the playing audio format and mixes - * them, performing addition, volume adjustment, and overflow clipping. - * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME - * for full audio volume. Note this does not change hardware volume. - * This is provided for convenience -- you can mix your own audio data. - *} -procedure SDL_MixAudio(dst: pcuint8; src: pcuint8; len: cuint32; volume: cint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MixAudio' {$ENDIF} {$ENDIF}; +{** + * This function is a legacy means of mixing audio. + * + * This function is equivalent to calling... + * + * ```c + * SDL_MixAudioFormat(dst, src, format, len, volume); + * ``` + * + * ...where `format` is the obtained format of the audio device from the + * legacy SDL_OpenAudio() function. + * + * \param dst the destination for the mixed audio + * \param src the source audio buffer to be mixed + * \param len the length of the audio buffer in bytes + * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME + * for full audio volume + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_MixAudioFormat + *} +procedure SDL_MixAudio(dst: pcuint8; src: pcuint8; len: cuint32; volume: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MixAudio' {$ENDIF} {$ENDIF}; {** - * This works like SDL_MixAudio(), but you specify the audio format instead of - * using the format of audio device 1. Thus it can be used when no audio - * device is open at all. - *} -procedure SDL_MixAudioFormat(dst: pcuint8; src: pcuint8; format: TSDL_AudioFormat; len: cuint32; volume: cint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MixAudioFormat' {$ENDIF} {$ENDIF}; + * Mix audio data in a specified format. + * + * This takes an audio buffer `src` of `len` bytes of `format` data and mixes + * it into `dst`, performing addition, volume adjustment, and overflow + * clipping. The buffer pointed to by `dst` must also be `len` bytes of + * `format` data. + * + * This is provided for convenience -- you can mix your own audio data. + * + * Do not use this function for mixing together more than two streams of + * sample data. The output from repeated application of this function may be + * distorted by clipping, because there is no accumulator with greater range + * than the input (not to mention this being an inefficient way of doing it). + * + * It is a common misconception that this function is required to write audio + * data to an output stream in an audio callback. While you can do that, + * SDL_MixAudioFormat() is really only needed when you're mixing a single + * audio stream with a volume adjustment. + * + * \param dst the destination for the mixed audio + * \param src the source audio buffer to be mixed + * \param format the SDL_AudioFormat structure representing the desired audio + * format + * \param len the length of the audio buffer in bytes + * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME + * for full audio volume + * + * \since This function is available since SDL 2.0.0. + *} +procedure SDL_MixAudioFormat(dst: pcuint8; src: pcuint8; format: TSDL_AudioFormat; len: cuint32; volume: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MixAudioFormat' {$ENDIF} {$ENDIF}; {** - * Queue more audio on non-callback devices. - * - * SDL offers two ways to feed audio to the device: you can either supply a - * callback that SDL triggers with some frequency to obtain more audio - * (pull method), or you can supply no callback, and then SDL will expect - * you to supply data at regular intervals (push method) with this function. - * - * There are no limits on the amount of data you can queue, short of - * exhaustion of address space. Queued data will drain to the device as - * necessary without further intervention from you. If the device needs - * audio but there is not enough queued, it will play silence to make up - * the difference. This means you will have skips in your audio playback - * if you aren't routinely queueing sufficient data. - * - * This function copies the supplied data, so you are safe to free it when - * the function returns. This function is thread-safe, but queueing to the - * same device from two threads at once does not promise which buffer will - * be queued first. - * - * You may not queue audio on a device that is using an application-supplied - * callback; doing so returns an error. You have to use the audio callback - * or queue audio with this function, but not both. - * - * You should not call SDL_LockAudio() on the device before queueing; SDL - * handles locking internally for this function. - * - * \param dev The device ID to which we will queue audio. - * \param data The data to queue to the device for later playback. - * \param len The number of bytes (not samples!) to which (data) points. - * \return zero on success, -1 on error. - * - * \sa SDL_GetQueuedAudioSize - * \sa SDL_ClearQueuedAudio - *} -function SDL_QueueAudio(dev: TSDL_AudioDeviceID; data: Pointer; len: cuint32): cint32; cdecl; + * Queue more audio on non-callback devices. + * + * If you are looking to retrieve queued audio from a non-callback capture + * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return + * -1 to signify an error if you use it with capture devices. + * + * SDL offers two ways to feed audio to the device: you can either supply a + * callback that SDL triggers with some frequency to obtain more audio (pull + * method), or you can supply no callback, and then SDL will expect you to + * supply data at regular intervals (push method) with this function. + * + * There are no limits on the amount of data you can queue, short of + * exhaustion of address space. Queued data will drain to the device as + * necessary without further intervention from you. If the device needs audio + * but there is not enough queued, it will play silence to make up the + * difference. This means you will have skips in your audio playback if you + * aren't routinely queueing sufficient data. + * + * This function copies the supplied data, so you are safe to free it when the + * function returns. This function is thread-safe, but queueing to the same + * device from two threads at once does not promise which buffer will be + * queued first. + * + * You may not queue audio on a device that is using an application-supplied + * callback; doing so returns an error. You have to use the audio callback or + * queue audio with this function, but not both. + * + * You should not call SDL_LockAudio() on the device before queueing; SDL + * handles locking internally for this function. + * + * Note that SDL2 does not support planar audio. You will need to resample + * from planar audio formats into a non-planar one (see SDL_AudioFormat) + * before queuing audio. + * + * \param dev the device ID to which we will queue audio + * \param data the data to queue to the device for later playback + * \param len the number of bytes (not samples!) to which `data` points + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_ClearQueuedAudio + * \sa SDL_GetQueuedAudioSize + *} +function SDL_QueueAudio(dev: TSDL_AudioDeviceID; data: Pointer; len: cuint32): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_QueueAudio' {$ENDIF} {$ENDIF}; {** - * Dequeue more audio on non-callback devices. - * - * (If you are looking to queue audio for output on a non-callback playback - * device, you want SDL_QueueAudio() instead. This will always return 0 - * if you use it with playback devices.) - * - * SDL offers two ways to retrieve audio from a capture device: you can - * either supply a callback that SDL triggers with some frequency as the - * device records more audio data, (push method), or you can supply no - * callback, and then SDL will expect you to retrieve data at regular - * intervals (pull method) with this function. - * - * There are no limits on the amount of data you can queue, short of - * exhaustion of address space. Data from the device will keep queuing as - * necessary without further intervention from you. This means you will - * eventually run out of memory if you aren't routinely dequeueing data. - * - * Capture devices will not queue data when paused; if you are expecting - * to not need captured audio for some length of time, use - * SDL_PauseAudioDevice() to stop the capture device from queueing more - * data. This can be useful during, say, level loading times. When - * unpaused, capture devices will start queueing data from that point, - * having flushed any capturable data available while paused. - * - * This function is thread-safe, but dequeueing from the same device from - * two threads at once does not promise which thread will dequeued data - * first. - * - * You may not dequeue audio from a device that is using an - * application-supplied callback; doing so returns an error. You have to use - * the audio callback, or dequeue audio with this function, but not both. - * - * You should not call SDL_LockAudio() on the device before queueing; SDL - * handles locking internally for this function. - * - * \param dev The device ID from which we will dequeue audio. - * \param data A pointer into where audio data should be copied. - * \param len The number of bytes (not samples!) to which (data) points. - * \return number of bytes dequeued, which could be less than requested. - * - * \sa SDL_GetQueuedAudioSize - * \sa SDL_ClearQueuedAudio - *} -function SDL_DequeueAudio(dev: TSDL_AudioDeviceID; data: Pointer; len:Uint32):Uint32; cdecl; + * Dequeue more audio on non-callback devices. + * + * If you are looking to queue audio for output on a non-callback playback + * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always + * return 0 if you use it with playback devices. + * + * SDL offers two ways to retrieve audio from a capture device: you can either + * supply a callback that SDL triggers with some frequency as the device + * records more audio data, (push method), or you can supply no callback, and + * then SDL will expect you to retrieve data at regular intervals (pull + * method) with this function. + * + * There are no limits on the amount of data you can queue, short of + * exhaustion of address space. Data from the device will keep queuing as + * necessary without further intervention from you. This means you will + * eventually run out of memory if you aren't routinely dequeueing data. + * + * Capture devices will not queue data when paused; if you are expecting to + * not need captured audio for some length of time, use SDL_PauseAudioDevice() + * to stop the capture device from queueing more data. This can be useful + * during, say, level loading times. When unpaused, capture devices will start + * queueing data from that point, having flushed any capturable data available + * while paused. + * + * This function is thread-safe, but dequeueing from the same device from two + * threads at once does not promise which thread will dequeue data first. + * + * You may not dequeue audio from a device that is using an + * application-supplied callback; doing so returns an error. You have to use + * the audio callback, or dequeue audio with this function, but not both. + * + * You should not call SDL_LockAudio() on the device before dequeueing; SDL + * handles locking internally for this function. + * + * \param dev the device ID from which we will dequeue audio + * \param data a pointer into where audio data should be copied + * \param len the number of bytes (not samples!) to which (data) points + * \returns the number of bytes dequeued, which could be less than requested; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.5. + * + * \sa SDL_ClearQueuedAudio + * \sa SDL_GetQueuedAudioSize + *} +function SDL_DequeueAudio(dev: TSDL_AudioDeviceID; data: Pointer; len: cuint32): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DequeueAudio' {$ENDIF} {$ENDIF}; - {** - * Get the number of bytes of still-queued audio. - * - * This is the number of bytes that have been queued for playback with - * SDL_QueueAudio(), but have not yet been sent to the hardware. - * - * Once we've sent it to the hardware, this function can not decide the exact - * byte boundary of what has been played. It's possible that we just gave the - * hardware several kilobytes right before you called this function, but it - * hasn't played any of it yet, or maybe half of it, etc. - * - * You may not queue audio on a device that is using an application-supplied - * callback; calling this function on such a device always returns 0. - * You have to use the audio callback or queue audio with SDL_QueueAudio(), - * but not both. - * - * You should not call SDL_LockAudio() on the device before querying; SDL - * handles locking internally for this function. - * - * \param dev The device ID of which we will query queued audio size. - * \return Number of bytes (not samples!) of queued audio. - * - * \sa SDL_QueueAudio - * \sa SDL_ClearQueuedAudio - *} +{** + * Get the number of bytes of still-queued audio. + * + * For playback devices: this is the number of bytes that have been queued for + * playback with SDL_QueueAudio(), but have not yet been sent to the hardware. + * + * Once we've sent it to the hardware, this function can not decide the exact + * byte boundary of what has been played. It's possible that we just gave the + * hardware several kilobytes right before you called this function, but it + * hasn't played any of it yet, or maybe half of it, etc. + * + * For capture devices, this is the number of bytes that have been captured by + * the device and are waiting for you to dequeue. This number may grow at any + * time, so this only informs of the lower-bound of available data. + * + * You may not queue or dequeue audio on a device that is using an + * application-supplied callback; calling this function on such a device + * always returns 0. You have to use the audio callback or queue audio, but + * not both. + * + * You should not call SDL_LockAudio() on the device before querying; SDL + * handles locking internally for this function. + * + * \param dev the device ID of which we will query queued audio size + * \returns the number of bytes (not samples!) of queued audio. + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_ClearQueuedAudio + * \sa SDL_QueueAudio + * \sa SDL_DequeueAudio + *} function SDL_GetQueuedAudioSize(dev: TSDL_AudioDeviceID): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetQueuedAudioSize' {$ENDIF} {$ENDIF}; {** - * Drop any queued audio data waiting to be sent to the hardware. - * - * Immediately after this call, SDL_GetQueuedAudioSize() will return 0 and - * the hardware will start playing silence if more audio isn't queued. - * - * This will not prevent playback of queued audio that's already been sent - * to the hardware, as we can not undo that, so expect there to be some - * fraction of a second of audio that might still be heard. This can be - * useful if you want to, say, drop any pending music during a level change - * in your game. - * - * You may not queue audio on a device that is using an application-supplied - * callback; calling this function on such a device is always a no-op. - * You have to use the audio callback or queue audio with SDL_QueueAudio(), - * but not both. - * - * You should not call SDL_LockAudio() on the device before clearing the - * queue; SDL handles locking internally for this function. - * - * This function always succeeds and thus returns void. - * - * \param dev The device ID of which to clear the audio queue. - * - * \sa SDL_QueueAudio - * \sa SDL_GetQueuedAudioSize - *} + * Drop any queued audio data waiting to be sent to the hardware. + * + * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For + * output devices, the hardware will start playing silence if more audio isn't + * queued. For capture devices, the hardware will start filling the empty + * queue with new data if the capture device isn't paused. + * + * This will not prevent playback of queued audio that's already been sent to + * the hardware, as we can not undo that, so expect there to be some fraction + * of a second of audio that might still be heard. This can be useful if you + * want to, say, drop any pending music or any unprocessed microphone input + * during a level change in your game. + * + * You may not queue or dequeue audio on a device that is using an + * application-supplied callback; calling this function on such a device + * always returns 0. You have to use the audio callback or queue audio, but + * not both. + * + * You should not call SDL_LockAudio() on the device before clearing the + * queue; SDL handles locking internally for this function. + * + * This function always succeeds and thus returns void. + * + * \param dev the device ID of which to clear the audio queue + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_GetQueuedAudioSize + * \sa SDL_QueueAudio + * \sa SDL_DequeueAudio + *} procedure SDL_ClearQueuedAudio(dev: TSDL_AudioDeviceID); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ClearQueuedAudio' {$ENDIF} {$ENDIF}; @@ -549,20 +1315,144 @@ procedure SDL_ClearQueuedAudio(dev: TSDL_AudioDeviceID); cdecl; * function or you will cause deadlock. *} -procedure SDL_LockAudio cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockAudio' {$ENDIF} {$ENDIF}; -procedure SDL_LockAudioDevice(dev: TSDL_AudioDeviceID) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockAudioDevice' {$ENDIF} {$ENDIF}; -procedure SDL_UnlockAudio cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Unlock' {$ENDIF} {$ENDIF}; -procedure SDL_UnlockAudioDevice(dev: TSDL_AudioDeviceID) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockAudioDevice' {$ENDIF} {$ENDIF}; - {*Audio lock functions*} +{** + * This function is a legacy means of locking the audio device. + * + * New programs might want to use SDL_LockAudioDevice() instead. This function + * is equivalent to calling... + * + * ```c + * SDL_LockAudioDevice(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LockAudioDevice + * \sa SDL_UnlockAudio + * \sa SDL_UnlockAudioDevice + *} +procedure SDL_LockAudio; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockAudio' {$ENDIF} {$ENDIF}; + +{** + * Use this function to lock out the audio callback function for a specified + * device. + * + * The lock manipulated by these functions protects the audio callback + * function specified in SDL_OpenAudioDevice(). During a + * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed + * that the callback function for that device is not running, even if the + * device is not paused. While a device is locked, any other unpaused, + * unlocked devices may still run their callbacks. + * + * Calling this function from inside your audio callback is unnecessary. SDL + * obtains this lock before calling your function, and releases it when the + * function returns. + * + * You should not hold the lock longer than absolutely necessary. If you hold + * it too long, you'll experience dropouts in your audio playback. Ideally, + * your application locks the device, sets a few variables and unlocks again. + * Do not do heavy work while holding the lock for a device. + * + * It is safe to lock the audio device multiple times, as long as you unlock + * it an equivalent number of times. The callback will not run until the + * device has been unlocked completely in this way. If your application fails + * to unlock the device appropriately, your callback will never run, you might + * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably + * deadlock. + * + * Internally, the audio device lock is a mutex; if you lock from two threads + * at once, not only will you block the audio callback, you'll block the other + * thread. + * + * \param dev the ID of the device to be locked + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_UnlockAudioDevice + *} +procedure SDL_LockAudioDevice(dev: TSDL_AudioDeviceID); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockAudioDevice' {$ENDIF} {$ENDIF}; - {** - * This function shuts down audio processing and closes the audio device. - *} -procedure SDL_CloseAudio cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseAudio' {$ENDIF} {$ENDIF}; -procedure SDL_CloseAudioDevice(dev: TSDL_AudioDeviceID) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseAudioDevice' {$ENDIF} {$ENDIF}; +{** + * This function is a legacy means of unlocking the audio device. + * + * New programs might want to use SDL_UnlockAudioDevice() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_UnlockAudioDevice(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LockAudio + * \sa SDL_UnlockAudioDevice + *} +procedure SDL_UnlockAudio; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Unlock' {$ENDIF} {$ENDIF}; - {** - * 1 if audio device is still functioning, zero if not, -1 on error. - *} -function SDL_AudioDeviceConnected(dev: TSDL_AudioDeviceID): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AudioDeviceConnected' {$ENDIF} {$ENDIF}; +{** + * Use this function to unlock the audio callback function for a specified + * device. + * + * This function should be paired with a previous SDL_LockAudioDevice() call. + * + * \param dev the ID of the device to be unlocked + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LockAudioDevice + *} +procedure SDL_UnlockAudioDevice(dev: TSDL_AudioDeviceID); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockAudioDevice' {$ENDIF} {$ENDIF}; + +{*Audio lock functions*} + +{** + * This function is a legacy means of closing the audio device. + * + * This function is equivalent to calling... + * + * ```c + * SDL_CloseAudioDevice(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_OpenAudio + *} +procedure SDL_CloseAudio; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseAudio' {$ENDIF} {$ENDIF}; + +{** + * Use this function to shut down audio processing and close the audio device. + * + * The application should close open audio devices once they are no longer + * needed. Calling this function will wait until the device's audio callback + * is not running, release the audio hardware and then clean up internal + * state. No further audio will play from this device once this function + * returns. + * + * This function may block briefly while pending audio data is played by the + * hardware, so that applications don't drop the last buffer of data they + * supplied. + * + * The device ID is invalid as soon as the device is closed, and is eligible + * for reuse in a new SDL_OpenAudioDevice() call immediately. + * + * \param dev an audio device previously opened with SDL_OpenAudioDevice() + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_OpenAudioDevice + *} +procedure SDL_CloseAudioDevice(dev: TSDL_AudioDeviceID); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseAudioDevice' {$ENDIF} {$ENDIF}; diff --git a/units/sdlblendmode.inc b/units/sdlblendmode.inc index a1ac070a..15dfb171 100644 --- a/units/sdlblendmode.inc +++ b/units/sdlblendmode.inc @@ -5,6 +5,7 @@ *} type + PPSDL_BlendMode = ^PSDL_BlendMode; PSDL_BlendMode = ^TSDL_BlendMode; TSDL_BlendMode = type DWord; @@ -31,6 +32,7 @@ const * \brief The blend operation used when combining source and destination pixel components *} type + PPSDL_BlendOperation = ^PSDL_BlendOperation; PSDL_BlendOperation = ^TSDL_BlendOperation; TSDL_BlendOperation = type DWord; @@ -45,6 +47,7 @@ const * \brief The normalized factor used to multiply pixel components *} type + PPSDL_BlendFactor = ^PSDL_BlendFactor; PSDL_BlendFactor = ^TSDL_BlendFactor; TSDL_BlendFactor = type DWord; diff --git a/units/sdlclipboard.inc b/units/sdlclipboard.inc index 051b31a5..1b3929fa 100644 --- a/units/sdlclipboard.inc +++ b/units/sdlclipboard.inc @@ -1,24 +1,105 @@ +{* + * \file SDL_clipboard.h + * + * Include file for SDL clipboard handling + } + {* Function prototypes *} -{** - * \brief Put UTF-8 text into the clipboard +{* + * Put UTF-8 text into the clipboard. + * + * \param text the text to store in the clipboard + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \sa SDL_GetClipboardText() - *} -function SDL_SetClipboardText(const text: PAnsiChar): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetClipboardText' {$ENDIF} {$ENDIF}; + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetClipboardText + * \sa SDL_HasClipboardText + } +function SDL_SetClipboardText(text: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetClipboardText' {$ENDIF} {$ENDIF}; -{** - * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free() +{* + * Get UTF-8 text from the clipboard, which must be freed with SDL_free(). + * + * This functions returns empty string if there was not enough memory left for + * a copy of the clipboard's content. + * + * \returns the clipboard text on success or an empty string on failure; call + * SDL_GetError() for more information. Caller must call SDL_free() + * on the returned pointer when done with it (even if there was an + * error). * - * \sa SDL_SetClipboardText() - *} -function SDL_GetClipboardText(): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetClipboardText' {$ENDIF} {$ENDIF}; + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HasClipboardText + * \sa SDL_SetClipboardText + } +function SDL_GetClipboardText(): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetClipboardText' {$ENDIF} {$ENDIF}; -{** - * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty +{* + * Query whether the clipboard exists and contains a non-empty text string. + * + * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * + * \since This function is available since SDL 2.0.0. * - * \sa SDL_GetClipboardText() - *} -function SDL_HasClipboardText(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasClipboardText' {$ENDIF} {$ENDIF}; + * \sa SDL_GetClipboardText + * \sa SDL_SetClipboardText + } +function SDL_HasClipboardText(): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasClipboardText' {$ENDIF} {$ENDIF}; +{* + * Put UTF-8 text into the primary selection. + * + * \param text the text to store in the primary selection + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.26.1. + * + * \sa SDL_GetPrimarySelectionText + * \sa SDL_HasPrimarySelectionText + } +function SDL_SetPrimarySelectionText(text: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetPrimarySelectionText' {$ENDIF} {$ENDIF}; + +{* + * Get UTF-8 text from the primary selection, which must be freed with + * SDL_free(). + * + * This functions returns empty string if there was not enough memory left for + * a copy of the primary selection's content. + * + * \returns the primary selection text on success or an empty string on + * failure; call SDL_GetError() for more information. Caller must + * call SDL_free() on the returned pointer when done with it (even if + * there was an error). + * + * \since This function is available since SDL 2.26.1. + * + * \sa SDL_HasPrimarySelectionText + * \sa SDL_SetPrimarySelectionText + } +function SDL_GetPrimarySelectionText(): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPrimarySelectionText' {$ENDIF} {$ENDIF}; + +{* + * Query whether the primary selection exists and contains a non-empty text + * string. + * + * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it + * does not. + * + * \since This function is available since SDL 2.26.1. + * + * \sa SDL_GetPrimarySelectionText + * \sa SDL_SetPrimarySelectionText + } +function SDL_HasPrimarySelectionText(): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasPrimarySelectionText' {$ENDIF} {$ENDIF}; diff --git a/units/sdlcpuinfo.inc b/units/sdlcpuinfo.inc index 880da9b2..6cf3701c 100644 --- a/units/sdlcpuinfo.inc +++ b/units/sdlcpuinfo.inc @@ -1,82 +1,215 @@ -{* This is a guess for the cacheline size used for padding. +{* + * This is a guess for the cacheline size used for padding. * Most x86 processors have a 64 byte cache line. * The 64-bit PowerPC processors have a 128 byte cache line. * We'll use the larger value to be generally safe. *} const - SDL_CACHELINE_SIZE = 128; + SDL_CACHELINE_SIZE = 128; {** - * This function returns the number of CPU cores available. + * This function returns the number of CPU cores available. *} -function SDL_GetCPUCount(): cint; cdecl external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCPUCount' {$ENDIF} {$ENDIF}; +function SDL_GetCPUCount(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCPUCount' {$ENDIF} {$ENDIF}; {** - * This function returns the L1 cache line size of the CPU + * This function returns the L1 cache line size of the CPU. * - * This is useful for determining multi-threaded structure padding - * or SIMD prefetch sizes. + * This is useful for determining multi-threaded structure padding + * or SIMD prefetch sizes. *} -function SDL_GetCPUCacheLineSize(): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCPUCacheLineSize' {$ENDIF} {$ENDIF}; +function SDL_GetCPUCacheLineSize(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCPUCacheLineSize' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has the RDTSC instruction. + * This function returns true if the CPU has the RDTSC instruction. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasRDTSC(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasRDTSC' {$ENDIF} {$ENDIF}; +function SDL_HasRDTSC(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasRDTSC' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has AltiVec features. + * This function returns true if the CPU has AltiVec features. + * + * This always returns false on CPUs that aren't using PowerPC + * instruction sets. *} -function SDL_HasAltiVec(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAltiVec' {$ENDIF} {$ENDIF}; +function SDL_HasAltiVec(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAltiVec' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has MMX features. + * This function returns true if the CPU has MMX features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasMMX(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasMMX' {$ENDIF} {$ENDIF}; +function SDL_HasMMX(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasMMX' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has 3DNow! features. + * This function returns true if the CPU has 3DNow! features. + * + * This always returns false on CPUs that aren't using AMD instruction sets. *} -function SDL_Has3DNow(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Has3DNow' {$ENDIF} {$ENDIF}; +function SDL_Has3DNow(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Has3DNow' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has SSE features. + * This function returns true if the CPU has SSE features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasSSE(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE' {$ENDIF} {$ENDIF}; +function SDL_HasSSE(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE' {$ENDIF} {$ENDIF}; {** * This function returns true if the CPU has SSE2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + *} +function SDL_HasSSE2(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE2' {$ENDIF} {$ENDIF}; + +{** + * This function returns true if the CPU has SSE3 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + *} +function SDL_HasSSE3(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE3' {$ENDIF} {$ENDIF}; + +{** + * This function returns true if the CPU has SSE4.1 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasSSE2(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE2' {$ENDIF} {$ENDIF}; +function SDL_HasSSE41(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE41' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has SSE3 features. + * This function returns true if the CPU has SSE4.2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasSSE3(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE3' {$ENDIF} {$ENDIF}; +function SDL_HasSSE42(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE42' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has SSE4.1 features. + * This function returns true if the CPU has AVX features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasSSE41(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE41' {$ENDIF} {$ENDIF}; +function SDL_HasAVX(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAVX' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has SSE4.2 features. + * This function returns true if the CPU has AVX2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasSSE42(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasSSE42' {$ENDIF} {$ENDIF}; +function SDL_HasAVX2(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAVX2' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has AVX features. + * Determine whether the CPU has AVX-512F (foundation) features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. *} -function SDL_HasAVX(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAVX' {$ENDIF} {$ENDIF}; +function SDL_HasAVX512F(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAVX512F' {$ENDIF} {$ENDIF}; {** - * This function returns true if the CPU has AVX2 features. + * Determine whether the CPU has ARM SIMD (ARMv6) features. + * This is different from ARM NEON, which is a different instruction set. + * + * This always returns false on CPUs that aren't using ARM instruction sets. + *} +function SDL_HasARMSIMD(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasARMSIMD' {$ENDIF} {$ENDIF}; + +{** + * Determine whether the CPU has NEON (ARM SIMD) features. + * + * This always returns false on CPUs that aren't using ARM instruction sets. *} -function SDL_HasAVX2(): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasAVX2' {$ENDIF} {$ENDIF}; +function SDL_HasNEON(): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasNEON' {$ENDIF} {$ENDIF}; {** - * This function returns the amount of RAM configured in the system, in MB. + * This function returns the amount of RAM configured in the system, in MB. + *} +function SDL_GetSystemRAM(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetSystemRAM' {$ENDIF} {$ENDIF}; + +{** + * Report the alignment this system needs for SIMD allocations. + * + * This will return the minimum number of bytes to which a pointer must be + * aligned to be compatible with SIMD instructions on the current machine. For + * example, if the machine supports SSE only, it will return 16, but if it + * supports AVX-512F, it'll return 64 (etc). This only reports values for + * instruction sets SDL knows about, so if your SDL build doesn't have + * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and + * not 64 for the AVX-512 instructions that exist but SDL doesn't know about. + * Plan accordingly. + *} +function SDL_SIMDGetAlignment(): csize_t; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SIMDGetAlignment' {$ENDIF} {$ENDIF}; + +{* + * Allocate memory in a SIMD-friendly way. + * + * This will allocate a block of memory that is suitable for use with SIMD + * instructions. Specifically, it will be properly aligned and padded for the + * system's supported vector instructions. + * + * The memory returned will be padded such that it is safe to read or write an + * incomplete vector at the end of the memory block. This can be useful so you + * don't have to drop back to a scalar fallback at the end of your SIMD + * processing loop to deal with the final elements without overflowing the + * allocated buffer. + * + * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free(). + * + * Note that SDL will only deal with SIMD instruction sets it is aware of; for + * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and + * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants + * 64. To be clear: if you can't decide to use an instruction set with an + * SDL_Has*() function, don't use that instruction set with memory allocated + * through here. + * + * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't + * out of memory, but you are not allowed to dereference it (because you only + * own zero bytes of that buffer). + *} +function SDL_SIMDAlloc(const len: csize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SIMDAlloc' {$ENDIF} {$ENDIF}; + +{** + * Reallocate memory obtained from SDL_SIMDAlloc. + * + * It is not valid to use this function on a pointer from anything but + * SDL_SIMDAlloc(). It can't be used on pointers from SDL_malloc, GetMem, etc. + *} +function SDL_SIMDRealloc(mem: Pointer; const len: csize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SIMDRealloc' {$ENDIF} {$ENDIF}; + +{** + * Deallocate memory obtained from SDL_SIMDAlloc. + * + * It is not valid to use this function on a pointer from anything but + * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from + * SDL_malloc, GetMem, etc. + * + * However, SDL_SIMDFree(NIL) is a legal no-op. + * + * The memory pointed to by `mem` is no longer valid for access upon return, + * and may be returned to the system or reused by a future allocation. The + * pointer passed to this function is no longer safe to dereference once this + * function returns, and should be discarded. *} -function SDL_GetSystemRAM(): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetSystemRAM' {$ENDIF} {$ENDIF}; +procedure SDL_SIMDFree(mem: Pointer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SIMDFree' {$ENDIF} {$ENDIF}; diff --git a/units/sdlerror.inc b/units/sdlerror.inc index f6e92249..49a370fd 100644 --- a/units/sdlerror.inc +++ b/units/sdlerror.inc @@ -13,7 +13,7 @@ * * \return -1, there is no error handling for this function *} -function SDL_SetError(const fmt: PAnsiChar): cint; cdecl; +function SDL_SetError(const fmt: PAnsiChar; args: array of const): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetError' {$ENDIF} {$ENDIF}; {** @@ -64,6 +64,8 @@ procedure SDL_ClearError cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MAC type + PPSDL_ErrorCode = ^PSDL_ErrorCode; + PSDL_ErrorCode = ^TSDL_ErrorCode; TSDL_ErrorCode = (SDL_ENOMEM, SDL_EFREAD, SDL_EFWRITE, diff --git a/units/sdlerror_c.inc b/units/sdlerror_c.inc deleted file mode 100644 index 4185b583..00000000 --- a/units/sdlerror_c.inc +++ /dev/null @@ -1,41 +0,0 @@ -// based on "sdl_error_c.h" (2.0.14) - -{* This file defines a structure that carries language-independent - error messages -*} - -const - ERR_MAX_STRLEN = 128; - //ERR_MAX_ARGS = 5; { Obsolete in 2.0.14? } - -type - - TSDL_Error = record - {* This is a numeric value corresponding to the current error *} - error: cint; - str: String[ERR_MAX_STRLEN]; - end; - - { Seems the error structure has changed drastically by SDL2 ver. 2.0.14?! - For ref. the old structure: (Can be deleted in later versions) } - //TSDL_Error = record - // {* This is a numeric value corresponding to the current error *} - // error: cint; - // - // {* This is a key used to index into a language hashtable containing - // internationalized versions of the SDL error messages. If the key - // is not in the hashtable, or no hashtable is available, the key is - // used directly as an error message format string. - // *} - // key: String[ERR_MAX_STRLEN]; - // - // {* These are the arguments for the error functions *} - // argc: cint32; - // case cint32 of - // {* What is a character anyway? (UNICODE issues) *} - // 0: (value_c: Byte;); - // 1: (value_ptr: Pointer;); - // 2: (value_i: cint32;); - // 3: (value_f: Double;); - // 4: (buf: String[ERR_MAX_STRLEN];); - //end; diff --git a/units/sdlevents.inc b/units/sdlevents.inc index 1fd9efc5..5f4fe6d1 100644 --- a/units/sdlevents.inc +++ b/units/sdlevents.inc @@ -1,6 +1,7 @@ //from "sdl_events.h" type + PPSDL_EventType = ^PSDL_EventType; PSDL_EventType = ^TSDL_EventType; TSDL_EventType = type cuint32; @@ -53,6 +54,11 @@ const * Called on Android in onResume() *} SDL_APP_DIDENTERFOREGROUND = TSDL_EventType($106); + {* The user's locale preferences have changed. *} + SDL_LOCALECHANGED = TSDL_EventType($107); + + { Display events } + SDL_DISPLAYEVENT = TSDL_EventType($150); // Display state change { Window events } SDL_WINDOWEVENT = TSDL_EventType($200); // Window state change @@ -64,6 +70,7 @@ const SDL_TEXTEDITING = TSDL_EventType($302); // Keyboard text editing (composition) SDL_TEXTINPUT = TSDL_EventType($303); // Keyboard text input SDL_KEYMAPCHANGED = TSDL_EventType($304); // Keymap changed due to a system event such as an input language or keyboard layout change. + SDL_TEXTEDITING_EXT = TSDL_EventType($305); // Extended keyboard text editing (composition) { Mouse events } SDL_MOUSEMOTION = TSDL_EventType($400); // Mouse moved @@ -72,21 +79,26 @@ const SDL_MOUSEWHEEL = TSDL_EventType($403); // Mouse wheel motion { Joystick events } - SDL_JOYAXISMOTION = TSDL_EventType($600); // Joystick axis motion - SDL_JOYBALLMOTION = TSDL_EventType($601); // Joystick trackball motion - SDL_JOYHATMOTION = TSDL_EventType($602); // Joystick hat position change - SDL_JOYBUTTONDOWN = TSDL_EventType($603); // Joystick button pressed - SDL_JOYBUTTONUP = TSDL_EventType($604); // Joystick button released - SDL_JOYDEVICEADDED = TSDL_EventType($605); // A new joystick has been inserted into the system - SDL_JOYDEVICEREMOVED = TSDL_EventType($606); // An opened joystick has been removed + SDL_JOYAXISMOTION = TSDL_EventType($600); // Joystick axis motion + SDL_JOYBALLMOTION = TSDL_EventType($601); // Joystick trackball motion + SDL_JOYHATMOTION = TSDL_EventType($602); // Joystick hat position change + SDL_JOYBUTTONDOWN = TSDL_EventType($603); // Joystick button pressed + SDL_JOYBUTTONUP = TSDL_EventType($604); // Joystick button released + SDL_JOYDEVICEADDED = TSDL_EventType($605); // A new joystick has been inserted into the system + SDL_JOYDEVICEREMOVED = TSDL_EventType($606); // An opened joystick has been removed + SDL_JOYBATTERYUPDATED = TSDL_EventType($607); // Joystick battery level change { Game controller events } SDL_CONTROLLERAXISMOTION = TSDL_EventType($650); // Game controller axis motion - SDL_CONTROLLERBUTTONDOWN = TSDL_EventType($651); // Game controller button pressed + SDL_CONTROLLERBUTTONDOWN = TSDL_EventType($651); // Game controller button pressed SDL_CONTROLLERBUTTONUP = TSDL_EventType($652); // Game controller button released - SDL_CONTROLLERDEVICEADDED = TSDL_EventType($653); // A new Game controller has been inserted into the system - SDL_CONTROLLERDEVICEREMOVED = TSDL_EventType($654); // An opened Game controller has been removed - SDL_CONTROLLERDEVICEREMAPPED = TSDL_EventType($655); // The controller mapping was updated + SDL_CONTROLLERDEVICEADDED = TSDL_EventType($653); // A new Game controller has been inserted into the system + SDL_CONTROLLERDEVICEREMOVED = TSDL_EventType($654); // An opened Game controller has been removed + SDL_CONTROLLERDEVICEREMAPPED = TSDL_EventType($655); // The controller mapping was updated + SDL_CONTROLLERTOUCHPADDOWN = TSDL_EventType($666); // Game controller touchpad was touched + SDL_CONTROLLERTOUCHPADMOTION = TSDL_EventType($667); // Game controller touchpad finger was moved + SDL_CONTROLLERTOUCHPADUP = TSDL_EventType($668); // Game controller touchpad finger was lifted + SDL_CONTROLLERSENSORUPDATE = TSDL_EventType($669); // Game controller sensor was updated { Touch events } SDL_FINGERDOWN = TSDL_EventType($700); @@ -111,10 +123,16 @@ const SDL_AUDIODEVICEADDED = TSDL_EventType($1100); // A new audio device is available SDL_AUDIODEVICEREMOVED = TSDL_EventType($1101); // An audio device has been removed. + { Sensor events } + SDL_SENSORUPDATED = TSDL_EventType($1200); // A sensor was updated + { Render events } SDL_RENDER_TARGETS_RESET = TSDL_EventType($2000); // The render targets have been reset SDL_RENDER_DEVICE_RESET = TSDL_EventType($2001); // The device has been reset and all textures need to be recreated - + + { Internal events } + SDL_POLLSENTINEL = TSDL_EventType($7F00); // Signals the end of an event poll cycle + {** Events SDL_USEREVENT through SDL_LASTEVENT are for your use, * and should be allocated with SDL_RegisterEvents() *} @@ -129,16 +147,34 @@ type {** * Fields shared by every event *} - + PPSDL_CommonEvent = ^PSDL_CommonEvent; + PSDL_CommonEvent = ^TSDL_CommonEvent; TSDL_CommonEvent = record type_: cuint32; timestamp: cuint32; end; {** - * Window state change event data (event.window.*) + * Display state change event data (event.display.*) *} + PPSDL_DisplayEvent = ^PSDL_DisplayEvent; + PSDL_DisplayEvent = ^TSDL_DisplayEvent; + TSDL_DisplayEvent = record + type_: cuint32; // SDL_DISPLAYEVENT + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + display: cuint32; // The associated display index + event: cuint8; // SDL_DisplayEventID + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + data1: cint32; // event dependent data + end; + {** + * Window state change event data (event.window.*) + *} + PPSDL_WindowEvent = ^PSDL_WindowEvent; + PSDL_WindowEvent = ^TSDL_WindowEvent; TSDL_WindowEvent = record type_: cuint32; // SDL_WINDOWEVENT timestamp: cuint32; @@ -154,12 +190,14 @@ type {** * Keyboard button event structure (event.key.*) *} + PPSDL_KeyboardEvent = ^PSDL_KeyboardEvent; + PSDL_KeyboardEvent = ^TSDL_KeyboardEvent; TSDL_KeyboardEvent = record type_: cuint32; // SDL_KEYDOWN or SDL_KEYUP timestamp: cuint32; windowID: cuint32; // The window with keyboard focus, if any state: cuint8; // SDL_PRESSED or SDL_RELEASED - _repeat: cuint8; // Non-zero if this is a key repeat + repeat_: cuint8; // Non-zero if this is a key repeat padding2: cuint8; padding3: cuint8; keysym: TSDL_KeySym; // The key that was pressed or released @@ -169,20 +207,35 @@ const SDL_TEXTEDITINGEVENT_TEXT_SIZE = 32; type - {** * Keyboard text editing event structure (event.edit.*) *} - + PPSDL_TextEditingEvent = ^PSDL_TextEditingEvent; + PSDL_TextEditingEvent = ^TSDL_TextEditingEvent; TSDL_TextEditingEvent = record type_: cuint32; // SDL_TEXTEDITING timestamp: cuint32; windowID: cuint32; // The window with keyboard focus, if any - text: array[0..SDL_TEXTEDITINGEVENT_TEXT_SIZE] of Char; // The editing text + text: array[0..SDL_TEXTEDITINGEVENT_TEXT_SIZE - 1] of Char; // The editing text start: cint32; // The start cursor of selected editing text length: cint32; // The length of selected editing text end; + {** + * Extended keyboard text editing event structure (event.editExt.*) when text would be + * truncated if stored in the text buffer SDL_TextEditingEvent + *} + PPSDL_TextEditingExtEvent = ^PSDL_TextEditingExtEvent; + PSDL_TextEditingExtEvent = ^TSDL_TextEditingExtEvent; + TSDL_TextEditingExtEvent = record + type_: cuint32; // SDL_TEXTEDITING_EXT + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + windowID: cuint32; // The window with keyboard focus, if any + text: PAnsiChar; // The editing text, which should be freed with SDL_free(), and will not be NIL + start: cint32; // The start cursor of selected editing text + length: cint32; // The length of selected editing text + end; + const SDL_TEXTINPUTEVENT_TEXT_SIZE = 32; @@ -191,27 +244,26 @@ type {** * Keyboard text input event structure (event.text.*) *} - + PPSDL_TextInputEvent = ^PSDL_TextInputEvent; + PSDL_TextInputEvent = ^TSDL_TextInputEvent; TSDL_TextInputEvent = record type_: cuint32; // SDL_TEXTINPUT timestamp: cuint32; windowID: cuint32; // The window with keyboard focus, if any - text: array[0..SDL_TEXTINPUTEVENT_TEXT_SIZE] of Char; // The input text + text: array[0..SDL_TEXTINPUTEVENT_TEXT_SIZE - 1] of Char; // The input text end; {** * Mouse motion event structure (event.motion.*) *} - + PPSDL_MouseMotionEvent = ^PSDL_MouseMotionEvent; + PSDL_MouseMotionEvent = ^TSDL_MouseMotionEvent; TSDL_MouseMotionEvent = record - type_: cuint32; // SDL_MOUSEMOTION - timestamp: cuint32; - windowID: cuint32; // The window with mouse focus, if any - which: cuint32; // The mouse instance id, or SDL_TOUCH_MOUSEID - state: cuint8; // The current button state - padding1: cuint8; - padding2: cuint8; - padding3: cuint8; + type_: cuint32; // SDL_MOUSEMOTION + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + windowID: cuint32; // The window with mouse focus, if any + which: cuint32; // The mouse instance id, or SDL_TOUCH_MOUSEID + state: cuint32; // The current button state x: cint32; // X coordinate, relative to window y: cint32; // Y coordinate, relative to window xrel: cint32; // The relative motion in the X direction @@ -221,7 +273,8 @@ type {** * Mouse button event structure (event.button.*) *} - + PPSDL_MouseButtonEvent = ^PSDL_MouseButtonEvent; + PSDL_MouseButtonEvent = ^TSDL_MouseButtonEvent; TSDL_MouseButtonEvent = record type_: cuint32; // SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP timestamp: cuint32; @@ -238,21 +291,27 @@ type {** * Mouse wheel event structure (event.wheel.*) *} - + PPSDL_MouseWheelEvent = ^PSDL_MouseWheelEvent; + PSDL_MouseWheelEvent = ^TSDL_MouseWheelEvent; TSDL_MouseWheelEvent = record type_: cuint32; // SDL_MOUSEWHEEL timestamp: cuint32; - windowID: cuint32; // The window with mouse focus, if any - which: cuint32; // The mouse instance id, or SDL_TOUCH_MOUSEID - x: cint32; // The amount scrolled horizontally - y: cint32; // The amount scrolled vertically - direction: cuint32; // Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back + windowID: cuint32; // The window with mouse focus, if any + which: cuint32; // The mouse instance id, or SDL_TOUCH_MOUSEID + x: cint32; // The amount scrolled horizontally + y: cint32; // The amount scrolled vertically + direction: cuint32; // Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back + preciseX: cfloat; // The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) + preciseY: cfloat; // The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) + mouseX: cint32; // X coordinate, relative to window (added in 2.26.0) + mouseY: cint32; // Y coordinate, relative to window (added in 2.26.0) end; {** * Joystick axis motion event structure (event.jaxis.*) *} - + PPSDL_JoyAxisEvent = ^PSDL_JoyAxisEvent; + PSDL_JoyAxisEvent = ^TSDL_JoyAxisEvent; TSDL_JoyAxisEvent = record type_: cuint32; // SDL_JOYAXISMOTION timestamp: cuint32; @@ -268,7 +327,8 @@ type {** * Joystick trackball motion event structure (event.jball.*) *} - + PPSDL_JoyBallEvent = ^PSDL_JoyBallEvent; + PSDL_JoyBallEvent = ^TSDL_JoyBallEvent; TSDL_JoyBallEvent = record type_: cuint32; // SDL_JOYBALLMOTION timestamp: cuint32; @@ -284,7 +344,8 @@ type {** * Joystick hat position change event structure (event.jhat.*) *} - + PPSDL_JoyHatEvent = ^PSDL_JoyHatEvent; + PSDL_JoyHatEvent = ^TSDL_JoyHatEvent; TSDL_JoyHatEvent = record type_: cuint32; // SDL_JOYHATMOTION timestamp: cuint32; @@ -304,7 +365,8 @@ type {** * Joystick button event structure (event.jbutton.*) *} - + PPSDL_JoyButtonEvent = ^PSDL_JoyButtonEvent; + PSDL_JoyButtonEvent = ^TSDL_JoyButtonEvent; TSDL_JoyButtonEvent = record type_: cuint32; // SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP timestamp: cuint32; @@ -318,7 +380,8 @@ type {** * Joystick device event structure (event.jdevice.*) *} - + PPSDL_JoyDeviceEvent = ^PSDL_JoyDeviceEvent; + PSDL_JoyDeviceEvent = ^TSDL_JoyDeviceEvent; TSDL_JoyDeviceEvent = record type_: cuint32; // SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED timestamp: cuint32; @@ -326,9 +389,22 @@ type end; {** - * Game controller axis motion event structure (event.caxis.*) + * Joysick battery level change event structure (event.jbattery.*) *} + PPSDL_JoyBatteryEvent = ^PSDL_JoyBatteryEvent; + PSDL_JoyBatteryEvent = ^TSDL_JoyBatteryEvent; + TSDL_JoyBatteryEvent = record + type_: cuint32; // SDL_JOYBATTERYUPDATED + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + which: TSDL_JoystickID; // The joystick instance id + level: TSDL_JoystickPowerLevel; // The joystick battery level + end; + {** + * Game controller axis motion event structure (event.caxis.*) + *} + PPSDL_ControllerAxisEvent = ^PSDL_ControllerAxisEvent; + PSDL_ControllerAxisEvent = ^TSDL_ControllerAxisEvent; TSDL_ControllerAxisEvent = record type_: cuint32; // SDL_CONTROLLERAXISMOTION timestamp: cuint32; @@ -344,7 +420,8 @@ type {** * Game controller button event structure (event.cbutton.*) *} - + PPSDL_ControllerButtonEvent = ^PSDL_ControllerButtonEvent; + PSDL_ControllerButtonEvent = ^TSDL_ControllerButtonEvent; TSDL_ControllerButtonEvent = record type_: cuint32; // SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP timestamp: cuint32; @@ -359,7 +436,8 @@ type {** * Controller device event structure (event.cdevice.*) *} - + PPSDL_ControllerDeviceEvent = ^PSDL_ControllerDeviceEvent; + PSDL_ControllerDeviceEvent = ^TSDL_ControllerDeviceEvent; TSDL_ControllerDeviceEvent = record type_: cuint32; // SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, or SDL_CONTROLLERDEVICEREMAPPED timestamp: cuint32; @@ -367,9 +445,39 @@ type end; {** - * Audio device event structure (event.adevice.*) + * Game controller touchpad event structure (event.ctouchpad.*) + *} + PPSDL_ControllerTouchpadEvent = ^PSDL_ControllerTouchpadEvent; + PSDL_ControllerTouchpadEvent = ^TSDL_ControllerTouchpadEvent; + TSDL_ControllerTouchpadEvent = record + type_: cuint32; // SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + which: TSDL_JoystickID; // The joystick instance id + touchpad: cint32; // The index of the touchpad + finger: cint32; // The index of the finger on the touchpad + x: cfloat; // Normalized in the range 0...1 with 0 being on the left + y: cfloat; // Normalized in the range 0...1 with 0 being at the top + pressure: cfloat; // Normalized in the range 0...1 + end; + + {** + * Game controller sensor event structure (event.csensor.*) *} + PPSDL_ControllerSensorEvent = ^PSDL_ControllerSensorEvent; + PSDL_ControllerSensorEvent = ^TSDL_ControllerSensorEvent; + TSDL_ControllerSensorEvent = record + type_: cuint32; // SDL_CONTROLLERSENSORUPDATE + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + which: TSDL_JoystickID; // The joystick instance id + sensor: cint32; // The type of the sensor, one of the values of SDL_SensorType + data: array[0..2] of cfloat; // Up to 3 values from the sensor, as defined in SDL_sensor.h + end; + {** + * Audio device event structure (event.adevice.*) + *} + PPSDL_AudioDeviceEvent = ^PSDL_AudioDeviceEvent; + PSDL_AudioDeviceEvent = ^TSDL_AudioDeviceEvent; TSDL_AudioDeviceEvent = record type_: cuint32; // ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED timestamp: cuint32; @@ -384,7 +492,8 @@ type {** * Touch finger event structure (event.tfinger.*) *} - + PPSDL_TouchFingerEvent = ^PSDL_TouchFingerEvent; + PSDL_TouchFingerEvent = ^TSDL_TouchFingerEvent; TSDL_TouchFingerEvent = record type_: cuint32; // SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP timestamp: cuint32; @@ -395,11 +504,14 @@ type dx: cfloat; // Normalized in the range 0...1 dy: cfloat; // Normalized in the range 0...1 pressure: cfloat; // Normalized in the range 0...1 + window: cuint32; // The window underneath the finger, if any end; {** * Multiple Finger Gesture Event (event.mgesture.*) *} + PPSDL_MultiGestureEvent = ^PSDL_MultiGestureEvent; + PSDL_MultiGestureEvent = ^TSDL_MultiGestureEvent; TSDL_MultiGestureEvent = record type_: cuint32; // SDL_MULTIGESTURE timestamp: cuint32; @@ -414,6 +526,8 @@ type {* (event.dgesture.*) *} + PPSDL_DollarGestureEvent = ^PSDL_DollarGestureEvent; + PSDL_DollarGestureEvent = ^TSDL_DollarGestureEvent; TSDL_DollarGestureEvent = record type_: cuint32; // SDL_DOLLARGESTURE timestamp: cuint32; @@ -431,17 +545,32 @@ type * This event is disabled by default, you can enable it with SDL_EventState() * If you enable this event, you must free the filename in the event. *} - + PPSDL_DropEvent = ^PSDL_DropEvent; + PSDL_DropEvent = ^TSDL_DropEvent; TSDL_DropEvent = record - type_: cuint32; // SDL_DROPFILE + type_: cuint32; // SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE timestamp: cuint32; - _file: PAnsiChar; // The file name, which should be freed with SDL_free() + file_: PAnsiChar; // The file name, which should be freed with SDL_free(), is NIL on begin/complete + windowID: cuint32; // The window that was dropped on, if any end; {** - * The "quit requested" event + * Sensor event structure (event.sensor.*) *} + PPSDL_SensorEvent = ^PSDL_SensorEvent; + PSDL_SensorEvent = ^TSDL_SensorEvent; + TSDL_SensorEvent = record + type_: cuint32; // SDL_SENSORUPDATED + timestamp: cuint32; // In milliseconds, populated using SDL_GetTicks() + which: cint32; // The instance ID of the sensor + data: array[0..5] of cfloat; // Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() + end; + {** + * The "quit requested" event + *} + PPSDL_QuitEvent = ^PSDL_QuitEvent; + PSDL_QuitEvent = ^TSDL_QuitEvent; TSDL_QuitEvent = record type_: cuint32; // SDL_QUIT timestamp: cuint32; @@ -450,7 +579,8 @@ type {** * A user-defined event type (event.user.*) *} - + PPSDL_UserEvent = ^PSDL_UserEvent; + PSDL_UserEvent = ^TSDL_UserEvent; TSDL_UserEvent = record type_: cuint32; // SDL_USEREVENT through SDL_NUMEVENTS-1 timestamp: cuint32; @@ -466,7 +596,7 @@ type * * If you want to use this event, you should include SDL_syswm.h. *} - + PPSDL_SysWMEvent = ^PSDL_SysWMEvent; PSDL_SysWMEvent = ^TSDL_SysWMEvent; TSDL_SysWMEvent = record type_: cuint32; // SDL_SYSWMEVENT @@ -477,18 +607,20 @@ type {** * General event structure *} - + PPSDL_Event = ^PSDL_Event; PSDL_Event = ^TSDL_Event; TSDL_Event = record case cint of 0: (type_: cuint32); SDL_COMMONEVENT: (common: TSDL_CommonEvent); + SDL_DISPLAYEVENT: (display: TSDL_DisplayEvent); SDL_WINDOWEVENT: (window: TSDL_WindowEvent); SDL_KEYUP, SDL_KEYDOWN: (key: TSDL_KeyboardEvent); SDL_TEXTEDITING: (edit: TSDL_TextEditingEvent); + SDL_TEXTEDITING_EXT: (exitExt: TSDL_TextEditingExtEvent); SDL_TEXTINPUT: (text: TSDL_TextInputEvent); SDL_MOUSEMOTION: (motion: TSDL_MouseMotionEvent); @@ -503,6 +635,7 @@ type SDL_JOYBUTTONUP: (jbutton: TSDL_JoyButtonEvent); SDL_JOYDEVICEADDED, SDL_JOYDEVICEREMOVED: (jdevice: TSDL_JoyDeviceEvent); + SDL_JOYBATTERYUPDATED: (jbattery: TSDL_JoyBatteryEvent); SDL_CONTROLLERAXISMOTION: (caxis: TSDL_ControllerAxisEvent); SDL_CONTROLLERBUTTONUP, @@ -510,10 +643,16 @@ type SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED: (cdevice: TSDL_ControllerDeviceEvent); + SDL_CONTROLLERTOUCHPADDOWN, + SDL_CONTROLLERTOUCHPADMOTION, + SDL_CONTROLLERTOUCHPADUP: (ctouchpad: TSDL_ControllerTouchpadEvent); + SDL_CONTROLLERSENSORUPDATE: (csensor: TSDL_ControllerSensorEvent); SDL_AUDIODEVICEADDED, SDL_AUDIODEVICEREMOVED: (adevice: TSDL_AudioDeviceEvent); + SDL_SENSORUPDATED: (sensor: TSDL_SensorEvent); + SDL_QUITEV: (quit: TSDL_QuitEvent); SDL_USEREVENT: (user: TSDL_UserEvent); @@ -546,6 +685,8 @@ const SDL_GETEVENT = 2; type + PPSDL_EventAction = ^PSDL_EventAction; + PSDL_EventAction = ^TSDL_EventAction; TSDL_EventAction = Word; {** @@ -627,6 +768,7 @@ type function SDL_PushEvent(event: PSDL_Event): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PumpEvents' {$ENDIF} {$ENDIF}; type + PPSDL_EventFilter = ^PSDL_EventFilter; PSDL_EventFilter = ^TSDL_EventFilter; {$IFNDEF GPC} TSDL_EventFilter = function(userdata: Pointer; event: PSDL_Event): cint; cdecl; diff --git a/units/sdlfilesystem.inc b/units/sdlfilesystem.inc index 7af4d244..39aeb315 100644 --- a/units/sdlfilesystem.inc +++ b/units/sdlfilesystem.inc @@ -1,88 +1,105 @@ +{* + * \file SDL_filesystem.h + * + * \brief Include file for filesystem SDL API functions + } -{** - * \brief Get the path where the application resides. +{* + * Get the directory where the application was run from. + * + * This is not necessarily a fast call, so you should call this once near + * startup and save the string if you need it. + * + * **Mac OS X and iOS Specific Functionality**: If the application is in a + * ".app" bundle, this function returns the Resource directory (e.g. + * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding + * a property to the Info.plist file. Adding a string key with the name + * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the + * behaviour. + * + * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an + * application in /Applications/SDLApp/MyApp.app): * - * Get the "base path". This is the directory where the application was run - * from, which is probably the installation directory, and may or may not - * be the process's current working directory. + * - `resource`: bundle resource directory (the default). For example: + * `/Applications/SDLApp/MyApp.app/Contents/Resources` + * - `bundle`: the Bundle directory. For example: + * `/Applications/SDLApp/MyApp.app/` + * - `parent`: the containing directory of the bundle. For example: + * `/Applications/SDLApp/` * - * This returns an absolute path in UTF-8 encoding, and is guaranteed to - * end with a path separator ('\\' on Windows, '/' most other places). + * The returned path is guaranteed to end with a path separator ('\' on + * Windows, '/' on most other platforms). * - * The pointer returned by this function is owned by you. Please call - * SDL_free() on the pointer when you are done with it, or it will be a - * memory leak. This is not necessarily a fast call, though, so you should - * call this once near startup and save the string if you need it. + * The pointer returned is owned by the caller. Please call SDL_free() on the + * pointer when done with it. * - * Some platforms can't determine the application's path, and on other - * platforms, this might be meaningless. In such cases, this function will - * return NULL. + * \returns an absolute path in UTF-8 encoding to the application data + * directory. nil will be returned on error or when the platform + * doesn't implement this functionality, call SDL_GetError() for more + * information. * - * \return String of base dir in UTF-8 encoding, or NULL on error. + * \since This function is available since SDL 2.0.1. * * \sa SDL_GetPrefPath - *} -function SDL_GetBasePath(): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetBasePath' {$ENDIF} {$ENDIF}; + } +function SDL_GetBasePath(): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetBasePath' {$ENDIF} {$ENDIF}; -{** - * \brief Get the user-and-app-specific path where files can be written. +{* + * Get the user-and-app-specific path where files can be written. * * Get the "pref dir". This is meant to be where users can write personal - * files (preferences and save games, etc) that are specific to your - * application. This directory is unique per user, per application. + * files (preferences and save games, etc) that are specific to your + * application. This directory is unique per user, per application. * - * This function will decide the appropriate location in the native filesystem, - * create the directory if necessary, and return a string of the absolute - * path to the directory in UTF-8 encoding. + * This function will decide the appropriate location in the native + * filesystem, create the directory if necessary, and return a string of the + * absolute path to the directory in UTF-8 encoding. * * On Windows, the string might look like: - * "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\" + * + * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\` * * On Linux, the string might look like: - * "/home/bob/.local/share/My Program Name/" * - * On Mac OS X, the string might look like: - * "/Users/bob/Library/Application Support/My Program Name/" + * `/home/bob/.local/share/My Program Name/` * - * (etc.) + * On Mac OS X, the string might look like: * - * You specify the name of your organization (if it's not a real organization, - * your name or an Internet domain you own might do) and the name of your - * application. These should be untranslated proper names. + * `/Users/bob/Library/Application Support/My Program Name/` * - * Both the org and app strings may become part of a directory name, so - * please follow these rules: + * You should assume the path returned by this function is the only safe place + * to write files (and that SDL_GetBasePath(), while it might be writable, or + * even the parent of the returned path, isn't where you should be writing + * things). * - * - Try to use the same org string (including case-sensitivity) for - * all your applications that use this function. - * - Always use a unique app string for each one, and make sure it never - * changes for an app once you've decided on it. - * - Unicode characters are legal, as long as it's UTF-8 encoded, but... - * - ...only use letters, numbers, and spaces. Avoid punctuation like - * "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. + * Both the org and app strings may become part of a directory name, so please + * follow these rules: * - * This returns an absolute path in UTF-8 encoding, and is guaranteed to - * end with a path separator ('\\' on Windows, '/' most other places). + * - Try to use the same org string (_including case-sensitivity_) for all + * your applications that use this function. + * - Always use a unique app string for each one, and make sure it never + * changes for an app once you've decided on it. + * - Unicode characters are legal, as long as it's UTF-8 encoded, but... + * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game + * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. * - * The pointer returned by this function is owned by you. Please call - * SDL_free() on the pointer when you are done with it, or it will be a - * memory leak. This is not necessarily a fast call, though, so you should - * call this once near startup and save the string if you need it. + * The returned path is guaranteed to end with a path separator ('\' on + * Windows, '/' on most other platforms). * - * You should assume the path returned by this function is the only safe - * place to write files (and that SDL_GetBasePath(), while it might be - * writable, or even the parent of the returned path, aren't where you - * should be writing things). + * The pointer returned is owned by the caller. Please call SDL_free() on the + * pointer when done with it. * - * Some platforms can't determine the pref path, and on other - * platforms, this might be meaningless. In such cases, this function will - * return NULL. + * \param org the name of your organization + * \param app the name of your application + * \returns a UTF-8 string of the user directory in platform-dependent + * notation. nil if there's a problem (creating directory failed, + * etc.). * - * \param org The name of your organization. - * \param app The name of your application. - * \return UTF-8 string of user dir in platform-dependent notation. NULL - * if there's a problem (creating directory failed, etc). + * \since This function is available since SDL 2.0.1. * * \sa SDL_GetBasePath - *} -function SDL_GetPrefPath(const org: PAnsiChar; const app: PAnsiChar): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPrefPath' {$ENDIF} {$ENDIF}; + } +function SDL_GetPrefPath(org: PAnsiChar; app: PAnsiChar): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPrefPath' {$ENDIF} {$ENDIF}; + diff --git a/units/sdlgamecontroller.inc b/units/sdlgamecontroller.inc index b609b8fe..e4b67122 100644 --- a/units/sdlgamecontroller.inc +++ b/units/sdlgamecontroller.inc @@ -14,22 +14,49 @@ {* The gamecontroller structure used to identify an SDL game controller *} type - PSDL_GameController = ^TSDL_GameController; - TSDL_GameController = Pointer; //todo + PPSDL_GameController = ^PSDL_GameController; + PSDL_GameController = type Pointer; - TSDL_GameControllerBindType = (SDL_CONTROLLER_BINDTYPE_NONE, - SDL_CONTROLLER_BINDTYPE_BUTTON, - SDL_CONTROLLER_BINDTYPE_AXIS, - SDL_CONTROLLER_BINDTYPE_HAT); + PPSDL_GameControllerType = ^PSDL_GameControllerType; + PSDL_GameControllerType = ^TSDL_GameControllerType; + TSDL_GameControllerType = type cint; +const + SDL_CONTROLLER_TYPE_UNKNOWN = TSDL_GameControllerType(0); + SDL_CONTROLLER_TYPE_XBOX360 = TSDL_GameControllerType(1); + SDL_CONTROLLER_TYPE_XBOXONE = TSDL_GameControllerType(2); + SDL_CONTROLLER_TYPE_PS3 = TSDL_GameControllerType(3); + SDL_CONTROLLER_TYPE_PS4 = TSDL_GameControllerType(4); + SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO = TSDL_GameControllerType(5); + SDL_CONTROLLER_TYPE_VIRTUAL = TSDL_GameControllerType(6); + SDL_CONTROLLER_TYPE_PS5 = TSDL_GameControllerType(7); + SDL_CONTROLLER_TYPE_AMAZON_LUNA = TSDL_GameControllerType(8); + SDL_CONTROLLER_TYPE_GOOGLE_STADIA = TSDL_GameControllerType(9); + SDL_CONTROLLER_TYPE_NVIDIA_SHIELD = TSDL_GameControllerType(10); + SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT = TSDL_GameControllerType(11); + SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT = TSDL_GameControllerType(12); + SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR = TSDL_GameControllerType(13); + +type + PPSDL_GameControllerBindType = ^PSDL_GameControllerBindType; + PSDL_GameControllerBindType = ^TSDL_GameControllerBindType; + TSDL_GameControllerBindType = type cint; +const + SDL_CONTROLLER_BINDTYPE_NONE = TSDL_GameControllerBindType(0); + SDL_CONTROLLER_BINDTYPE_BUTTON = TSDL_GameControllerBindType(1); + SDL_CONTROLLER_BINDTYPE_AXIS = TSDL_GameControllerBindType(2); + SDL_CONTROLLER_BINDTYPE_HAT = TSDL_GameControllerBindType(3); {** * Get the SDL joystick layer binding for this controller button/axis mapping *} +type THat = record hat: cint; hat_mask: cint; end; + PPSDL_GameControllerButtonBind = ^PSDL_GameControllerButtonBind; + PSDL_GameControllerButtonBind = ^TSDL_GameControllerButtonBind; TSDL_GameControllerButtonBind = record bindType: TSDL_GameControllerBindType; case cint of @@ -83,6 +110,12 @@ function SDL_GameControllerAddMapping( mappingString: PAnsiChar ): cint cdecl; e function SDL_GameControllerAddMappingsFromRW(rw: PSDL_RWops; freerw: cint32):cint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerAddMappingsFromRW' {$ENDIF} {$ENDIF}; +{** + * Get the number of mappings installed. + *} +function SDL_GameControllerNumMappings():cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerNumMappings' {$ENDIF} {$ENDIF}; + {** * Get a mapping string for a GUID * @@ -90,6 +123,15 @@ function SDL_GameControllerAddMappingsFromRW(rw: PSDL_RWops; freerw: cint32):cin *} function SDL_GameControllerMappingForGUID( guid: TSDL_JoystickGUID ): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerMappingForGUID' {$ENDIF} {$ENDIF}; +{** + * Get the mapping at a particular index. + * + * Returns the mapping string. Must be freed with SDL_free(). + * Returns NIL if the index is out of range. + *} +function SDL_GameControllerMappingForIndex(mapping_index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerMappingForIndex' {$ENDIF} {$ENDIF}; + {** * Get a mapping string for an open GameController * @@ -109,6 +151,43 @@ function SDL_IsGameController(joystick_index: cint): TSDL_Bool cdecl; external S *} function SDL_GameControllerNameForIndex(joystick_index: cint): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerNameForIndex' {$ENDIF} {$ENDIF}; +{** + * Get the implementation dependent path for the game controller. + * + * This function can be called before any controllers are opened. + * + * `joystick_index` is the same as the `device_index` passed to + * SDL_JoystickOpen(). + * + * \param joystick_index the device_index of a device, from zero to + * SDL_NumJoysticks()-1 + * \returns the implementation-dependent path for the game controller, or NIL + * if there is no path or the index is invalid. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GameControllerPath + *} +function SDL_GameControllerPathForIndex(joystick_index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerPathForIndex' {$ENDIF} {$ENDIF}; + +{** + * Get the type of a game controller. + * This can be called before any controllers are opened. + *} +function SDL_GameControllerTypeForIndex(joystick_index: cint): TSDL_GameControllerType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerTypeForIndex' {$ENDIF} {$ENDIF}; + +{** + * Get the mapping of a game controller. + * This can be called before any controllers are opened. + * + * Returns the mapping string. Must be freed with SDL_free(). + * Returns NIL if no mapping is available. + *} +function SDL_GameControllerMappingForDeviceIndex(joystick_index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerMappingForDeviceIndex' {$ENDIF} {$ENDIF}; + {** * Open a game controller for use. * The index passed as an argument refers to the N'th game controller on the system. @@ -125,11 +204,126 @@ function SDL_GameControllerOpen(joystick_index: cint): PSDL_GameController cdecl function SDL_GameControllerFromInstanceID(joyid: TSDL_JoystickID): PSDL_GameController; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerFromInstanceID' {$ENDIF} {$ENDIF}; +{** + * Get the SDL_GameController associated with a player index. + * + * Please note that the player index is _not_ the device index, nor is it the + * instance id! + * + *} +function SDL_GameControllerFromPlayerIndex(player_index: cint): PSDL_GameController; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerFromPlayerIndex' {$ENDIF} {$ENDIF}; + {** * Return the name for this currently opened controller *} function SDL_GameControllerName(gamecontroller: PSDL_GameController): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerName' {$ENDIF} {$ENDIF}; +{** + * Get the implementation-dependent path for an opened game controller. + * + * This is the same path as returned by SDL_GameControllerNameForIndex(), but + * it takes a controller identifier instead of the (unstable) device index. + * + * \param gamecontroller a game controller identifier previously returned by + * SDL_GameControllerOpen() + * \returns the implementation dependent path for the game controller, or NIL + * if there is no path or the identifier passed is invalid. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GameControllerPathForIndex + *} +function SDL_GameControllerPath(gamecontroller: PSDL_GameController): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerPath' {$ENDIF} {$ENDIF}; + +{** + * Get the type of this currently opened controller + * + * This is the same name as returned by SDL_GameControllerTypeForIndex(), but + * it takes a controller identifier instead of the (unstable) device index. + *} +function SDL_GameControllerGetType(gamecontroller: PSDL_GameController): TSDL_GameControllerType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetType' {$ENDIF} {$ENDIF}; + +{** + * Get the player index of an opened game controller. + * For XInput controllers this returns the XInput user index. + * + * Returns the player index for controller, or -1 if it's not available. + *} +function SDL_GameControllerGetPlayerIndex(gamecontroller: PSDL_GameController): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetPlayerIndex' {$ENDIF} {$ENDIF}; + +{** + * Set the player index of an opened game controller. + *} +procedure SDL_GameControllerSetPlayerIndex(gamecontroller: PSDL_GameController; player_index: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerSetPlayerIndex' {$ENDIF} {$ENDIF}; + +{** + * Get the USB vendor ID of an opened controller, if available. + * + * If the vendor ID isn't available this function returns 0. + * + * \param gamecontroller the game controller object to query. + * \return the USB vendor ID, or zero if unavailable. + * + * \since This function is available since SDL 2.0.6. + *} +function SDL_GameControllerGetVendor(gamecontroller: PSDL_GameController): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetVendor' {$ENDIF} {$ENDIF}; + +{** + * Get the USB product ID of an opened controller, if available. + * If the product ID isn't available, this function returns 0. + *} +function SDL_GameControllerGetProduct(gamecontroller: PSDL_GameController): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetProduct' {$ENDIF} {$ENDIF}; + +{** + * Get the product version of an opened controller, if available. + * If the product version isn't available, this function returns 0. + *} +function SDL_GameControllerGetProductVersion(gamecontroller: PSDL_GameController): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetProductVersion' {$ENDIF} {$ENDIF}; + +{** + * Get the firmware version of an opened controller, if available. + * + * If the firmware version isn't available this function returns 0. + * + * \param gamecontroller the game controller object to query. + * \return the controller firmware version, or zero if unavailable. + * + * \since This function is available since SDL 2.24.0. + *} +function SDL_GameControllerGetFirmwareVersion(gamecontroller: PSDL_GameController): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetFirmwareVersion' {$ENDIF} {$ENDIF}; + +{** + * Get the serial number of an opened controller, if available. + * + * Returns a string containing the serial number of the controller, + * or NIL if it is not available. Do _not_ free the string with SDL_free(). + *} +function SDL_GameControllerGetSerial(gamecontroller: PSDL_GameController): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetSerial' {$ENDIF} {$ENDIF}; + +{** + * Get the Steam Input handle of an opened controller, if available. + * + * Returns an InputHandle_t for the controller that can be used with Steam Input API: + * https://partner.steamgames.com/doc/api/ISteamInput + * + * \param gamecontroller the game controller object to query. + * \returns the gamepad handle, or 0 if unavailable. + * + * \since This function is available since SDL 2.30.0. + *} +function SDL_GameControllerGetSteamHandle(gamecontroller: PSDL_GameController): cuint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetSteamHandle' {$ENDIF} {$ENDIF}; + {** * Returns SDL_TRUE if the controller has been opened and currently connected, * or SDL_FALSE if it has not. @@ -165,8 +359,9 @@ procedure SDL_GameControllerUpdate() cdecl; external SDL_LibName {$IFDEF DELPHI} *} type + PPSDL_GameControllerAxis = ^PSDL_GameControllerAxis; PSDL_GameControllerAxis = ^TSDL_GameControllerAxis; - TSDL_GameControllerAxis = type Byte; + TSDL_GameControllerAxis = type cint; const SDL_CONTROLLER_AXIS_INVALID = TSDL_GameControllerAxis(-1); SDL_CONTROLLER_AXIS_LEFTX = TSDL_GameControllerAxis(0); @@ -192,6 +387,15 @@ function SDL_GameControllerGetStringForAxis(axis: TSDL_GameControllerAxis): PAns *} function SDL_GameControllerGetBindForAxis(gamecontroller: PSDL_GameController; axis: TSDL_GameControllerAxis): TSDL_GameControllerButtonBind cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetBindForAxis' {$ENDIF} {$ENDIF}; +{** + * Query whether a game controller has a given axis. + * + * This merely reports whether the controller's mapping defined this axis, + * as that is all the information SDL has about the physical device. + *} +function SDL_GameControllerHasAxis(gamecontroller: PSDL_GameController; axis: TSDL_GameControllerAxis): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasAxis' {$ENDIF} {$ENDIF}; + {** * Get the current state of an axis control on a game controller. * @@ -205,26 +409,33 @@ function SDL_GameControllerGetAxis(gamecontroller: PSDL_GameController; axis: TS * The list of buttons available from a controller *} type + PPSDL_GameControllerButton = ^PSDL_GameControllerButton; PSDL_GameControllerButton = ^TSDL_GameControllerButton; - TSDL_GameControllerButton = type Byte; + TSDL_GameControllerButton = type cint; const - SDL_CONTROLLER_BUTTON_INVALID = TSDL_GameControllerButton(-1); - SDL_CONTROLLER_BUTTON_A = TSDL_GameControllerButton(0); - SDL_CONTROLLER_BUTTON_B = TSDL_GameControllerButton(1); - SDL_CONTROLLER_BUTTON_X = TSDL_GameControllerButton(2); - SDL_CONTROLLER_BUTTON_Y = TSDL_GameControllerButton(3); - SDL_CONTROLLER_BUTTON_BACK = TSDL_GameControllerButton(4); - SDL_CONTROLLER_BUTTON_GUIDE = TSDL_GameControllerButton(5); - SDL_CONTROLLER_BUTTON_START = TSDL_GameControllerButton(6); - SDL_CONTROLLER_BUTTON_LEFTSTICK = TSDL_GameControllerButton(7); - SDL_CONTROLLER_BUTTON_RIGHTSTICK = TSDL_GameControllerButton(8); - SDL_CONTROLLER_BUTTON_LEFTSHOULDER = TSDL_GameControllerButton(9); + SDL_CONTROLLER_BUTTON_INVALID = TSDL_GameControllerButton(-1); + SDL_CONTROLLER_BUTTON_A = TSDL_GameControllerButton(0); + SDL_CONTROLLER_BUTTON_B = TSDL_GameControllerButton(1); + SDL_CONTROLLER_BUTTON_X = TSDL_GameControllerButton(2); + SDL_CONTROLLER_BUTTON_Y = TSDL_GameControllerButton(3); + SDL_CONTROLLER_BUTTON_BACK = TSDL_GameControllerButton(4); + SDL_CONTROLLER_BUTTON_GUIDE = TSDL_GameControllerButton(5); + SDL_CONTROLLER_BUTTON_START = TSDL_GameControllerButton(6); + SDL_CONTROLLER_BUTTON_LEFTSTICK = TSDL_GameControllerButton(7); + SDL_CONTROLLER_BUTTON_RIGHTSTICK = TSDL_GameControllerButton(8); + SDL_CONTROLLER_BUTTON_LEFTSHOULDER = TSDL_GameControllerButton(9); SDL_CONTROLLER_BUTTON_RIGHTSHOULDER = TSDL_GameControllerButton(10); - SDL_CONTROLLER_BUTTON_DPAD_UP = TSDL_GameControllerButton(11); - SDL_CONTROLLER_BUTTON_DPAD_DOWN = TSDL_GameControllerButton(12); - SDL_CONTROLLER_BUTTON_DPAD_LEFT = TSDL_GameControllerButton(13); - SDL_CONTROLLER_BUTTON_DPAD_RIGHT = TSDL_GameControllerButton(14); - SDL_CONTROLLER_BUTTON_MAX = TSDL_GameControllerButton(15); + SDL_CONTROLLER_BUTTON_DPAD_UP = TSDL_GameControllerButton(11); + SDL_CONTROLLER_BUTTON_DPAD_DOWN = TSDL_GameControllerButton(12); + SDL_CONTROLLER_BUTTON_DPAD_LEFT = TSDL_GameControllerButton(13); + SDL_CONTROLLER_BUTTON_DPAD_RIGHT = TSDL_GameControllerButton(14); + SDL_CONTROLLER_BUTTON_MISC1 = TSDL_GameControllerButton(15); {**< Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button *} + SDL_CONTROLLER_BUTTON_PADDLE1 = TSDL_GameControllerButton(16); {**< Xbox Elite paddle P1 *} + SDL_CONTROLLER_BUTTON_PADDLE2 = TSDL_GameControllerButton(17); {**< Xbox Elite paddle P3 *} + SDL_CONTROLLER_BUTTON_PADDLE3 = TSDL_GameControllerButton(18); {**< Xbox Elite paddle P2 *} + SDL_CONTROLLER_BUTTON_PADDLE4 = TSDL_GameControllerButton(19); {**< Xbox Elite paddle P4 *} + SDL_CONTROLLER_BUTTON_TOUCHPAD = TSDL_GameControllerButton(20); {**< PS4/PS5 touchpad button *} + SDL_CONTROLLER_BUTTON_MAX = TSDL_GameControllerButton(21); {** * turn this string into a button mapping @@ -241,6 +452,14 @@ function SDL_GameControllerGetStringForButton(button: TSDL_GameControllerButton) *} function SDL_GameControllerGetBindForButton(gamecontroller: PSDL_GameController; button: TSDL_GameControllerButton): TSDL_GameControllerButtonBind cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetBindForButton' {$ENDIF} {$ENDIF}; +{** + * Query whether a game controller has a given button. + * + * This merely reports whether the controller's mapping defined this button, + * as that is all the information SDL has about the physical device. + *} +function SDL_GameControllerHasButton(gamecontroller: PSDL_GameController; button: TSDL_GameControllerButton): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasButton' {$ENDIF} {$ENDIF}; {** * Get the current state of a button on a game controller. @@ -249,10 +468,185 @@ function SDL_GameControllerGetBindForButton(gamecontroller: PSDL_GameController; *} function SDL_GameControllerGetButton(gamecontroller: PSDL_GameController; button: TSDL_GameControllerButton): cuint8 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetButton' {$ENDIF} {$ENDIF}; +{** + * Get the number of touchpads on a game controller. + *} +function SDL_GameControllerGetNumTouchpads(gamecontroller: PSDL_GameController): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetNumTouchpads' {$ENDIF} {$ENDIF}; + +{** + * Get the number of supported simultaneous fingers on a touchpad on a game controller. + *} +function SDL_GameControllerGetNumTouchpadFingers(gamecontroller: PSDL_GameController; touchpad: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetNumTouchpadFingers' {$ENDIF} {$ENDIF}; + +{** + * Get the current state of a finger on a touchpad on a game controller. + *} +function SDL_GameControllerGetTouchpadFinger( + gamecontroller: PSDL_GameController; + touchpad, finger: cint; + state: pcuint8; + x, y, pressure: pcfloat +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetTouchpadFinger' {$ENDIF} {$ENDIF}; + +{** + * Return whether a game controller has a particular sensor. + *} +function SDL_GameControllerHasSensor(gamecontroller: PSDL_GameController; senstype: TSDL_SensorType): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasSensor' {$ENDIF} {$ENDIF}; + +{** + * Set whether data reporting for a game controller sensor is enabled. + *} +function SDL_GameControllerSetSensorEnabled(gamecontroller: PSDL_GameController; senstype: TSDL_SensorType; enabled: TSDL_bool): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerSetSensorEnabled' {$ENDIF} {$ENDIF}; + +{** + * Query whether sensor data reporting is enabled for a game controller. + *} +function SDL_GameControllerIsSensorEnabled(gamecontroller: PSDL_GameController; senstype: TSDL_SensorType): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerIsSensorEnabled' {$ENDIF} {$ENDIF}; + +{** + * Get the data rate (number of events per second) of + * a game controller sensor. + * + * Returns the data rate, or 0.0 if the data rate is not available. + *} +function SDL_GameControllerGetSensorDataRate(gamecontroller: PSDL_GameController; senstype: TSDL_SensorType): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetSensorDataRate' {$ENDIF} {$ENDIF}; + +{** + * Get the current state of a game controller sensor. + * + * The number of values and interpretation of the data is sensor dependent. + * See sdlsensor.inc for the details for each type of sensor. + *} +function SDL_GameControllerGetSensorData(gamecontroller: PSDL_GameController; senstype: TSDL_SensorType; data: pcfloat; num_values: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetSensorData' {$ENDIF} {$ENDIF}; + +{** + * Get the current state of a game controller sensor with the timestamp of the + * last update. + * + * The number of values and interpretation of the data is sensor dependent. + * See SDL_sensor.h for the details for each type of sensor. + * + * \param gamecontroller The controller to query + * \param type The type of sensor to query + * \param timestamp A pointer filled with the timestamp in microseconds of the + * current sensor reading if available, or 0 if not + * \param data A pointer filled with the current sensor state + * \param num_values The number of values to write to data + * \return 0 or -1 if an error occurred. + * + * \since This function is available since SDL 2.26.0. + *} +function SDL_GameControllerGetSensorDataWithTimestamp( + gamecontroller: PSDL_GameController; + senstype: TSDL_SensorType; + timestamp: pcuint64; + data: pcfloat; + num_values: cint +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetSensorDataWithTimestamp' {$ENDIF} {$ENDIF}; + +{** + * Query whether a game controller has rumble support. + *} +function SDL_GameControllerHasRumble(gamecontroller: PSDL_GameController): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasRumble' {$ENDIF} {$ENDIF}; + +{** + * Start a rumble effect on a game controller. + * + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. + * + * Returns 0, or -1 if rumble isn't supported on this controller. + *} +function SDL_GameControllerRumble( + gamecontroller: PSDL_GameController; + low_frequency_rumble, high_frequency_rumble: cuint16; + duration_ms: cuint32 +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerRumble' {$ENDIF} {$ENDIF}; + +{** + * Query whether a game controller has rumble support on triggers. + *} +function SDL_GameControllerHasRumbleTriggers(gamecontroller: PSDL_GameController): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasRumbleTriggers' {$ENDIF} {$ENDIF}; + +{** + * Start a rumble effect in the game controller's triggers. + * + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. + * + * Note that this is rumbling of the _triggers_ and not the game controller as + * a whole. This is currently only supported on Xbox One controllers. If you + * want the (more common) whole-controller rumble, use + * SDL_GameControllerRumble() instead. + * + * Returns 0, or -1 if trigger rumble isn't supported on this controller + *} +function SDL_GameControllerRumbleTriggers( + gamecontroller: PSDL_GameController; + left_rumble, right_rumble: cuint16; + duration_ms: cuint32 +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerRumbleTriggers' {$ENDIF} {$ENDIF}; + +{** + * Query whether a game controller has an LED. + *} +function SDL_GameControllerHasLED(gamecontroller: PSDL_GameController): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerHasLED' {$ENDIF} {$ENDIF}; + +{** + * Update a game controller's LED color. + * + * Returns 0, or -1 if this controller does not have a modifiable LED. + *} +function SDL_GameControllerSetLED(gamecontroller: PSDL_GameController; red, green, blue: cuint8): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerSetLED' {$ENDIF} {$ENDIF}; + +{** + * Send a controller-specific effect packet. + * + * Returns 0, or -1 if this controller or driver does not + * support effect packets. + *} +function SDL_GameControllerSendEffect(gamecontroller: PSDL_GameController; data: Pointer; size: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerSendEffect' {$ENDIF} {$ENDIF}; + {** * Close a controller previously opened with SDL_GameControllerOpen(). *} procedure SDL_GameControllerClose(gamecontroller: PSDL_GameController) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerClose' {$ENDIF} {$ENDIF}; +{** + * Return the sfSymbolsName for a given axis on a game controller + * on Apple platforms. + * + * Returns the sfSymbolsName, or NIL if the name can't be found. + * Do _not_ pass this string to SDL_free(). + *} +function SDL_GameControllerGetAppleSFSymbolsNameForAxis(gamecontroller: PSDL_GameController; axis: TSDL_GameControllerAxis): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetAppleSFSymbolsNameForAxis' {$ENDIF} {$ENDIF}; + +{** + * Return the sfSymbolsName for a given button on a game controller + * on Apple platforms. + * + * Returns the sfSymbolsName, or NIL if the name can't be found. + * Do _not_ pass this string to SDL_free(). + *} +function SDL_GameControllerGetAppleSFSymbolsNameForButton(gamecontroller: PSDL_GameController; button: TSDL_GameControllerButton): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GameControllerGetAppleSFSymbolsNameForButton' {$ENDIF} {$ENDIF}; + function SDL_GameControllerAddMappingsFromFile(Const FilePath:PAnsiChar):cint32; diff --git a/units/sdlgesture.inc b/units/sdlgesture.inc index 05aa6eeb..8ab4db4d 100644 --- a/units/sdlgesture.inc +++ b/units/sdlgesture.inc @@ -1,35 +1,72 @@ //from "sdl_gesture.h" type - TSDL_GestureID = cint64; + PPSDL_GestureID = ^PSDL_GestureID; + PSDL_GestureID = ^TSDL_GestureID; + TSDL_GestureID = type cint64; {* Function prototypes *} - {** - * Begin Recording a gesture on the specified touch, or all touches (-1) - * - * - *} -function SDL_RecordGesture(touchId: TSDL_TouchID): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RecordGesture' {$ENDIF} {$ENDIF}; + {/** + * Begin recording a gesture on a specified touch device or all touch devices. + * + * If the parameter `touchId` is -1 (i.e., all devices), this function will + * always return 1, regardless of whether there actually are any devices. + * + * \param touchId the touch device id, or -1 for all touch devices + * \returns 1 on success or 0 if the specified device could not be found. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetTouchDevice + *} +function SDL_RecordGesture(touchId: TSDL_TouchID): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RecordGesture' {$ENDIF} {$ENDIF}; {** - * Save all currently loaded Dollar Gesture templates - * - * - *} -function SDL_SaveAllDollarTemplates(src: PSDL_RWops): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveAllDollarTemplates' {$ENDIF} {$ENDIF}; + * Save all currently loaded Dollar Gesture templates. + * + * \param dst a SDL_RWops to save to + * \returns the number of saved templates on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadDollarTemplates + * \sa SDL_SaveDollarTemplate + *} +function SDL_SaveAllDollarTemplates(dst: PSDL_RWops): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveAllDollarTemplates' {$ENDIF} {$ENDIF}; {** - * Save a currently loaded Dollar Gesture template - * - * - *} -function SDL_SaveDollarTemplate(gestureId: TSDL_GestureID; src: PSDL_RWops): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveDollarTemplate' {$ENDIF} {$ENDIF}; + * Save a currently loaded Dollar Gesture template. + * + * \param gestureId a gesture id + * \param dst a SDL_RWops to save to + * \returns 1 on success or 0 on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadDollarTemplates + * \sa SDL_SaveAllDollarTemplates + *} +function SDL_SaveDollarTemplate(gestureId: TSDL_GestureID; dst: PSDL_RWops): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveDollarTemplate' {$ENDIF} {$ENDIF}; {** - * Load Dollar Gesture templates from a file - * - * - *} -function SDL_LoadDollarTemplates(touchId: TSDL_TouchID; src: PSDL_RWops): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadDollarTemplates' {$ENDIF} {$ENDIF}; + * Load Dollar Gesture templates from a file. + * + * \param touchId a touch id + * \param src a SDL_RWops to load from + * \returns the number of loaded templates on success or a negative error code + * (or 0) on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SaveAllDollarTemplates + * \sa SDL_SaveDollarTemplate + *} +function SDL_LoadDollarTemplates(touchId: TSDL_TouchID; src: PSDL_RWops): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadDollarTemplates' {$ENDIF} {$ENDIF}; diff --git a/units/sdlguid.inc b/units/sdlguid.inc new file mode 100644 index 00000000..cd950cef --- /dev/null +++ b/units/sdlguid.inc @@ -0,0 +1,60 @@ +{** + * \file SDL_guid.h + * + * Include file for handling ::SDL_GUID values. + *} + +{** + * An SDL_GUID is a 128-bit identifier for an input device that + * identifies that device across runs of SDL programs on the same + * platform. If the device is detached and then re-attached to a + * different port, or if the base system is rebooted, the device + * should still report the same GUID. + * + * GUIDs are as precise as possible but are not guaranteed to + * distinguish physically distinct but equivalent devices. For + * example, two game controllers from the same vendor with the same + * product ID and revision may have the same GUID. + * + * GUIDs may be platform-dependent (i.e., the same device may report + * different GUIDs on different operating systems). + *} +type + PPSDL_GUID = ^PSDL_GUID; + PSDL_GUID = ^TSDL_GUID; + TSDL_GUID = record + data: array[0..15] of cuint8; + end; + + {** + * Get an ASCII string representation for a given ::SDL_GUID. + * + * You should supply at least 33 bytes for pszGUID. + * + * \param guid the ::SDL_GUID you wish to convert to string + * \param pszGUID buffer in which to write the ASCII string + * \param cbGUID the size of pszGUID + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GUIDFromString + *} +procedure SDL_GUIDToString(guid: TSDL_GUID; pszGUID: PAnsiChar; cbGUID: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GUIDToString' {$ENDIF} {$ENDIF}; + +{** + * Convert a GUID string into a ::SDL_GUID structure. + * + * Performs no error checking. If this function is given a string containing + * an invalid GUID, the function will silently succeed, but the GUID generated + * will not be useful. + * + * \param pchGUID string containing an ASCII representation of a GUID + * \returns a ::SDL_GUID structure. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GUIDToString + *} +function SDL_GUIDFromString(const pchGUID: PAnsiChar): TSDL_GUID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GUIDFromString' {$ENDIF} {$ENDIF}; diff --git a/units/sdlhaptic.inc b/units/sdlhaptic.inc index f0182f46..48d36b81 100644 --- a/units/sdlhaptic.inc +++ b/units/sdlhaptic.inc @@ -80,13 +80,6 @@ * SDL_HapticClose(haptic); * * return 0; // Success - * - * - * - * You can also find out more information on my blog: - * http://bobbens.dyndns.org/journal/2010/sdl_haptic/ - * - * Edgar Simo Serra *} {** @@ -99,8 +92,8 @@ * SDL_HapticClose *} type - PSDL_Haptic = ^TSDL_Haptic; - TSDL_Haptic = record end; + PPSDL_Haptic = ^PSDL_Haptic; + PSDL_Haptic = type Pointer; {** * Haptic features @@ -140,7 +133,13 @@ const * SDL_HapticPeriodic *} const - SDL_HAPTIC_SQUARE = (1 shl 2); + SDL_HAPTIC_LEFTRIGHT = (1 shl 2); + + { !!! FIXME: put this back when we have more bits in 2.1 } + { #define SDL_HAPTIC_SQUARE (1<<2) } + SDL_HAPTIC_SQUARE = (1 shl 2); // SDL2-For-Pascal: Out-commented in C code. + // Why not keeping it for + // compatibility here? {** * Triangle wave effect supported. @@ -305,9 +304,14 @@ const const SDL_HAPTIC_SPHERICAL = 2; - {*Direction encodings*} - - {*Haptic features*} + {** + * \brief Use this value to play an effect on the steering wheel axis. This + * provides better compatibility across platforms and devices as SDL will guess + * the correct axis. + * \sa SDL_HapticDirection + *} +const + SDL_HAPTIC_STEERING_AXIS = 3; {* * Misc defines. @@ -319,8 +323,7 @@ const * SDL_HapticRunEffect *} const - //SDL_HAPTIC_INFINITY = 4294967295U; - SDL_HAPTIC_INFINITY = 4294967295; //right?! + SDL_HAPTIC_INFINITY = 4294967295; // C: 4294967295U {** * Structure that represents a haptic direction. @@ -415,9 +418,11 @@ const * SDL_HapticNumAxes *} type + PPSDL_HapticDirection = ^PSDL_HapticDirection; + PSDL_HapticDirection = ^TSDL_HapticDirection; TSDL_HapticDirection = record - _type: cuint8; {**< The type of encoding. *} - dir: array[0..2] of cint32; {**< The encoded direction. *} + type_: cuint8; {**< The type of encoding. *} + dir: array[0..2] of cint32; {**< The encoded direction. *} end; {** @@ -432,10 +437,12 @@ type * SDL_HapticEffect *} type + PPSDL_HapticConstant = ^PSDL_HapticConstant; + PSDL_HapticConstant = ^TSDL_HapticConstant; TSDL_HapticConstant = record {* Header *} - _type: cuint16; {**< SDL_HAPTIC_CONSTANT *} - direction: TSDL_HapticDirection; {**< Direction of the effect. *} + type_: cuint16; {**< SDL_HAPTIC_CONSTANT *} + direction: TSDL_HapticDirection; {**< Direction of the effect. *} {* Replay *} length: cuint32; {**< Duration of the effect. *} @@ -446,7 +453,7 @@ type interval: cuint16; {**< How soon it can be triggered again after button. *} {* Constant *} - level: cint16; {**< Strength of the constant effect. *} + level: cint16; {**< Strength of the constant effect. *} {* Envelope *} attack_length: cuint16; {**< Duration of the attack. *} @@ -513,9 +520,11 @@ type * SDL_HapticEffect *} type + PPSDL_HapticPeriodic = ^PSDL_HapticPeriodic; + PSDL_HapticPeriodic = ^TSDL_HapticPeriodic; TSDL_HapticPeriodic = record { Header *} - _type: cuint16; {**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE, + type_: cuint16; {**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE, SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or SDL_HAPTIC_SAWTOOTHDOWN *} direction: TSDL_HapticDirection; {**< Direction of the effect. *} @@ -530,8 +539,8 @@ type {* Periodic *} period: cuint16; {**< Period of the wave. *} - magnitude: cint16; {**< Peak value. *} - offset: cint16; {**< Mean value of the wave. *} + magnitude: cint16; {**< Peak value. *} + offset: cint16; {**< Mean value of the wave. *} phase: cuint16; {**< Horizontal shift given by hundredth of a cycle. *} {* Envelope *} @@ -566,11 +575,13 @@ type * SDL_HapticEffect *} type + PPSDL_HapticCondition = ^PSDL_HapticCondition; + PSDL_HapticCondition = ^TSDL_HapticCondition; TSDL_HapticCondition = record {* Header *} - _type: cuint16; {**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + type_: cuint16; {**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION *} - direction: TSDL_HapticDirection; {**< Direction of the effect - Not used ATM. *} + direction: TSDL_HapticDirection; {**< Direction of the effect - Not used ATM. *} {* Replay *} length: cuint32; {**< Duration of the effect. *} @@ -583,10 +594,10 @@ type {* Condition *} right_sat: array[0..2] of cuint16; {**< Level when joystick is to the positive side. *} left_sat: array[0..2] of cuint16; {**< Level when joystick is to the negative side. *} - right_coeff: array[0..2] of cint16; {**< How fast to increase the force towards the positive side. *} - left_coeff: array[0..2] of cint16; {**< How fast to increase the force towards the negative side. *} - deadband: array[0..2] of cuint16; {**< Size of the dead zone. *} - center: array[0..2] of cint16; {**< Position of the dead zone. *} + right_coeff: array[0..2] of cint16;{**< How fast to increase the force towards the positive side. *} + left_coeff: array[0..2] of cint16; {**< How fast to increase the force towards the negative side. *} + deadband: array[0..2] of cuint16; {**< Size of the dead zone. *} + center: array[0..2] of cint16; {**< Position of the dead zone. *} end; {** @@ -603,10 +614,12 @@ type * SDL_HapticEffect *} type + PPSDL_HapticRamp = ^PSDL_HapticRamp; + PSDL_HapticRamp = ^TSDL_HapticRamp; TSDL_HapticRamp = record {* Header *} - _type: cuint16; {**< SDL_HAPTIC_RAMP *} - direction: TSDL_HapticDirection; {**< Direction of the effect. *} + type_: cuint16; {**< SDL_HAPTIC_RAMP *} + direction: TSDL_HapticDirection; {**< Direction of the effect. *} {* Replay *} length: cuint32; {**< Duration of the effect. *} @@ -617,8 +630,8 @@ type interval: cuint16; {**< How soon it can be triggered again after button. *} {* Ramp *} - start: cint16; {**< Beginning strength level. *} - _end: cint16; {**< Ending strength level. *} + start: cint16; {**< Beginning strength level. *} + end_: cint16; {**< Ending strength level. *} {* Envelope *} attack_length: cuint16; {**< Duration of the attack. *} @@ -627,6 +640,31 @@ type fade_level: cuint16; {**< Level at the end of the fade. *} end; + {** + * \brief A structure containing a template for a Left/Right effect. + * + * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect. + * + * The Left/Right effect is used to explicitly control the large and small + * motors, commonly found in modern game controllers. The small (right) motor + * is high frequency, and the large (left) motor is low frequency. + * + * \sa SDL_HAPTIC_LEFTRIGHT + * \sa SDL_HapticEffect + *} +type + TSDL_HapticLeftRight = record + {* Header *} + type_: cuint16; {**< ::SDL_HAPTIC_LEFTRIGHT *} + + {* Replay *} + length: cuint32; {**< Duration of the effect in milliseconds. *} + + {* Rumble *} + large_magnitude: cuint16; {**< Control of the large controller motor. *} + small_magnitude: cuint16; {**< Control of the small controller motor. *} + end; + {** * A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect. * @@ -641,10 +679,12 @@ type * SDL_HapticEffect *} type + PPSDL_HapticCustom = ^PSDL_HapticCustom; + PSDL_HapticCustom = ^TSDL_HapticCustom; TSDL_HapticCustom = record {* Header *} - _type: cuint16; {**< SDL_HAPTIC_CUSTOM *} - direction: TSDL_HapticDirection; {**< Direction of the effect. *} + type_: cuint16; {**< SDL_HAPTIC_CUSTOM *} + direction: TSDL_HapticDirection; {**< Direction of the effect. *} {* Replay *} length: cuint32; {**< Duration of the effect. *} @@ -736,420 +776,545 @@ type * SDL_HapticCustom *} type + PPSDL_HapticEffect = ^PSDL_HapticEffect; PSDL_HapticEffect = ^TSDL_HapticEffect; TSDL_HapticEffect = record - {* Common for all force feedback effects *} - _type: cuint16; {**< Effect type. *} - case cuint16 of - 0: (constant: TSDL_HapticConstant;); {**< Constant effect. *} - 1: (periodic: TSDL_HapticPeriodic;); {**< Periodic effect. *} - 2: (condition: TSDL_HapticCondition;); {**< Condition effect. *} - 3: (ramp: TSDL_HapticRamp;); {**< Ramp effect. *} - 4: (custom: TSDL_HapticCustom;); {**< Custom effect. *} + case cint of + {* Common for all force feedback effects *} + 0: (type_: cuint16); {**< Effect type. *} + 1: (constant: TSDL_HapticConstant;); {**< Constant effect. *} + 2: (periodic: TSDL_HapticPeriodic;); {**< Periodic effect. *} + 3: (condition: TSDL_HapticCondition;); {**< Condition effect. *} + 4: (ramp: TSDL_HapticRamp;); {**< Ramp effect. *} + 5: (leftright: TSDL_HapticLeftRight;); {**< Custom effect. *} + 6: (custom: TSDL_HapticCustom;); {**< Custom effect. *} end; {* Function prototypes *} {** - * Count the number of haptic devices attached to the system. - * - * Number of haptic devices detected on the system. - *} -function SDL_NumHaptics: cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_NumHaptics' {$ENDIF} {$ENDIF}; + * Count the number of haptic devices attached to the system. + * + * \returns the number of haptic devices detected on the system or a negative + * error code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticName + *} +function SDL_NumHaptics: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_NumHaptics' {$ENDIF} {$ENDIF}; {** - * Get the implementation dependent name of a Haptic device. - * - * This can be called before any joysticks are opened. - * If no name can be found, this function returns NULL. - * - * device_index Index of the device to get its name. - * Name of the device or NULL on error. - * - * SDL_NumHaptics - *} -function SDL_HapticName(device_index: cint): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticName' {$ENDIF} {$ENDIF}; + * Get the implementation dependent name of a haptic device. + * + * This can be called before any joysticks are opened. If no name can be + * found, this function returns NULL. + * + * \param device_index index of the device to query. + * \returns the name of the device or NULL on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_NumHaptics + *} +function SDL_HapticName(device_index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticName' {$ENDIF} {$ENDIF}; {** - * Opens a Haptic device for usage. - * - * The index passed as an argument refers to the N'th Haptic device on this - * system. - * - * When opening a haptic device, its gain will be set to maximum and - * autocenter will be disabled. To modify these values use - * SDL_HapticSetGain() and SDL_HapticSetAutocenter(). - * - * device_index Index of the device to open. - * Device identifier or NULL on error. - * - * SDL_HapticIndex - * SDL_HapticOpenFromMouse - * SDL_HapticOpenFromJoystick - * SDL_HapticClose - * SDL_HapticSetGain - * SDL_HapticSetAutocenter - * SDL_HapticPause - * SDL_HapticStopAll - *} -function SDL_HapticOpen(device_index: cint): PSDL_Haptic cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpen' {$ENDIF} {$ENDIF}; + * Open a haptic device for use. + * + * The index passed as an argument refers to the N'th haptic device on this + * system. + * + * When opening a haptic device, its gain will be set to maximum and + * autocenter will be disabled. To modify these values use SDL_HapticSetGain() + * and SDL_HapticSetAutocenter(). + * + * \param device_index index of the device to open + * \returns the device identifier or NULL on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticClose + * \sa SDL_HapticIndex + * \sa SDL_HapticOpenFromJoystick + * \sa SDL_HapticOpenFromMouse + * \sa SDL_HapticPause + * \sa SDL_HapticSetAutocenter + * \sa SDL_HapticSetGain + * \sa SDL_HapticStopAll + *} +function SDL_HapticOpen(device_index: cint): PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpen' {$ENDIF} {$ENDIF}; {** - * Checks if the haptic device at index has been opened. - * - * device_index Index to check to see if it has been opened. - * 1 if it has been opened or 0 if it hasn't. - * - * SDL_HapticOpen - * SDL_HapticIndex - *} -function SDL_HapticOpened(device_index: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpened' {$ENDIF} {$ENDIF}; + * Check if the haptic device at the designated index has been opened. + * + * \param device_index the index of the device to query + * \returns 1 if it has been opened, 0 if it hasn't or on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticIndex + * \sa SDL_HapticOpen + *} +function SDL_HapticOpened(device_index: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpened' {$ENDIF} {$ENDIF}; {** - * Gets the index of a haptic device. - * - * haptic Haptic device to get the index of. - * The index of the haptic device or -1 on error. - * - * SDL_HapticOpen - * SDL_HapticOpened - *} -function SDL_HapticIndex(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticIndex' {$ENDIF} {$ENDIF}; + * Get the index of a haptic device. + * + * \param haptic the SDL_Haptic device to query + * \returns the index of the specified haptic device or a negative error code + * on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + * \sa SDL_HapticOpened + *} +function SDL_HapticIndex(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticIndex' {$ENDIF} {$ENDIF}; {** - * Gets whether or not the current mouse has haptic capabilities. - * - * SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't. - * - * SDL_HapticOpenFromMouse - *} -function SDL_MouseIsHaptic: cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MouseInHaptic' {$ENDIF} {$ENDIF}; + * Query whether or not the current mouse has haptic capabilities. + * + * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpenFromMouse + *} +function SDL_MouseIsHaptic: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MouseInHaptic' {$ENDIF} {$ENDIF}; {** - * Tries to open a haptic device from the current mouse. - * - * The haptic device identifier or NULL on error. - * - * SDL_MouseIsHaptic - * SDL_HapticOpen - *} -function SDL_HapticOpenFromMouse: PSDL_Haptic cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpenFromMouse' {$ENDIF} {$ENDIF}; + * Try to open a haptic device from the current mouse. + * + * \returns the haptic device identifier or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + * \sa SDL_MouseIsHaptic + *} +function SDL_HapticOpenFromMouse: PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpenFromMouse' {$ENDIF} {$ENDIF}; {** - * Checks to see if a joystick has haptic features. - * - * joystick Joystick to test for haptic capabilities. - * 1 if the joystick is haptic, 0 if it isn't - * or -1 if an error ocurred. - * - * SDL_HapticOpenFromJoystick - *} -function SDL_JoystickIsHaptic(joystick: PSDL_Joystick): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickIsHaptic' {$ENDIF} {$ENDIF}; + * Query if a joystick has haptic features. + * + * \param joystick the SDL_Joystick to test for haptic capabilities + * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpenFromJoystick + *} +function SDL_JoystickIsHaptic(joystick: PSDL_Joystick): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickIsHaptic' {$ENDIF} {$ENDIF}; {** - * Opens a Haptic device for usage from a Joystick device. - * - * You must still close the haptic device seperately. It will not be closed - * with the joystick. - * - * When opening from a joystick you should first close the haptic device before - * closing the joystick device. If not, on some implementations the haptic - * device will also get unallocated and you'll be unable to use force feedback - * on that device. - * - * joystick Joystick to create a haptic device from. - * A valid haptic device identifier on success or NULL on error. - * - * SDL_HapticOpen - * SDL_HapticClose - *} -function SDL_HapticOpenFromJoystick(joystick: PSDL_Joystick): PSDL_Haptic cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpenFromJoystick' {$ENDIF} {$ENDIF}; + * Open a haptic device for use from a joystick device. + * + * You must still close the haptic device separately. It will not be closed + * with the joystick. + * + * When opened from a joystick you should first close the haptic device before + * closing the joystick device. If not, on some implementations the haptic + * device will also get unallocated and you'll be unable to use force feedback + * on that device. + * + * \param joystick the SDL_Joystick to create a haptic device from + * \returns a valid haptic device identifier on success or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticClose + * \sa SDL_HapticOpen + * \sa SDL_JoystickIsHaptic + *} +function SDL_HapticOpenFromJoystick(joystick: PSDL_Joystick): PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticOpenFromJoystick' {$ENDIF} {$ENDIF}; {** - * Closes a Haptic device previously opened with SDL_HapticOpen(). - * - * haptic Haptic device to close. - *} -procedure SDL_HapticClose(haptic: PSDL_Haptic) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticClose' {$ENDIF} {$ENDIF}; + * Close a haptic device previously opened with SDL_HapticOpen(). + * + * \param haptic the SDL_Haptic device to close + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + *} +procedure SDL_HapticClose(haptic: PSDL_Haptic); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticClose' {$ENDIF} {$ENDIF}; {** - * Returns the number of effects a haptic device can store. - * - * On some platforms this isn't fully supported, and therefore is an - * approximation. Always check to see if your created effect was actually - * created and do not rely solely on SDL_HapticNumEffects(). - * - * haptic The haptic device to query effect max. - * The number of effects the haptic device can store or - * -1 on error. - * - * SDL_HapticNumEffectsPlaying - * SDL_HapticQuery - *} -function SDL_HapticNumEffects(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumEffects' {$ENDIF} {$ENDIF}; + * Get the number of effects a haptic device can store. + * + * On some platforms this isn't fully supported, and therefore is an + * approximation. Always check to see if your created effect was actually + * created and do not rely solely on SDL_HapticNumEffects(). + * + * \param haptic the SDL_Haptic device to query + * \returns the number of effects the haptic device can store or a negative + * error code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNumEffectsPlaying + * \sa SDL_HapticQuery + *} +function SDL_HapticNumEffects(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumEffects' {$ENDIF} {$ENDIF}; {** - * Returns the number of effects a haptic device can play at the same - * time. - * - * This is not supported on all platforms, but will always return a value. - * Added here for the sake of completeness. - * - * haptic The haptic device to query maximum playing effects. - * The number of effects the haptic device can play at the same time - * or -1 on error. - * - * SDL_HapticNumEffects - * SDL_HapticQuery - *} -function SDL_HapticNumEffectsPlaying(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumEffectsPlaying' {$ENDIF} {$ENDIF}; + * Get the number of effects a haptic device can play at the same time. + * + * This is not supported on all platforms, but will always return a value. + * + * \param haptic the SDL_Haptic device to query maximum playing effects + * \returns the number of effects the haptic device can play at the same time + * or a negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNumEffects + * \sa SDL_HapticQuery + *} +function SDL_HapticNumEffectsPlaying(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumEffectsPlaying' {$ENDIF} {$ENDIF}; {** - * Gets the haptic devices supported features in bitwise matter. - * - * Example: - * - * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) - * printf("We have constant haptic effect!"); - * - * - * - * haptic The haptic device to query. - * Haptic features in bitwise manner (OR'd). - * - * SDL_HapticNumEffects - * SDL_HapticEffectSupported - *} -function SDL_HapticQuery(haptic: PSDL_Haptic): cuint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticQuery' {$ENDIF} {$ENDIF}; + * Get the haptic device's supported features in bitwise manner. + * + * \param haptic the SDL_Haptic device to query + * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 + * on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticEffectSupported + * \sa SDL_HapticNumEffects + *} +function SDL_HapticQuery(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticQuery' {$ENDIF} {$ENDIF}; {** - * Gets the number of haptic axes the device has. - * - * SDL_HapticDirection - *} -function SDL_HapticNumAxes(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumAxes' {$ENDIF} {$ENDIF}; + * Get the number of haptic axes the device has. + * + * The number of haptic axes might be useful if working with the + * SDL_HapticDirection effect. + * + * \param haptic the SDL_Haptic device to query + * \returns the number of axes on success or a negative error code on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} +function SDL_HapticNumAxes(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNumAxes' {$ENDIF} {$ENDIF}; {** - * Checks to see if effect is supported by haptic. - * - * haptic Haptic device to check on. - * effect Effect to check to see if it is supported. - * SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error. - * - * SDL_HapticQuery - * SDL_HapticNewEffect - *} -function SDL_HapticEffectSupported(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticEffectSupported' {$ENDIF} {$ENDIF}; + * Check to see if an effect is supported by a haptic device. + * + * \param haptic the SDL_Haptic device to query + * \param effect the desired effect to query + * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNewEffect + * \sa SDL_HapticQuery + *} +function SDL_HapticEffectSupported(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticEffectSupported' {$ENDIF} {$ENDIF}; {** - * Creates a new haptic effect on the device. - * - * haptic Haptic device to create the effect on. - * effect Properties of the effect to create. - * The id of the effect on success or -1 on error. - * - * SDL_HapticUpdateEffect - * SDL_HapticRunEffect - * SDL_HapticDestroyEffect - *} -function SDL_HapticNewEffect(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNewEffect' {$ENDIF} {$ENDIF}; + * Create a new haptic effect on a specified device. + * + * \param haptic an SDL_Haptic device to create the effect on + * \param effect an SDL_HapticEffect structure containing the properties of + * the effect to create + * \returns the ID of the effect on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticDestroyEffect + * \sa SDL_HapticRunEffect + * \sa SDL_HapticUpdateEffect + *} +function SDL_HapticNewEffect(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticNewEffect' {$ENDIF} {$ENDIF}; {** - * Updates the properties of an effect. - * - * Can be used dynamically, although behaviour when dynamically changing - * direction may be strange. Specifically the effect may reupload itself - * and start playing from the start. You cannot change the type either when - * running SDL_HapticUpdateEffect(). - * - * haptic Haptic device that has the effect. - * effect Effect to update. - * data New effect properties to use. - * The id of the effect on success or -1 on error. - * - * SDL_HapticNewEffect - * SDL_HapticRunEffect - * SDL_HapticDestroyEffect - *} -function SDL_HapticUpdateEffect(haptic: PSDL_Haptic; effect: cint; data: PSDL_HapticEffect): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticUpdateEffect' {$ENDIF} {$ENDIF}; + * Update the properties of an effect. + * + * Can be used dynamically, although behavior when dynamically changing + * direction may be strange. Specifically the effect may re-upload itself and + * start playing from the start. You also cannot change the type either when + * running SDL_HapticUpdateEffect(). + * + * \param haptic the SDL_Haptic device that has the effect + * \param effect the identifier of the effect to update + * \param data an SDL_HapticEffect structure containing the new effect + * properties to use + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticDestroyEffect + * \sa SDL_HapticNewEffect + * \sa SDL_HapticRunEffect + *} +function SDL_HapticUpdateEffect(haptic: PSDL_Haptic; effect: cint; data: PSDL_HapticEffect): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticUpdateEffect' {$ENDIF} {$ENDIF}; {** - * Runs the haptic effect on its associated haptic device. - * - * If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over - * repeating the envelope (attack and fade) every time. If you only want the - * effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length - * parameter. - * - * haptic Haptic device to run the effect on. - * effect Identifier of the haptic effect to run. - * iterations Number of iterations to run the effect. Use - * SDL_HAPTIC_INFINITY for infinity. - * 0 on success or -1 on error. - * - * SDL_HapticStopEffect - * SDL_HapticDestroyEffect - * SDL_HapticGetEffectStatus - *} -function SDL_HapticRunEffect(haptic: PSDL_Haptic; effect: cint; iterations: cuint32): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRunEffect' {$ENDIF} {$ENDIF}; + * Run the haptic effect on its associated haptic device. + * + * To repeat the effect over and over indefinitely, set `iterations` to + * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make + * one instance of the effect last indefinitely (so the effect does not fade), + * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` + * instead. + * + * \param haptic the SDL_Haptic device to run the effect on + * \param effect the ID of the haptic effect to run + * \param iterations the number of iterations to run the effect; use + * `SDL_HAPTIC_INFINITY` to repeat forever + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticDestroyEffect + * \sa SDL_HapticGetEffectStatus + * \sa SDL_HapticStopEffect + *} +function SDL_HapticRunEffect(haptic: PSDL_Haptic; effect: cint; iterations: cuint32): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRunEffect' {$ENDIF} {$ENDIF}; {** - * Stops the haptic effect on its associated haptic device. - * - * haptic Haptic device to stop the effect on. - * effect Identifier of the effect to stop. - * 0 on success or -1 on error. - * - * SDL_HapticRunEffect - * SDL_HapticDestroyEffect - *} -function SDL_HapticStopEffect(haptic: PSDL_Haptic; effect: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticStopEffect' {$ENDIF} {$ENDIF}; + * Stop the haptic effect on its associated haptic device. + * + * * + * + * \param haptic the SDL_Haptic device to stop the effect on + * \param effect the ID of the haptic effect to stop + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticDestroyEffect + * \sa SDL_HapticRunEffect + *} +function SDL_HapticStopEffect(haptic: PSDL_Haptic; effect: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticStopEffect' {$ENDIF} {$ENDIF}; {** - * Destroys a haptic effect on the device. - * - * This will stop the effect if it's running. Effects are automatically - * destroyed when the device is closed. - * - * haptic Device to destroy the effect on. - * effect Identifier of the effect to destroy. - * - * SDL_HapticNewEffect - *} -procedure SDL_HapticDestroyEffect(haptic: PSDL_Haptic; effect: cint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticDestroyEffect' {$ENDIF} {$ENDIF}; + * Destroy a haptic effect on the device. + * + * This will stop the effect if it's running. Effects are automatically + * destroyed when the device is closed. + * + * \param haptic the SDL_Haptic device to destroy the effect on + * \param effect the ID of the haptic effect to destroy + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNewEffect + *} +procedure SDL_HapticDestroyEffect(haptic: PSDL_Haptic; effect: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticDestroyEffect' {$ENDIF} {$ENDIF}; {** - * Gets the status of the current effect on the haptic device. - * - * Device must support the ::SDL_HAPTIC_STATUS feature. - * - * haptic Haptic device to query the effect status on. - * effect Identifier of the effect to query its status. - * 0 if it isn't playing, 1 if it is playing or -1 on error. - * - * SDL_HapticRunEffect - * SDL_HapticStopEffect - *} -function SDL_HapticGetEffectStatus(haptic: PSDL_Haptic; effect: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticGetEffectStatus' {$ENDIF} {$ENDIF}; + * Get the status of the current effect on the specified haptic device. + * + * Device must support the SDL_HAPTIC_STATUS feature. + * + * \param haptic the SDL_Haptic device to query for the effect status on + * \param effect the ID of the haptic effect to query its status + * \returns 0 if it isn't playing, 1 if it is playing, or a negative error + * code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticRunEffect + * \sa SDL_HapticStopEffect + *} +function SDL_HapticGetEffectStatus(haptic: PSDL_Haptic; effect: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticGetEffectStatus' {$ENDIF} {$ENDIF}; {** - * Sets the global gain of the device. - * - * Device must support the SDL_HAPTIC_GAIN feature. - * - * The user may specify the maximum gain by setting the environment variable - * SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to - * SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the - * maximum. - * - * haptic Haptic device to set the gain on. - * gain Value to set the gain to, should be between 0 and 100. - * 0 on success or -1 on error. - * - * SDL_HapticQuery - *} -function SDL_HapticSetGain(haptic: PSDL_Haptic; gain: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticSetGain' {$ENDIF} {$ENDIF}; + * Set the global gain of the specified haptic device. + * + * Device must support the SDL_HAPTIC_GAIN feature. + * + * The user may specify the maximum gain by setting the environment variable + * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to + * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the + * maximum. + * + * \param haptic the SDL_Haptic device to set the gain on + * \param gain value to set the gain to, should be between 0 and 100 (0 - 100) + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticQuery + *} +function SDL_HapticSetGain(haptic: PSDL_Haptic; gain: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticSetGain' {$ENDIF} {$ENDIF}; {** - * Sets the global autocenter of the device. - * - * Autocenter should be between 0 and 100. Setting it to 0 will disable - * autocentering. - * - * Device must support the ::SDL_HAPTIC_AUTOCENTER feature. - * - * haptic Haptic device to set autocentering on. - * autocenter Value to set autocenter to, 0 disables autocentering. - * 0 on success or -1 on error. - * - * SDL_HapticQuery - *} -function SDL_HapticSetAutocenter(haptic: PSDL_Haptic; autocenter: cint): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticSetAutocenter' {$ENDIF} {$ENDIF}; + * Set the global autocenter of the device. + * + * Autocenter should be between 0 and 100. Setting it to 0 will disable + * autocentering. + * + * Device must support the SDL_HAPTIC_AUTOCENTER feature. + * + * \param haptic the SDL_Haptic device to set autocentering on + * \param autocenter value to set autocenter to (0-100) + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticQuery + *} +function SDL_HapticSetAutocenter(haptic: PSDL_Haptic; autocenter: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticSetAutocenter' {$ENDIF} {$ENDIF}; {** - * Pauses a haptic device. - * - * Device must support the SDL_HAPTIC_PAUSE feature. Call - * SDL_HapticUnpause() to resume playback. - * - * Do not modify the effects nor add new ones while the device is paused. - * That can cause all sorts of weird errors. - * - * haptic Haptic device to pause. - * 0 on success or -1 on error. - * - * SDL_HapticUnpause - *} -function SDL_HapticPause(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticPause' {$ENDIF} {$ENDIF}; + * Pause a haptic device. + * + * Device must support the `SDL_HAPTIC_PAUSE` feature. Call + * SDL_HapticUnpause() to resume playback. + * + * Do not modify the effects nor add new ones while the device is paused. That + * can cause all sorts of weird errors. + * + * \param haptic the SDL_Haptic device to pause + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticUnpause + *} +function SDL_HapticPause(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticPause' {$ENDIF} {$ENDIF}; {** - * Unpauses a haptic device. - * - * Call to unpause after SDL_HapticPause(). - * - * haptic Haptic device to pause. - * 0 on success or -1 on error. - * - * SDL_HapticPause - *} -function SDL_HapticUnpause(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticUnPause' {$ENDIF} {$ENDIF}; + * Unpause a haptic device. + * + * Call to unpause after SDL_HapticPause(). + * + * \param haptic the SDL_Haptic device to unpause + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticPause + *} +function SDL_HapticUnpause(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticUnPause' {$ENDIF} {$ENDIF}; {** - * Stops all the currently playing effects on a haptic device. - * - * haptic Haptic device to stop. - * 0 on success or -1 on error. - *} -function SDL_HapticStopAll(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticStopAll' {$ENDIF} {$ENDIF}; + * Stop all the currently playing effects on a haptic device. + * + * \param haptic the SDL_Haptic device to stop + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} +function SDL_HapticStopAll(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticStopAll' {$ENDIF} {$ENDIF}; {** - * Checks to see if rumble is supported on a haptic device.. - * - * haptic Haptic device to check to see if it supports rumble. - * SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error. - * - * SDL_HapticRumbleInit - * SDL_HapticRumblePlay - * SDL_HapticRumbleStop - *} -function SDL_HapticRumbleSupported(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleSupported' {$ENDIF} {$ENDIF}; + * Check whether rumble is supported on a haptic device. + * + * \param haptic haptic device to check for rumble support + * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticRumbleInit + * \sa SDL_HapticRumblePlay + * \sa SDL_HapticRumbleStop + *} +function SDL_HapticRumbleSupported(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleSupported' {$ENDIF} {$ENDIF}; {** - * Initializes the haptic device for simple rumble playback. - * - * haptic Haptic device to initialize for simple rumble playback. - * 0 on success or -1 on error. - * - * SDL_HapticOpen - * SDL_HapticRumbleSupported - * SDL_HapticRumblePlay - * SDL_HapticRumbleStop - *} -function SDL_HapticRumbleInit(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleInit' {$ENDIF} {$ENDIF}; + * Initialize a haptic device for simple rumble playback. + * + * \param haptic the haptic device to initialize for simple rumble playback + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + * \sa SDL_HapticRumblePlay + * \sa SDL_HapticRumbleStop + * \sa SDL_HapticRumbleSupported + *} +function SDL_HapticRumbleInit(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleInit' {$ENDIF} {$ENDIF}; {** - * Runs simple rumble on a haptic device - * - * haptic Haptic device to play rumble effect on. - * strength Strength of the rumble to play as a 0-1 float value. - * length Length of the rumble to play in milliseconds. - * 0 on success or -1 on error. - * - * SDL_HapticRumbleSupported - * SDL_HapticRumbleInit - * SDL_HapticRumbleStop - *} -function SDL_HapticRumblePlay(haptic: PSDL_Haptic; strength: cfloat; length: cuint32): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumblePlay' {$ENDIF} {$ENDIF}; + * Run a simple rumble effect on a haptic device. + * + * \param haptic the haptic device to play the rumble effect on + * \param strength strength of the rumble to play as a 0-1 float value + * \param length length of the rumble to play in milliseconds + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticRumbleInit + * \sa SDL_HapticRumbleStop + * \sa SDL_HapticRumbleSupported + *} +function SDL_HapticRumblePlay(haptic: PSDL_Haptic; strength: cfloat; length: cuint32): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumblePlay' {$ENDIF} {$ENDIF}; {** - * Stops the simple rumble on a haptic device. - * - * haptic Haptic to stop the rumble on. - * 0 on success or -1 on error. - * - * SDL_HapticRumbleSupported - * SDL_HapticRumbleInit - * SDL_HapticRumblePlay - *} -function SDL_HapticRumbleStop(haptic: PSDL_Haptic): cint cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleStop' {$ENDIF} {$ENDIF}; + * Stop the simple rumble on a haptic device. + * + * \param haptic the haptic device to stop the rumble effect on + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticRumbleInit + * \sa SDL_HapticRumblePlay + * \sa SDL_HapticRumbleSupported + *} +function SDL_HapticRumbleStop(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleStop' {$ENDIF} {$ENDIF}; diff --git a/units/sdlhidapi.inc b/units/sdlhidapi.inc new file mode 100644 index 00000000..570d2c70 --- /dev/null +++ b/units/sdlhidapi.inc @@ -0,0 +1,426 @@ +// from SDL_hidapi.h + +(** + * Header file for SDL HIDAPI functions. + * + * This is an adaptation of the original HIDAPI interface by Alan Ott, + * and includes source code licensed under the following BSD license: + * + Copyright (c) 2010, Alan Ott, Signal 11 Software + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of Signal 11 Software nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + * + * If you would like a version of SDL without this code, you can build SDL + * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example + * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework. + *) + +type + (** + * \brief A handle representing an open HID device. + *) + PSDL_hid_device = type Pointer; + + PSDL_hid_device_info = ^TSDL_hid_device_info; + + (** + * \brief Information about a connected HID device + *) + TSDL_hid_device_info = record + (** Platform-specific device path *) + path: PAnsiChar; + (** Device Vendor ID *) + vendor_id: pcushort; + (** Device Product ID *) + product_id: pcushort; + (** Serial Number *) + serial_number: pcwchar_t; + (** Device Release Number in binary-coded decimal, also known as Device Version Number *) + release_number: cushort; + (** Manufacturer String *) + manufacturer_string: pcwchar_t; + (** Product string *) + product_string: pcwchar_t; + (** Usage Page for this Device/Interface (Windows/Mac only). *) + usage_page: cushort; + (** Usage for this Device/Interface (Windows/Mac only). *) + usage: cushort; + (** + * The USB interface which this logical device represents. + * Valid on both Linux implementations in all cases. + * Valid on the Windows implementation only if the device + * contains more than one interface. + *) + interface_number: cint; + + (** + * Additional information about the USB interface. + * Valid on libusb and Android implementations. + *) + interface_class: cint; + interface_subclass: cint; + interface_protocol: cint; + + (** Pointer to the next device *) + next: PSDL_hid_device_info; + end; + +(** + * 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. + * + * Each call to this function should have a matching call to SDL_hid_exit() + * + * \returns 0 on success and -1 on error. + * + * \since This function is available since SDL 2.0.18. + * + * \sa SDL_hid_exit + *) +function SDL_hid_init(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_init' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * \returns 0 on success and -1 on error. + * + * \since This function is available since SDL 2.0.18. + * + * \sa SDL_hid_init + *) +function SDL_hid_exit(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_exit' {$ENDIF} {$ENDIF}; + +(** + * Check to see if devices may have been added or removed. + * + * Enumerating the HID devices is an expensive operation, so you can call this + * to see if there have been any system device changes since the last call to + * this function. A change in the counter returned doesn't necessarily mean + * that anything has changed, but you can call SDL_hid_enumerate() to get an + * updated device list. + * + * Calling this function for the first time may cause a thread or other system + * resource to be allocated to track device change notifications. + * + * \returns a change counter that is incremented with each potential device + * change, or 0 if device change detection isn't available. + * + * \since This function is available since SDL 2.0.18. + * + * \sa SDL_hid_enumerate + *) +function SDL_hid_device_change_count(): cUint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_device_change_count' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * \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 NIL + * 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. + * + * \sa SDL_hid_device_change_count + *) +function SDL_hid_enumerate(vendor_id, product_id: cushort): PSDL_hid_device_info; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_enumerate' {$ENDIF} {$ENDIF}; + +(** + * Free an enumeration Linked List + * + * 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(). + * + * \since This function is available since SDL 2.0.18. + *) +procedure SDL_hid_free_enumeration(devs: PSDL_hid_device_info); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_free_enumeration' {$ENDIF} {$ENDIF}; + +(** + * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally + * a serial number. + * + * If `serial_number` is NULL, the first device with the specified VID and PID + * is opened. + * + * \param vendor_id The Vendor ID (VID) of the device to open. + * \param product_id The Product ID (PID) of the device to open. + * \param serial_number The Serial Number of the device to open + * (optionally NIL). + * \returns a pointer to a SDL_hid_device object on success or NIL on + * failure. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_open(vendor_id, product_id: cushort; serial_number: pcwchar_t): PSDL_hid_device; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_open' {$ENDIF} {$ENDIF}; + +(** + * Open a HID device by its path name. + * + * The path name be determined by calling SDL_hid_enumerate(), or a + * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). + * + * \param path The path name of the device to open + * \returns a pointer to a SDL_hid_device object on success + * or NIL on failure. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_open_path(path: PAnsiChar; bExclusive: cuint): PSDL_hid_device; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_open_path' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * 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 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. + *) +function SDL_hid_write(dev: PSDL_hid_device; data: pcUint8; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_write' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * \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 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. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_read_timeout(dev: PSDL_hid_device; data: pcUint8; length: csize_t; milliseconds: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_read_timeout' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * \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. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_read(dev: PSDL_hid_device; data: pcUint8; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_read' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * 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. + * \returns 0 on success and -1 on error. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_set_nonblocking(dev: PSDL_hid_device; nonblock: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_set_nonblocking' {$ENDIF} {$ENDIF}; + +(** + * 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. + * + * \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. + * \returns the actual number of bytes written and -1 on error. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_send_feature_report(dev: PSDL_hid_device; data: pcUint8; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_send_feature_report' {$ENDIF} {$ENDIF}; + +(** + * 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]. + * + * \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. + * + * \since This function is available since SDL 2.0.18. + *) +function SDL_hid_get_feature_report(dev: PSDL_hid_device; data: pcUint8; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_feature_report' {$ENDIF} {$ENDIF}; + +(** + * Close a HID device. + * + * \param dev A device handle returned from SDL_hid_open(). + * + * \since This function is available since SDL 2.0.18. + *) +procedure SDL_hid_close(dev: PSDL_hid_device); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_close' {$ENDIF} {$ENDIF}; + +(** + * Get The Manufacturer String from a HID device. + * + * \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. + *) +function SDL_hid_get_manufacturer_string(dev: PSDL_hid_device; str: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_manufacturer_string' {$ENDIF} {$ENDIF}; + +(** + * Get The Product String from a HID device. + * + * \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. + *) +function SDL_hid_get_product_string(dev: PSDL_hid_device; str: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_product_string' {$ENDIF} {$ENDIF}; + +(** + * Get The Serial Number String from a HID device. + * + * \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. + *) +function SDL_hid_get_serial_number_string(dev: PSDL_hid_device; str: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_serial_number_string' {$ENDIF} {$ENDIF}; + +(** + * Get a string from a HID device, based on its string index. + * + * \param dev A device handle returned from SDL_hid_open(). + * \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. + *) +function SDL_hid_get_indexed_string(dev: PSDL_hid_device; string_index: cint; str: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_indexed_string' {$ENDIF} {$ENDIF}; + +(** + * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers + * + * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan + * + * \since This function is available since SDL 2.0.18. + *) +procedure SDL_hid_ble_scan(active: TSDL_bool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_ble_scan' {$ENDIF} {$ENDIF}; diff --git a/units/sdlhints.inc b/units/sdlhints.inc index b5b1a3ff..32d60caf 100644 --- a/units/sdlhints.inc +++ b/units/sdlhints.inc @@ -65,6 +65,19 @@ SDL_HINT_ENABLE_STEAM_CONTROLLERS = 'SDL_ENABLE_STEAM_CONTROLLERS'; */} SDL_HINT_EVENT_LOGGING = 'SDL_EVENT_LOGGING'; +{** + * \brief A variable controlling whether raising the window should be done more forcefully + * + * This variable can be set to the following values: + * "0" - No forcing (the default) + * "1" - Extra level of forcing + * + * At present, this is only an issue under MS Windows, which makes it nearly impossible to + * programmatically move a window to the foreground, for "security" reasons. See + * http://stackoverflow.com/a/34414846 for a discussion. + *} +SDL_HINT_FORCE_RAISEWINDOW = 'SDL_HINT_FORCE_RAISEWINDOW'; + {/** * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. * @@ -230,6 +243,17 @@ SDL_HINT_RENDER_SCALE_QUALITY = 'SDL_RENDER_SCALE_QUALITY'; */} SDL_HINT_RENDER_VSYNC = 'SDL_RENDER_VSYNC'; +{** + * \brief A variable controlling if VSYNC is automatically disable if doesn't reach the enough FPS + * + * This variable can be set to the following values: + * "0" - It will be using VSYNC as defined in the main flag. Default + * "1" - If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed + * + * By default SDL does not enable the automatic VSYNC + *} +SDL_HINT_PS2_DYNAMIC_VSYNC = 'SDL_PS2_DYNAMIC_VSYNC'; + {/** * \brief A variable controlling whether the screensaver is enabled. * @@ -297,6 +321,54 @@ SDL_HINT_VIDEO_EXTERNAL_CONTEXT = 'SDL_VIDEO_EXTERNAL_CONTEXT'; */} SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR = 'SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR'; +{** + * \brief A variable controlling whether the libdecor Wayland backend is preferred over native decrations. + * + * When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is + * available. (Note that, by default, libdecor will use xdg-decoration itself if available). + * + * This variable can be set to the following values: + * "0" - libdecor is enabled only if server-side decorations are unavailable. + * "1" - libdecor is always enabled if available. + * + * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + *} +SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR = 'SDL_VIDEO_WAYLAND_PREFER_LIBDECOR'; + +{** + * \brief A variable controlling whether video mode emulation is enabled under Wayland. + * + * When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application. + * If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. + * + * This variable can be set to the following values: + * "0" - Video mode emulation is disabled. + * "1" - Video mode emulation is enabled. + * + * By default video mode emulation is enabled. + *} +SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION = 'SDL_VIDEO_WAYLAND_MODE_EMULATION'; + +{** + * \brief Enable or disable mouse pointer warp emulation, needed by some older games. + * + * When this hint is set, any SDL will emulate mouse warps using relative mouse mode. + * This is required for some older games (such as Source engine games), which warp the + * mouse to the centre of the screen rather than using relative mouse motion. Note that + * relative mouse mode may have different mouse acceleration behaviour than pointer warps. + * + * This variable can be set to the following values: + * "0" - All mouse warps fail, as mouse warping is not available under Wayland. + * "1" - Some mouse warps will be emulated by forcing relative mouse mode. + * + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP = 'SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP'; + {/** * \brief Specify an "activity name" for screensaver inhibition. * @@ -482,6 +554,57 @@ SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL = 'SDL_WINDOWS_INTRESOURCE_ICON_SMALL'; */} SDL_HINT_WINDOWS_USE_D3D9EX = 'SDL_WINDOWS_USE_D3D9EX'; +{** + * \brief Controls whether SDL will declare the process to be DPI aware. + * + * This hint must be set before initializing the video subsystem. + * + * The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with + * a DPI scale factor. + * + * This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext) + * and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel + * even on high-DPI displays. + * + * For more information, see: + * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows + * + * This variable can be set to the following values: + * "" - Do not change the DPI awareness (default). + * "unaware" - Declare the process as DPI unaware. (Windows 8.1 and later). + * "system" - Request system DPI awareness. (Vista and later). + * "permonitor" - Request per-monitor DPI awareness. (Windows 8.1 and later). + * "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later). + * The most visible difference from "permonitor" is that window title bar will be scaled + * to the visually correct size when dragging between monitors with different scale factors. + * This is the preferred DPI awareness level. + * + * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best + * available match. + *} +SDL_HINT_WINDOWS_DPI_AWARENESS = 'SDL_WINDOWS_DPI_AWARENESS'; + +{** + * \brief Uses DPI-scaled points as the SDL coordinate system on Windows. + * + * This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere. + * This means windows will be appropriately sized, even when created on high-DPI displays with scaling. + * + * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings, + * will create a window with an 800x600 client area (in pixels). + * + * Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary), + * and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows. + * + * This variable can be set to the following values: + * "0" - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging + * between monitors with different scale factors (unless this is performed by + * Windows itself, which is the case when the process is DPI unaware). + * "1" - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on + * displays with non-100% scale factors. + *} +SDL_HINT_WINDOWS_DPI_SCALING = 'SDL_WINDOWS_DPI_SCALING'; + {/** * \brief A variable controlling whether grabbing input grabs the keyboard * @@ -493,6 +616,29 @@ SDL_HINT_WINDOWS_USE_D3D9EX = 'SDL_WINDOWS_USE_D3D9EX'; */} SDL_HINT_GRAB_KEYBOARD = 'SDL_GRAB_KEYBOARD'; +{** + * \brief A variable containing a list of devices to ignore in SDL_hid_enumerate() + * + * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might + * have the string "0x2563/0x0523,0x28de/0x0000". + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_HIDAPI_IGNORE_DEVICES = 'SDL_HIDAPI_IGNORE_DEVICES'; + +{** + * \brief A variable controlling whether the mouse is captured while mouse buttons are pressed + * + * This variable can be set to the following values: + * "0" - The mouse is not captured while mouse buttons are pressed + * "1" - The mouse is captured while mouse buttons are pressed + * + * By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged + * outside the window, the application continues to receive mouse events until the button is + * released. + *} +SDL_HINT_MOUSE_AUTO_CAPTURE = 'SDL_MOUSE_AUTO_CAPTURE'; + {/** * \brief A variable setting the double click radius, in pixels. */} @@ -519,6 +665,22 @@ SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH = 'SDL_MOUSE_FOCUS_CLICKTHROUGH'; */} SDL_HINT_MOUSE_NORMAL_SPEED_SCALE = 'SDL_MOUSE_NORMAL_SPEED_SCALE'; +{** + * \brief A variable controlling whether relative mouse mode constrains the mouse to the center of the window + * + * This variable can be set to the following values: + * "0" - Relative mouse mode constrains the mouse to the window + * "1" - Relative mouse mode constrains the mouse to the center of the window + * + * Constraining to the center of the window works better for FPS games and when the + * application is running over RDP. Constraining to the whole window works better + * for 2D games and increases the chance that the mouse will be in the correct + * position when using high DPI mice. + * + * By default SDL will constrain the mouse to the center of the window + *} +SDL_HINT_MOUSE_RELATIVE_MODE_CENTER = 'SDL_MOUSE_RELATIVE_MODE_CENTER'; + {/** * \brief A variable controlling whether relative mouse mode is implemented using mouse warping * @@ -546,6 +708,30 @@ SDL_HINT_MOUSE_RELATIVE_SCALING = 'SDL_MOUSE_RELATIVE_SCALING'; */} SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE = 'SDL_MOUSE_RELATIVE_SPEED_SCALE'; +{** + * \brief A variable controlling whether the system mouse acceleration curve is used for relative mouse motion. + * + * This variable can be set to the following values: + * "0" - Relative mouse motion will be unscaled (the default) + * "1" - Relative mouse motion will be scaled using the system mouse acceleration curve. + * + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE = 'SDL_MOUSE_RELATIVE_SYSTEM_SCALE'; + +{** + * \brief A variable controlling whether a motion event should be generated for mouse warping in relative mode. + * + * This variable can be set to the following values: + * "0" - Warping the mouse will not generate a motion event in relative mode + * "1" - Warping the mouse will generate a motion event in relative mode + * + * By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping. + *} +SDL_HINT_MOUSE_RELATIVE_WARP_MOTION = 'SDL_MOUSE_RELATIVE_WARP_MOTION'; + {/** * \brief A variable controlling whether mouse events should generate synthetic touch events * @@ -971,6 +1157,25 @@ SDL_HINT_AUTO_UPDATE_SENSORS = 'SDL_AUTO_UPDATE_SENSORS'; */} SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT = 'SDL_X11_FORCE_OVERRIDE_REDIRECT'; +{** + * \brief A variable that forces X11 windows to create as a custom type. + * + * This is currently only used for X11 and ignored elsewhere. + * + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property + * to report to the window manager the type of window it wants to create. + * This might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". + * + * If not set or set to "", this hint is ignored. This hint must be set + * before the SDL_CreateWindow() call that it is intended to affect. + * + *} +SDL_HINT_X11_WINDOW_TYPE = 'SDL_X11_WINDOW_TYPE'; + {/** * \brief A variable that lets you disable the detection and use of Xinput gamepad devices * @@ -980,6 +1185,15 @@ SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT = 'SDL_X11_FORCE_OVERRIDE_REDIRECT'; */} SDL_HINT_XINPUT_ENABLED = 'SDL_XINPUT_ENABLED'; +{** + * \brief A variable that lets you disable the detection and use of DirectInput gamepad devices + * + * The variable can be set to the following values: + * "0" - Disable DirectInput detection (only uses XInput) + * "1" - Enable DirectInput detection (the default) + *} +SDL_HINT_DIRECTINPUT_ENABLED = 'SDL_DIRECTINPUT_ENABLED'; + {** * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices. * @@ -1108,6 +1322,21 @@ SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS = 'SDL_JOYSTICK_ALLOW_BACKGROUND_EVENT *} SDL_HINT_JOYSTICK_DEVICE = 'SDL_JOYSTICK_DEVICE'; +{** + * \brief A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement + * the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2) + * this is useful for applications that need full compatibility for things like ADSR envelopes. + * Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0" + * Rumble is both at any arbitrary value, + * StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0" + * + * This variable can be set to the following values: + * "0" - Normal rumble behavior is behavior is used (default) + * "1" - Proper GameCube controller rumble behavior is used + * + *} +SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE = 'SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE'; + {/** * \brief A variable controlling whether the HIDAPI joystick drivers should be used. * @@ -1141,6 +1370,28 @@ SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE = 'SDL_JOYSTICK_HIDAPI_GAMECUBE'; */} SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_JOY_CONS'; +{** + * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver + * + * This variable can be set to the following values: + * "0" - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad + * "1" - Left and right Joy-Con controllers will be combined into a single controller (the default) + *} +SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS'; + +{** + * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver + * + * This variable can be set to the following values: + * "0" - Left and right Joy-Con controllers will not be in vertical mode (the default) + * "1" - Left and right Joy-Con controllers will be in vertical mode + * + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER). + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS'; + {/** * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used. * @@ -1152,6 +1403,44 @@ SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_JOY_CONS'; */} SDL_HINT_JOYSTICK_HIDAPI_LUNA = 'SDL_JOYSTICK_HIDAPI_LUNA'; +{** + * \brief A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + *} +SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC = 'SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC'; + +{** + * \brief A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + *} +SDL_HINT_JOYSTICK_HIDAPI_SHIELD = 'SDL_JOYSTICK_HIDAPI_SHIELD'; + +{** + * \brief A variable controlling whether the HIDAPI driver for PS3 controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms. + * + * It is not possible to use this driver on Windows, due to limitations in the default drivers + * installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_PS3 = 'SDL_JOYSTICK_HIDAPI_PS3'; + {/** * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used. * @@ -1267,6 +1556,50 @@ SDL_HINT_JOYSTICK_HIDAPI_SWITCH = 'SDL_JOYSTICK_HIDAPI_SWITCH'; */} SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED = 'SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED'; +{** + * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened + * + * This variable can be set to the following values: + * "0" - home button LED is turned off + * "1" - home button LED is turned on + * + * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + *} +SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED = 'SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED'; + +{** + * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller. + * + * This variable can be set to the following values: + * "0" - player LEDs are not enabled + * "1" - player LEDs are enabled (the default) + *} +SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED'; + +{** + * \brief A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_WII = 'SDL_JOYSTICK_HIDAPI_WII'; + +{** + * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller. + * + * This variable can be set to the following values: + * "0" - player LEDs are not enabled + * "1" - player LEDs are enabled (the default) + * + * This hiny is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED'; + {/** * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used. * @@ -1278,6 +1611,71 @@ SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED = 'SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED' */} SDL_HINT_JOYSTICK_HIDAPI_XBOX = 'SDL_JOYSTICK_HIDAPI_XBOX'; +{** + * \brief A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 = 'SDL_JOYSTICK_HIDAPI_XBOX_360'; + +{** + * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller. + * + * This variable can be set to the following values: + * "0" - player LEDs are not enabled + * "1" - player LEDs are enabled (the default) + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED'; + +{** + * \brief A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS = 'SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS'; + +{** + * \brief A variable controlling whether the HIDAPI driver for XBox One controllers should be used. + * + * This variable can be set to the following values: + * "0" - HIDAPI driver is not used + * "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE = 'SDL_JOYSTICK_HIDAPI_XBOX_ONE'; + +{** + * \brief A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened + * + * This variable can be set to the following values: + * "0" - home button LED is turned off + * "1" - home button LED is turned on + * + * By default the Home button LED state is not changed. This hint can also + * be set to a floating point value between 0.0 and 1.0 which controls + * the brightness of the Home button LED. The default brightness is 0.4. + * + * This hint is available since SDL 2.26.0. + *} +SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED = 'SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED'; + {/** * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. * @@ -1301,6 +1699,15 @@ SDL_HINT_JOYSTICK_RAWINPUT = 'SDL_JOYSTICK_RAWINPUT'; */} SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT = 'SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT'; +{** + * \brief A variable controlling whether the ROG Chakram mice should show up as joysticks + * + * This variable can be set to the following values: + * "0" - ROG Chakram mice do not show up as joysticks (the default) + * "1" - ROG Chakram mice show up as joysticks + *} +SDL_HINT_JOYSTICK_ROG_CHAKRAM = 'SDL_JOYSTICK_ROG_CHAKRAM'; + {/** * \brief A variable controlling whether a separate thread should be used * for handling joystick detection and raw input messages on Windows @@ -1395,6 +1802,18 @@ SDL_HINT_THREAD_STACK_SIZE = 'SDL_THREAD_STACK_SIZE'; */} SDL_HINT_TOUCH_MOUSE_EVENTS = 'SDL_TOUCH_MOUSE_EVENTS'; +{** + * \brief A variable controlling which touchpad should generate synthetic mouse events + * + * This variable can be set to the following values: + * "0" - Only front touchpad should generate mouse events. Default + * "1" - Only back touchpad should generate mouse events. + * "2" - Both touchpads should generate mouse events. + * + * By default SDL will generate mouse events for all touch devices + *} +SDL_HINT_VITA_TOUCH_MOUSE_DEVICE = 'SDL_HINT_VITA_TOUCH_MOUSE_DEVICE'; + {/** * \brief A variable controlling whether the Android / tvOS remotes * should be listed as joystick devices, instead of sending keyboard events. @@ -1410,6 +1829,24 @@ SDL_HINT_TV_REMOTE_AS_JOYSTICK = 'SDL_TV_REMOTE_AS_JOYSTICK'; */} SDL_HINT_VIDEO_HIGHDPI_DISABLED = 'SDL_VIDEO_HIGHDPI_DISABLED'; +{** + * \brief A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog. + * + * This variable can be set to the following values: + * "0" - Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital (the default) + * "1" - Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats + *} +SDL_HINT_LINUX_DIGITAL_HATS = 'SDL_LINUX_DIGITAL_HATS'; + +{** + * \brief A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values. + * + * This variable can be set to the following values: + * "0" - Return digital hat values based on unfiltered input axis values + * "1" - Return digital hat values with deadzones on the input axes taken into account (the default) + *} +SDL_HINT_LINUX_HAT_DEADZONES = 'SDL_LINUX_HAT_DEADZONES'; + {/** * \brief A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux * @@ -1438,6 +1875,23 @@ SDL_HINT_LINUX_JOYSTICK_DEADZONES = 'SDL_LINUX_JOYSTICK_DEADZONES'; */} SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK = 'SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK'; +{** + * \brief A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing + * + * This variable can be set to the following values: + * "0" - Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing (default). + * "1" - Dispatching OpenGL context updates will allow the dispatching thread to continue execution. + * + * Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread + * hangs because it's waiting for that background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. + * + * This hint only applies to macOS. + * + * This hint is available since SDL 2.24.0. + *} +SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH = 'SDL_MAC_OPENGL_ASYNC_DISPATCH'; + {/** * \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries * @@ -1473,6 +1927,28 @@ SDL_HINT_VIDEO_WIN_D3DCOMPILER = 'SDL_VIDEO_WIN_D3DCOMPILER'; */} SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT = 'SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT'; +{** + * \brief When calling SDL_CreateWindowFrom(), make the window compatible with OpenGL. + * + * This variable can be set to the following values: + * "0" - Don't add any graphics flags to the SDL_WindowFlags + * "1" - Add SDL_WINDOW_OPENGL to the SDL_WindowFlags + * + * By default SDL will not make the foreign window compatible with OpenGL. + *} +SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL = 'SDL_VIDEO_FOREIGN_WINDOW_OPENGL'; + +{** + * \brief When calling SDL_CreateWindowFrom(), make the window compatible with Vulkan. + * + * This variable can be set to the following values: + * "0" - Don't add any graphics flags to the SDL_WindowFlags + * "1" - Add SDL_WINDOW_VULKAN to the SDL_WindowFlags + * + * By default SDL will not make the foreign window compatible with Vulkan. + *} +SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN = 'SDL_VIDEO_FOREIGN_WINDOW_VULKAN'; + {/** * \brief A URL to a WinRT app's privacy policy * @@ -1686,6 +2162,17 @@ SDL_HINT_IME_INTERNAL_EDITING = 'SDL_IME_INTERNAL_EDITING'; */} SDL_HINT_IME_SHOW_UI = 'SDL_IME_SHOW_UI'; +{** + * \brief A variable to control if extended IME text support is enabled. + * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise. + * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated. + * + * The variable can be set to the following values: + * "0" - Legacy behavior. Text can be truncated, no heap allocations. (default) + * "1" - Modern behavior. + *} +SDL_HINT_IME_SUPPORT_EXTENDED_TEXT = 'SDL_IME_SUPPORT_EXTENDED_TEXT'; + {/** * \brief A variable to control whether mouse and touch events are to be treated together or separately * @@ -1693,10 +2180,13 @@ SDL_HINT_IME_SHOW_UI = 'SDL_IME_SHOW_UI'; * "0" - Mouse events will be handled as touch events, and touch will raise fake mouse * events. This is the behaviour of SDL <= 2.0.3. (default) * "1" - Mouse events will be handled separately from pure touch events. - * - * The value of this hint is used at runtime, so it can be changed at any time. + * + * NOTE: This hint is no longer supported on SDL >= 2.0.10. + * Use SDL_HINT_MOUSE_TOUCH_EVENTS and SDL_HINT_TOUCH_MOUSE_EVENTS + * for generating synthetic touch/mouse events. */} -SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH = 'SDL_ANDROID_SEPARATE_MOUSE_AND_TOUCH'; +SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH = 'SDL_ANDROID_SEPARATE_MOUSE_AND_TOUCH' + deprecated 'This hint is no longer supported on SDL >= 2.0.10. Use SDL_HINT_MOUSE_TOUCH_EVENTS and SDL_HINT_TOUCH_MOUSE_EVENTS instead.'; {/** * \brief Disable giving back control to the browser automatically @@ -1739,6 +2229,30 @@ SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT = 'SDL_EMSCRIPTEN_KEYBOARD_ELEMENT'; */} SDL_HINT_NO_SIGNAL_HANDLERS = 'SDL_NO_SIGNAL_HANDLERS'; +{** + * \brief A variable that decides whether to send SDL_QUIT when closing the final window. + * + * By default, SDL sends an SDL_QUIT event when there is only one window + * and it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most + * apps would also take the loss of this window as a signal to terminate the + * program. + * + * However, it's not unreasonable in some cases to have the program continue + * to live on, perhaps to create new windows later. + * + * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event + * when the final window is requesting to close. Note that in this case, + * there are still other legitimate reasons one might get an SDL_QUIT + * event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) + * on Unix, etc. + * + * The default value is "1". This hint can be changed at any time. + * + * This hint is available since SDL 2.0.22. Before then, you always get + * an SDL_QUIT event when closing the final window. + *} +SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE = 'SDL_QUIT_ON_LAST_WINDOW_CLOSE'; + {/** * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows. * @@ -1798,10 +2312,93 @@ SDL_HINT_RETURN_KEY_HIDES_IME = 'SDL_RETURN_KEY_HIDES_IME'; */} SDL_HINT_RPI_VIDEO_LAYER = 'SDL_RPI_VIDEO_LAYER'; +{** + * \brief A variable that decides what audio backend to use. + * + * By default, SDL will try all available audio backends in a reasonable + * order until it finds one that can work, but this hint allows the app + * or user to force a specific target, such as "alsa" if, say, you are + * on PulseAudio but want to try talking to the lower level instead. + * + * This functionality has existed since SDL 2.0.0 (indeed, before that) + * but before 2.0.22 this was an environment variable only. In 2.0.22, + * it was upgraded to a full SDL hint, so you can set the environment + * variable as usual or programatically set the hint with SDL_SetHint, + * which won't propagate to child processes. + * + * The default value is unset, in which case SDL will try to figure out + * the best audio backend on your behalf. This hint needs to be set + * before SDL_Init() is called to be useful. + * + * This hint is available since SDL 2.0.22. Before then, you could set + * the environment variable to get the same effect. + *} +SDL_HINT_AUDIODRIVER = 'SDL_AUDIODRIVER'; + +{** + * \brief A variable that decides what video backend to use. + * + * By default, SDL will try all available video backends in a reasonable + * order until it finds one that can work, but this hint allows the app + * or user to force a specific target, such as "x11" if, say, you are + * on Wayland but want to try talking to the X server instead. + * + * This functionality has existed since SDL 2.0.0 (indeed, before that) + * but before 2.0.22 this was an environment variable only. In 2.0.22, + * it was upgraded to a full SDL hint, so you can set the environment + * variable as usual or programatically set the hint with SDL_SetHint, + * which won't propagate to child processes. + * + * The default value is unset, in which case SDL will try to figure out + * the best video backend on your behalf. This hint needs to be set + * before SDL_Init() is called to be useful. + * + * This hint is available since SDL 2.0.22. Before then, you could set + * the environment variable to get the same effect. + *} +SDL_HINT_VIDEODRIVER = 'SDL_VIDEODRIVER'; + +{** + * \brief A variable that decides what KMSDRM device to use. + * + * Internally, SDL might open something like "/dev/dri/cardNN" to + * access KMSDRM functionality, where "NN" is a device index number. + * + * SDL makes a guess at the best index to use (usually zero), but the + * app or user can set this hint to a number between 0 and 99 to + * force selection. + * + * This hint is available since SDL 2.24.0. + *} +SDL_HINT_KMSDRM_DEVICE_INDEX = 'SDL_KMSDRM_DEVICE_INDEX'; + +{** + * \brief A variable that treats trackpads as touch devices. + * + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users + * expect from this device; however, these are often actually full + * multitouch-capable touch devices, so it might be preferable to some apps + * to treat them as such. + * + * Setting this hint to true will make the trackpad input report as a + * multitouch device instead of a mouse. The default is false. + * + * Note that most platforms don't support this hint. As of 2.24.0, it + * only supports MacBooks' trackpads on macOS. Others may follow later. + * + * This hint is checked during SDL_Init and can not be changed after. + * + * This hint is available since SDL 2.24.0. + *} +SDL_HINT_TRACKPAD_IS_TOUCH_ONLY = 'SDL_TRACKPAD_IS_TOUCH_ONLY'; + {/** * \brief An enumeration of hint priorities */} type + PPSDL_HintPriority = ^PSDL_HintPriority; + PSDL_HintPriority = ^TSDL_HintPriority; TSDL_HintPriority = type Integer; const @@ -1818,7 +2415,7 @@ const * * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise */} -function SDL_SetHintWithPriority(const name: PAnsiChar; const value: PAnsiChar; priority: TSDL_HintPriority) : boolean; cdecl; +function SDL_SetHintWithPriority(const name: PAnsiChar; const value: PAnsiChar; priority: TSDL_HintPriority): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHintWithPriority' {$ENDIF} {$ENDIF}; {/** @@ -1826,9 +2423,40 @@ function SDL_SetHintWithPriority(const name: PAnsiChar; const value: PAnsiChar; * * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise */} -function SDL_SetHint(const name: PAnsiChar; const value: PAnsiChar): boolean; cdecl; +function SDL_SetHint(const name: PAnsiChar; const value: PAnsiChar): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHint' {$ENDIF} {$ENDIF}; +{** + * Reset a hint to the default value. + * + * This will reset a hint to the value of the environment variable, + * or NIL if the environment isn't set. Callbacks will be called normally + * with this change. + * + * \param name the hint to set + * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.24.0. + *} +function SDL_ResetHint(const name: PAnsiChar): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResetHint' {$ENDIF} {$ENDIF}; + +{** + * Reset all hints to the default values. + * + * This will reset all hints to the value of the associated environment + * variable, or NIL if the environment isn't set. Callbacks will be called + * normally with this change. + * + * \since This function is available since SDL 2.26.0. + * + * \sa SDL_GetHint + * \sa SDL_SetHint + * \sa SDL_ResetHint + *} +procedure SDL_ResetHints(); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResetHints' {$ENDIF} {$ENDIF}; + {/** * \brief Get a hint * @@ -1842,7 +2470,7 @@ function SDL_GetHint(const name: PAnsiChar): PAnsiChar; cdecl; * * \return The boolean value of a hint variable. */} -function SDL_GetHintBoolean(const name: PAnsiChar; default_value: boolean): boolean; cdecl; +function SDL_GetHintBoolean(const name: PAnsiChar; default_value: TSDL_Bool): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHintBoolean' {$ENDIF} {$ENDIF}; {/** @@ -1853,7 +2481,9 @@ function SDL_GetHintBoolean(const name: PAnsiChar; default_value: boolean): bool * \param userdata A pointer to pass to the callback function */} type - TSDL_HintCallback = procedure(userdata: Pointer; const name: PAnsiChar; const oldValue: PAnsiChar; const newValue: PAnsiChar); + PPSDL_HintCallback = ^PSDL_HintCallback; + PSDL_HintCallback = ^TSDL_HintCallback; + TSDL_HintCallback = procedure(userdata: Pointer; const name: PAnsiChar; const oldValue: PAnsiChar; const newValue: PAnsiChar); cdecl; procedure SDL_AddHintCallback(const name: PAnsiChar; callback: TSDL_HintCallback; userdata: Pointer); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddHintCallback' {$ENDIF} {$ENDIF}; @@ -1868,10 +2498,19 @@ procedure SDL_AddHintCallback(const name: PAnsiChar; callback: TSDL_HintCallback procedure SDL_DelHintCallback(const name: PAnsiChar; callback: TSDL_HintCallback; userdata: Pointer); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DelHintCallback' {$ENDIF} {$ENDIF}; -{/** - * \brief Clear all hints +{** + * Clear all hints. * - * This function is called during SDL_Quit() to free stored hints. - */} + * This function is automatically called during SDL_Quit(), and deletes all + * callbacks without calling them and frees all memory associated with hints. + * If you're calling this from application code you probably want to call + * SDL_ResetHints() instead. + * + * This function will be removed from the API the next time we rev the ABI. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_ResetHints + *} procedure SDL_ClearHints(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ClearHints' {$ENDIF} {$ENDIF}; diff --git a/units/sdljoystick.inc b/units/sdljoystick.inc index 386e21a4..c507b078 100644 --- a/units/sdljoystick.inc +++ b/units/sdljoystick.inc @@ -1,5 +1,3 @@ -// based on sdl_joystick.h (2.0.14) - {** * \file SDL_joystick.h * @@ -31,13 +29,13 @@ type {* The joystick structure used to identify an SDL joystick *} - TSDL_Joystick = record end; - PSDL_Joystick = ^TSDL_Joystick; + PPSDL_Joystick = ^PSDL_Joystick; + PSDL_Joystick = type Pointer; {* A structure that encodes the stable unique id for a joystick device *} - TSDL_JoystickGUID = record - data: array[0..15] of cuint8; - end; + PPSDL_JoystickGUID = ^PSDL_JoystickGUID; + PSDL_JoystickGUID = ^TSDL_JoystickGUID; + TSDL_JoystickGUID = type TSDL_GUID; {** * This is a unique ID for a joystick for the time it is connected to the system, @@ -46,10 +44,14 @@ type * * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. *} - TSDL_JoystickID = cint32; + PPSDL_JoystickID = ^PSDL_JoystickID; + PSDL_JoystickID = ^TSDL_JoystickID; + TSDL_JoystickID = type cint32; type - TSDL_JoystickType = type cint32; + PPSDL_JoystickType = ^PSDL_JoystickType; + PSDL_JoystickType = ^TSDL_JoystickType; + TSDL_JoystickType = type Integer; const SDL_JOYSTICK_TYPE_UNKNOWN = TSDL_JoystickType(0); @@ -64,7 +66,9 @@ const SDL_JOYSTICK_TYPE_THROTTLE = TSDL_JoystickType(9); type - TSDL_JoystickPowerLevel = type cint32; + PPSDL_JoystickPowerLevel = ^PSDL_JoystickPowerLevel; + PSDL_JoystickPowerLevel = ^TSDL_JoystickPowerLevel; + TSDL_JoystickPowerLevel = type Integer; const SDL_JOYSTICK_POWER_UNKNOWN = TSDL_JoystickPowerLevel(-1); @@ -92,276 +96,718 @@ const * In particular, you are guaranteed that the joystick list won't change, so * the API functions that take a joystick index will be valid, and joystick * and game controller events will not be delivered. + * + * As of SDL 2.26.0, you can take the joystick lock around reinitializing the + * joystick subsystem, to prevent other threads from seeing joysticks in an + * uninitialized state. However, all open joysticks will be closed and SDL + * functions called with them will fail. + * + * \since This function is available since SDL 2.0.7. *} procedure SDL_LockJoysticks(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockJoysticks' {$ENDIF} {$ENDIF}; +{** + * Unlocking for multi-threaded access to the joystick API + * + * If you are using the joystick API or handling events from multiple threads + * you should use these locking functions to protect access to the joysticks. + * + * In particular, you are guaranteed that the joystick list won't change, so + * the API functions that take a joystick index will be valid, and joystick + * and game controller events will not be delivered. + * + * \since This function is available since SDL 2.0.7. + *} procedure SDL_UnlockJoysticks(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockJoysticks' {$ENDIF} {$ENDIF}; {** - * Count the number of joysticks attached to the system right now + * Count the number of joysticks attached to the system. + * + * \returns the number of attached joysticks on success or a negative error + * code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickName + * \sa SDL_JoystickPath + * \sa SDL_JoystickOpen *} -function SDL_NumJoysticks(): cint32; cdecl; +function SDL_NumJoysticks(): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_NumJoysticks' {$ENDIF} {$ENDIF}; {** - * Get the implementation dependent name of a joystick. - * This can be called before any joysticks are opened. - * If no name can be found, this function returns NULL. + * Get the implementation dependent name of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system) + * \returns the name of the selected joystick. If no name can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickName + * \sa SDL_JoystickOpen *} -function SDL_JoystickNameForIndex(device_index: cint32): PAnsiChar; cdecl; +function SDL_JoystickNameForIndex(device_index: cint): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNameForIndex' {$ENDIF} {$ENDIF}; {** - * Get the player index of a joystick, or -1 if it's not available - * This can be called before any joysticks are opened. + * Get the implementation dependent path of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system) + * \returns the path of the selected joystick. If no path can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_JoystickPath + * \sa SDL_JoystickOpen *} -function SDL_JoystickGetDevicePlayerIndex(device_index: cint32): cint32; cdecl; +function SDL_JoystickPathForIndex(device_index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickPathForIndex' {$ENDIF} {$ENDIF}; + +{** + * Get the player index of a joystick, or -1 if it's not available This can be + * called before any joysticks are opened. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_JoystickGetDevicePlayerIndex(device_index: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDevicePlayerIndex' {$ENDIF} {$ENDIF}; {** * Return the GUID for the joystick at this index * This can be called before any joysticks are opened. *} -function SDL_JoystickGetDeviceGUID(device_index: cint32): TSDL_JoystickGUID; cdecl; +function SDL_JoystickGetDeviceGUID(device_index: cint): TSDL_JoystickGUID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceGUID' {$ENDIF} {$ENDIF}; {** - * Get the USB vendor ID of a joystick, if available. - * This can be called before any joysticks are opened. - * If the vendor ID isn't available this function returns 0. + * Get the USB vendor ID of a joystick, if available. + * + * This can be called before any joysticks are opened. If the vendor ID isn't + * available this function returns 0. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system + * \returns the USB vendor ID of the selected joystick. If called on an + * invalid index, this function returns zero + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetDeviceVendor(device_index: cint32): cuint16; cdecl; +function SDL_JoystickGetDeviceVendor(device_index: cint): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceVendor' {$ENDIF} {$ENDIF}; {** - * Get the USB product ID of a joystick, if available. - * This can be called before any joysticks are opened. - * If the product ID isn't available this function returns 0. + * Get the USB product ID of a joystick, if available. + * + * This can be called before any joysticks are opened. If the product ID isn't + * available this function returns 0. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system + * \returns the USB product ID of the selected joystick. If called on an + * invalid index, this function returns zero + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetDeviceProduct(device_index: cint32): cuint16; cdecl; +function SDL_JoystickGetDeviceProduct(device_index: cint): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceProduct' {$ENDIF} {$ENDIF}; {** - * Get the product version of a joystick, if available. - * This can be called before any joysticks are opened. - * If the product version isn't available this function returns 0. + * Get the product version of a joystick, if available. + * + * This can be called before any joysticks are opened. If the product version + * isn't available this function returns 0. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system + * \returns the product version of the selected joystick. If called on an + * invalid index, this function returns zero + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetDeviceProductVersion(device_index: cint32): cuint16; cdecl; +function SDL_JoystickGetDeviceProductVersion(device_index: cint): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceProductVersion' {$ENDIF} {$ENDIF}; {** - * Get the type of a joystick, if available. - * This can be called before any joysticks are opened. + * Get the type of a joystick, if available. + * + * This can be called before any joysticks are opened. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system + * \returns the SDL_JoystickType of the selected joystick. If called on an + * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN` + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetDeviceType(device_index: cint32): TSDL_JoystickType; cdecl; +function SDL_JoystickGetDeviceType(device_index: cint): TSDL_JoystickType; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceType' {$ENDIF} {$ENDIF}; {** - * Get the instance ID of a joystick. - * This can be called before any joysticks are opened. - * If the index is out of range, this function will return -1. + * Get the instance ID of a joystick. + * + * This can be called before any joysticks are opened. If the index is out of + * range, this function will return -1. + * + * \param device_index the index of the joystick to query (the N'th joystick + * on the system + * \returns the instance id of the selected joystick. If called on an invalid + * index, this function returns zero + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetDeviceInstanceID(device_index: cint32): TSDL_JoystickID; cdecl; +function SDL_JoystickGetDeviceInstanceID(device_index: cint): TSDL_JoystickID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetDeviceInstanceID' {$ENDIF} {$ENDIF}; {** - * Open a joystick for use. - * The index passed as an argument refers to the N'th joystick on the system. - * This index is not the value which will identify this joystick in future - * joystick events. The joystick's instance id (::SDL_JoystickID) will be used - * there instead. + * Open a joystick for use. + * + * The `device_index` argument refers to the N'th joystick presently + * recognized by SDL on the system. It is **NOT** the same as the instance ID + * used to identify the joystick in future events. See + * SDL_JoystickInstanceID() for more details about instance IDs. + * + * The joystick subsystem must be initialized before a joystick can be opened + * for use. * - * \return A joystick identifier, or NULL if an error occurred. + * \param device_index the index of the joystick to query + * \returns a joystick identifier or NULL if an error occurred; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickClose + * \sa SDL_JoystickInstanceID *} -function SDL_JoystickOpen(device_index: cint32): PSDL_Joystick; cdecl; +function SDL_JoystickOpen(device_index: cint): PSDL_Joystick; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickOpen' {$ENDIF} {$ENDIF}; {** - * Return the SDL_Joystick associated with an instance id. + * Get the SDL_Joystick associated with an instance id. + * + * \param instance_id the instance id to get the SDL_Joystick for + * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.4. *} function SDL_JoystickFromInstanceID(instance_id: TSDL_JoystickID): PSDL_Joystick; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickFromInstanceID' {$ENDIF} {$ENDIF}; {** - * Return the SDL_Joystick associated with a player index. + * Get the SDL_Joystick associated with a player index. + * + * \param player_index the player index to get the SDL_Joystick for + * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.12. *} -function SDL_JoystickFromPlayerIndex(player_index: cint32): PSDL_Joystick; cdecl; +function SDL_JoystickFromPlayerIndex(player_index: cint): PSDL_Joystick; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickFromPlayerIndex' {$ENDIF} {$ENDIF}; {** - * Attaches a new virtual joystick. - * Returns the joystick's device index, or -1 if an error occurred. + * Attach a new virtual joystick. + * + * \returns the joystick's device index, or -1 if an error occurred. + * + * \since This function is available since SDL 2.0.14. *} -function SDL_JoystickAttachVirtual(type_: TSDL_JoystickType; naxes: cint32; nbuttons: cint32; nhats: cint32): PSDL_Joystick; cdecl; +function SDL_JoystickAttachVirtual(type_: TSDL_JoystickType; naxes: cint; nbuttons: cint; nhats: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickAttachVirtual' {$ENDIF} {$ENDIF}; +type + {** + * The structure that defines an extended virtual joystick description + * + * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_JoystickAttachVirtualEx() + * All other elements of this structure are optional and can be left 0. + * + * \sa SDL_JoystickAttachVirtualEx + *} + TUpdateProc = procedure(userdata: Pointer); cdecl; + TSetPlayerIndexProc = procedure(userdata: Pointer; player_index: cint); cdecl; + TRumbleFunc = function(userdata: Pointer; low_frequency_rumble: cuint16; high_frequency_rumble: cuint16): cint; cdecl; + TRumbleTriggersFunc = function(userdata: Pointer; left_rumble: cuint16; right_rumble: cuint16): cint; cdecl; + TSetLEDFunc = function(userdata: Pointer; red: cuint8; green: cuint8; blue: cuint8): cint; cdecl; + TSendEffectFunc = function(userdata: Pointer; const data: Pointer; size: cint): cint; cdecl; + + PPSDL_VirtualJoystickDesc = ^PSDL_VirtualJoystickDesc; + PSDL_VirtualJoystickDesc = ^TSDL_VirtualJoystickDesc; + TSDL_VirtualJoystickDesc = record + version: cuint16; {**< `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` *} + type_: cuint16; {**< `SDL_JoystickType` } + naxes: cuint16; {**< the number of axes on this joystick *} + nbuttons: cuint16; {**< the number of buttons on this joystick *} + nhats: cuint16; {**< the number of hats on this joystick *} + vendor_id: cuint16; {**< the USB vendor ID of this joystick *} + product_id: cuint16; {**< the USB product ID of this joystick *} + padding: cuint16; {**< unused *} + button_mask: cuint16; {**< A mask of which buttons are valid for this controller + e.g. (1 << SDL_CONTROLLER_BUTTON_A) *} + axis_mask: cuint32; {**< A mask of which axes are valid for this controller + e.g. (1 << SDL_CONTROLLER_AXIS_LEFTX) *} + name: PAnsiChar; {**< the name of the joystick *} + + userdata: Pointer; {**< User data pointer passed to callbacks *} + Update: TUpdateProc; {**< Called when the joystick state should be updated *} + SetPlayerIndex: TSetPlayerIndexProc; {**< Called when the player index is set *} + Rumble: TRumbleFunc; {**< Implements SDL_JoystickRumble() *} + RumbleTriggers: TRumbleTriggersFunc; {**< Implements SDL_JoystickRumbleTriggers() *} + SetLED: TSetLEDFunc; {**< Implements SDL_JoystickSetLED() *} + SendEffect: TSendEffectFunc; {**< Implements SDL_JoystickSendEffect() *} + end; + {** - * Detaches a virtual joystick - * Returns 0 on success, or -1 if an error occurred. + * \brief The current version of the SDL_VirtualJoystickDesc structure *} -function SDL_JoystickDetachVirtual(device_index: cint32): cint32; cdecl; +const + SDL_VIRTUAL_JOYSTICK_DESC_VERSION = 1; + +{/** + * Attach a new virtual joystick with extended properties. + * + * \returns the joystick's device index, or -1 if an error occurred. + * + * \since This function is available since SDL 2.24.0. + */} +function SDL_JoystickAttachVirtualEx(const desc: PSDL_VirtualJoystickDesc): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickAttachVirtualEx' {$ENDIF} {$ENDIF}; + +{** + * Detach a virtual joystick. + * + * \param device_index a value previously returned from + * SDL_JoystickAttachVirtual() + * \returns 0 on success, or -1 if an error occurred. + * + * \since This function is available since SDL 2.0.14. + *} +function SDL_JoystickDetachVirtual(device_index: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickDetachVirtual' {$ENDIF} {$ENDIF}; {** - * Indicates whether or not a virtual-joystick is at a given device index. + * Query whether or not the joystick at a given device index is virtual. + * + * \param device_index a joystick device index. + * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.14. *} -function SDL_JoystickIsVirtual(device_index: cint32): TSDL_Bool; cdecl; +function SDL_JoystickIsVirtual(device_index: cint): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickIsVirtual' {$ENDIF} {$ENDIF}; {** - * Set values on an opened, virtual-joystick's controls. - * Please note that values set here will not be applied until the next - * call to SDL_JoystickUpdate, which can either be called directly, - * or can be called indirectly through various other SDL APIS, - * including, but not limited to the following: SDL_PollEvent, - * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent. + * Set values on an opened, virtual-joystick's axis. * - * Returns 0 on success, -1 on error. + * Please note that values set here will not be applied until the next call to + * SDL_JoystickUpdate, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * Note that when sending trigger axes, you should scale the value to the full + * range of Sint16. For example, a trigger at rest would have the value of + * `SDL_JOYSTICK_AXIS_MIN`. + * + * \param joystick the virtual joystick on which to set state. + * \param axis the specific axis on the virtual joystick to set. + * \param value the new value for the specified axis. + * \returns 0 on success, -1 on error. + * + * \since This function is available since SDL 2.0.14. *} -function SDL_JoystickSetVirtualAxis(joystick: PSDL_Joystick; axis: cint32; value: cint16): cint32; cdecl; +function SDL_JoystickSetVirtualAxis(joystick: PSDL_Joystick; axis: cint; value: cint16): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSetVirtualAxis' {$ENDIF} {$ENDIF}; -function SDL_JoystickSetVirtualButton(joystick: PSDL_Joystick; button: cint32; value: cuint8): cint32; cdecl; +{** + * Set values on an opened, virtual-joystick's button. + * + * Please note that values set here will not be applied until the next call to + * SDL_JoystickUpdate, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param button the specific button on the virtual joystick to set. + * \param value the new value for the specified button. + * \returns 0 on success, -1 on error. + * + * \since This function is available since SDL 2.0.14. + *} +function SDL_JoystickSetVirtualButton(joystick: PSDL_Joystick; button: cint; value: cuint8): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSetVirtualButton' {$ENDIF} {$ENDIF}; -function SDL_JoystickSetVirtualHat(joystick: PSDL_Joystick; hat: cint32; value: cuint8): cint32; cdecl; +{** + * Set values on an opened, virtual-joystick's hat. + * + * Please note that values set here will not be applied until the next call to + * SDL_JoystickUpdate, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param hat the specific hat on the virtual joystick to set. + * \param value the new value for the specified hat. + * \returns 0 on success, -1 on error. + * + * \since This function is available since SDL 2.0.14. + *} +function SDL_JoystickSetVirtualHat(joystick: PSDL_Joystick; hat: cint; value: cuint8): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSetVirtualHat' {$ENDIF} {$ENDIF}; {** - * Return the name for this currently opened joystick. - * If no name can be found, this function returns NULL. + * Get the implementation dependent name of a joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the name of the selected joystick. If no name can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickNameForIndex + * \sa SDL_JoystickOpen *} function SDL_JoystickName(joystick: PSDL_Joystick): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickName' {$ENDIF} {$ENDIF}; {** - * Get the player index of an opened joystick, or -1 if it's not available + * Get the implementation dependent path of a joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the path of the selected joystick. If no path can be found, this + * function returns NULL; call SDL_GetError() for more information. * - * For XInput controllers this returns the XInput user index. + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_JoystickPathForIndex *} -function SDL_JoystickGetPlayerIndex(joystick: PSDL_Joystick): cint32; cdecl; +function SDL_JoystickPath(joystick: PSDL_Joystick): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickPath' {$ENDIF} {$ENDIF}; + +{** + * Get the player index of an opened joystick. + * + * For XInput controllers this returns the XInput user index. Many joysticks + * will not be able to supply this information. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the player index, or -1 if it's not available. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_JoystickGetPlayerIndex(joystick: PSDL_Joystick): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetPlayerIndex' {$ENDIF} {$ENDIF}; {** - * Set the player index of an opened joystick + * Set the player index of an opened joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param player_index Player index to assign to this joystick, or -1 to clear + * the player index and turn off player LEDs. + * + * \since This function is available since SDL 2.0.12. *} -procedure SDL_JoystickSetPlayerIndex(joystick: PSDL_Joystick; player_index: cint32); cdecl; +procedure SDL_JoystickSetPlayerIndex(joystick: PSDL_Joystick; player_index: cint); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSetPlayerIndex' {$ENDIF} {$ENDIF}; {** - * Return the GUID for this opened joystick + * Get the implementation-dependent GUID for the joystick. + * + * This function requires an open joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the GUID of the given joystick. If called on an invalid index, + * this function returns a zero GUID; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetDeviceGUID + * \sa SDL_JoystickGetGUIDString *} function SDL_JoystickGetGUID(joystick: PSDL_Joystick): TSDL_JoystickGUID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetGUID' {$ENDIF} {$ENDIF}; {** - * Get the USB vendor ID of an opened joystick, if available. - * If the vendor ID isn't available this function returns 0. + * Get the USB vendor ID of an opened joystick, if available. + * + * If the vendor ID isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 2.0.6. *} function SDL_JoystickGetVendor(joystick: PSDL_Joystick): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetVendor' {$ENDIF} {$ENDIF}; {** - * Get the USB product ID of an opened joystick, if available. - * If the product ID isn't available this function returns 0. + * Get the USB product ID of an opened joystick, if available. + * + * If the product ID isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the USB product ID of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 2.0.6. *} function SDL_JoystickGetProduct(joystick: PSDL_Joystick): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetProduct' {$ENDIF} {$ENDIF}; {** - * Get the product version of an opened joystick, if available. - * If the product version isn't available this function returns 0. + * Get the product version of an opened joystick, if available. + * + * If the product version isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the product version of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 2.0.6. *} function SDL_JoystickGetProductVersion(joystick: PSDL_Joystick): cuint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetProductVersion' {$ENDIF} {$ENDIF}; {** - * Get the serial number of an opened joystick, if available. + * Get the firmware version of an opened joystick, if available. + * + * If the firmware version isn't available this function returns 0. * - * Returns the serial number of the joystick, or NULL if it is not available. + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the firmware version of the selected joystick, or 0 if + * unavailable. + * + * \since This function is available since SDL 2.24.0. + *} +function SDL_JoystickGetFirmwareVersion(joystick: PSDL_Joystick): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetFirmwareVersion' {$ENDIF} {$ENDIF}; + +{** + * Get the serial number of an opened joystick, if available. + * + * Returns the serial number of the joystick, or NULL if it is not available. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the serial number of the selected joystick, or NULL if + * unavailable. + * + * \since This function is available since SDL 2.0.14. *} function SDL_JoystickGetSerial(joystick: PSDL_Joystick): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetSerial' {$ENDIF} {$ENDIF}; {** - * Get the type of an opened joystick. + * Get the type of an opened joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \returns the SDL_JoystickType of the selected joystick. + * + * \since This function is available since SDL 2.0.6. *} function SDL_JoystickGetType(joystick: PSDL_Joystick): TSDL_JoystickType; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetType' {$ENDIF} {$ENDIF}; {** - * Return a string representation for this guid. pszGUID must point to at least 33 bytes - * (32 for the string plus a NULL terminator). + * Get an ASCII string representation for a given SDL_JoystickGUID. + * + * You should supply at least 33 bytes for pszGUID. + * + * \param guid the SDL_JoystickGUID you wish to convert to string + * \param pszGUID buffer in which to write the ASCII string + * \param cbGUID the size of pszGUID + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetDeviceGUID + * \sa SDL_JoystickGetGUID + * \sa SDL_JoystickGetGUIDFromString *} -procedure SDL_JoystickGetGUIDString(guid: TSDL_JoystickGUID; pszGUID: PAnsiChar; cbGUID: cint32); cdecl; +procedure SDL_JoystickGetGUIDString(guid: TSDL_JoystickGUID; pszGUID: PAnsiChar; cbGUID: cint); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetGUIDString' {$ENDIF} {$ENDIF}; {** - * convert a string into a joystick guid + * Convert a GUID string into a SDL_JoystickGUID structure. + * + * Performs no error checking. If this function is given a string containing + * an invalid GUID, the function will silently succeed, but the GUID generated + * will not be useful. + * + * \param pchGUID string containing an ASCII representation of a GUID + * \returns a SDL_JoystickGUID structure. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetGUIDString *} function SDL_JoystickGetGUIDFromString(const pchGUID: PAnsiChar): TSDL_JoystickGUID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetGUIDFromString' {$ENDIF} {$ENDIF}; {** - * Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not. + * Get the device information encoded in a SDL_JoystickGUID structure + * + * \param guid the SDL_JoystickGUID you wish to get info about + * \param vendor A pointer filled in with the device VID, or 0 if not + * available + * \param product A pointer filled in with the device PID, or 0 if not + * available + * \param version A pointer filled in with the device version, or 0 if not + * available + * \param crc16 A pointer filled in with a CRC used to distinguish different + * products with the same VID/PID, or 0 if not available + * + * \since This function is available since SDL 2.26.0. + * + * \sa SDL_JoystickGetDeviceGUID + *} +procedure SDL_GetJoystickGUIDInfo(guid: TSDL_JoystickGUID; vendor: pcuint16; product: pcuint16; version: pcuint16; crc16: pcuint16); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetJoystickGUIDInfo' {$ENDIF} {$ENDIF}; + +{** + * Get the status of a specified joystick. + * + * \param joystick the joystick to query + * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickClose + * \sa SDL_JoystickOpen *} function SDL_JoystickGetAttached(joystick: PSDL_Joystick): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetAttached' {$ENDIF} {$ENDIF}; {** - * Get the instance ID of an opened joystick or -1 if the joystick is invalid. + * Get the instance ID of an opened joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \returns the instance ID of the specified joystick on success or a negative + * error code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickOpen *} function SDL_JoystickInstanceID(joystick: PSDL_Joystick): TSDL_JoystickID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickInstanceID' {$ENDIF} {$ENDIF}; {** - * Get the number of general axis controls on a joystick. + * Get the number of general axis controls on a joystick. + * + * Often, the directional pad on a game controller will either look like 4 + * separate buttons or a POV hat, and not axes, but all of this is up to the + * device and platform. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \returns the number of axis controls/number of axes on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetAxis + * \sa SDL_JoystickOpen *} -function SDL_JoystickNumAxes(joystick: PSDL_Joystick): cint32; cdecl; +function SDL_JoystickNumAxes(joystick: PSDL_Joystick): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNumAxes' {$ENDIF} {$ENDIF}; {** - * Get the number of trackballs on a joystick. + * Get the number of trackballs on a joystick. * - * Joystick trackballs have only relative motion events associated - * with them and their state cannot be polled. + * Joystick trackballs have only relative motion events associated with them + * and their state cannot be polled. + * + * Most joysticks do not have trackballs. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \returns the number of trackballs on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetBall *} -function SDL_JoystickNumBalls(joystick: PSDL_Joystick): cint32; cdecl; +function SDL_JoystickNumBalls(joystick: PSDL_Joystick): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNumBalls' {$ENDIF} {$ENDIF}; {** - * Get the number of POV hats on a joystick. + * Get the number of POV hats on a joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \returns the number of POV hats on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetHat + * \sa SDL_JoystickOpen *} -function SDL_JoystickNumHats(joystick: PSDL_Joystick): cint32; cdecl; +function SDL_JoystickNumHats(joystick: PSDL_Joystick): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNumHats' {$ENDIF} {$ENDIF}; {** - * Get the number of buttons on a joystick. + * Get the number of buttons on a joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \returns the number of buttons on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickGetButton + * \sa SDL_JoystickOpen *} -function SDL_JoystickNumButtons(joystick: PSDL_Joystick): cint32; cdecl; +function SDL_JoystickNumButtons(joystick: PSDL_Joystick): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickNumButtons' {$ENDIF} {$ENDIF}; {** - * Update the current state of the open joysticks. + * Update the current state of the open joysticks. * - * This is called automatically by the event loop if any joystick - * events are enabled. + * This is called automatically by the event loop if any joystick events are + * enabled. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickEventState *} procedure SDL_JoystickUpdate(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickUpdate' {$ENDIF} {$ENDIF}; {** - * Enable/disable joystick event polling. + * Enable/disable joystick event polling. + * + * If joystick events are disabled, you must call SDL_JoystickUpdate() + * yourself and manually check the state of the joystick when you want + * joystick information. * - * If joystick events are disabled, you must call SDL_JoystickUpdate() - * yourself and check the state of the joystick when you want joystick - * information. + * It is recommended that you leave joystick event handling enabled. * - * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE. + * **WARNING**: Calling this function may delete all events currently in SDL's + * event queue. + * + * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE` + * \returns 1 if enabled, 0 if disabled, or a negative error code on failure; + * call SDL_GetError() for more information. + * + * If `state` is `SDL_QUERY` then the current state is returned, + * otherwise the new processing state is returned. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GameControllerEventState *} -function SDL_JoystickEventState(state: cint32): cint32; cdecl; +function SDL_JoystickEventState(state: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickEventState' {$ENDIF} {$ENDIF}; const @@ -369,25 +815,45 @@ const SDL_JOYSTICK_AXIS_MIN = -32768; {** - * Get the current state of an axis control on a joystick. + * Get the current state of an axis control on a joystick. + * + * SDL makes no promises about what part of the joystick any given axis refers + * to. Your game should have some sort of configuration UI to let users + * specify what each axis should be bound to. Alternately, SDL's higher-level + * Game Controller API makes a great effort to apply order to this lower-level + * interface, so you know that a specific axis is the "left thumb stick," etc. + * + * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to + * 32767) representing the current position of the axis. It may be necessary + * to impose certain tolerances on these values to account for jitter. + * + * \param joystick an SDL_Joystick structure containing joystick information + * \param axis the axis to query; the axis indices start at index 0 + * \returns a 16-bit signed integer representing the current position of the + * axis or 0 on failure; call SDL_GetError() for more information. * - * The state is a value ranging from -32768 to 32767. + * \since This function is available since SDL 2.0.0. * - * The axis indices start at index 0. + * \sa SDL_JoystickNumAxes *} -function SDL_JoystickGetAxis(joystick: PSDL_Joystick; axis: cint32): cint16; cdecl; +function SDL_JoystickGetAxis(joystick: PSDL_Joystick; axis: cint): cint16; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetAxis' {$ENDIF} {$ENDIF}; {** - * Get the initial state of an axis control on a joystick. + * Get the initial state of an axis control on a joystick. * - * The state is a value ranging from -32768 to 32767. + * The state is a value ranging from -32768 to 32767. * - * The axis indices start at index 0. + * The axis indices start at index 0. * - * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \param joystick an SDL_Joystick structure containing joystick information + * \param axis the axis to query; the axis indices start at index 0 + * \param state Upon return, the initial value is supplied here. + * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * + * \since This function is available since SDL 2.0.6. *} -function SDL_JoystickGetAxisInitialState(joystick: PSDL_Joystick; axis: cint32; state: pcint16): TSDL_Bool; cdecl; +function SDL_JoystickGetAxisInitialState(joystick: PSDL_Joystick; axis: cint; state: pcint16): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetAxisInitialState' {$ENDIF} {$ENDIF}; {** @@ -405,101 +871,206 @@ const SDL_HAT_LEFTDOWN = SDL_HAT_LEFT or SDL_HAT_DOWN; {** - * Get the current state of a POV hat on a joystick. + * Get the current state of a POV hat on a joystick. + * + * The returned value will be one of the following positions: + * + * - `SDL_HAT_CENTERED` + * - `SDL_HAT_UP` + * - `SDL_HAT_RIGHT` + * - `SDL_HAT_DOWN` + * - `SDL_HAT_LEFT` + * - `SDL_HAT_RIGHTUP` + * - `SDL_HAT_RIGHTDOWN` + * - `SDL_HAT_LEFTUP` + * - `SDL_HAT_LEFTDOWN` + * + * \param joystick an SDL_Joystick structure containing joystick information + * \param hat the hat index to get the state from; indices start at index 0 + * \returns the current hat position. * - * The hat indices start at index 0. + * \since This function is available since SDL 2.0.0. * - * The return value is one of the following positions: - * - SDL_HAT_CENTERED - * - SDL_HAT_UP - * - SDL_HAT_RIGHT - * - SDL_HAT_DOWN - * - SDL_HAT_LEFT - * - SDL_HAT_RIGHTUP - * - SDL_HAT_RIGHTDOWN - * - SDL_HAT_LEFTUP - * - SDL_HAT_LEFTDOWN + * \sa SDL_JoystickNumHats *} -function SDL_JoystickGetHat(joystick: PSDL_Joystick; hat: cint32): cuint8; cdecl; +function SDL_JoystickGetHat(joystick: PSDL_Joystick; hat: cint): cuint8; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetHat' {$ENDIF} {$ENDIF}; {** - * Get the ball axis change since the last poll. + * Get the ball axis change since the last poll. + * + * Trackballs can only return relative motion since the last call to + * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`. + * + * Most joysticks do not have trackballs. + * + * \param joystick the SDL_Joystick to query + * \param ball the ball index to query; ball indices start at index 0 + * \param dx stores the difference in the x axis position since the last poll + * \param dy stores the difference in the y axis position since the last poll + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * 0, or -1 if you passed it invalid parameters. + * \since This function is available since SDL 2.0.0. * - * The ball indices start at index 0. + * \sa SDL_JoystickNumBalls *} -function SDL_JoystickGetBall(joystick: PSDL_Joystick; ball: cint32; dx: pcint32; dy: pcint32): cint32; cdecl; +function SDL_JoystickGetBall(joystick: PSDL_Joystick; ball: cint; dx: pcint; dy: pcint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetBall' {$ENDIF} {$ENDIF}; {** - * Get the current state of a button on a joystick. + * Get the current state of a button on a joystick. * - * The button indices start at index 0. + * \param joystick an SDL_Joystick structure containing joystick information + * \param button the button index to get the state from; indices start at + * index 0 + * \returns 1 if the specified button is pressed, 0 otherwise. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickNumButtons *} -function SDL_JoystickGetButton(joystick: PSDL_Joystick; button: cint32): cuint8; cdecl; +function SDL_JoystickGetButton(joystick: PSDL_Joystick; button: cint): cuint8; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickGetButton' {$ENDIF} {$ENDIF}; {** - * Start a rumble effect - * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling. + * Start a rumble effect. + * + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. * - * \param joystick The joystick to vibrate - * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF - * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF - * \param duration_ms The duration of the rumble effect, in milliseconds + * \param joystick The joystick to vibrate + * \param low_frequency_rumble The intensity of the low frequency (left) + * rumble motor, from 0 to 0xFFFF + * \param high_frequency_rumble The intensity of the high frequency (right) + * rumble motor, from 0 to 0xFFFF + * \param duration_ms The duration of the rumble effect, in milliseconds + * \returns 0, or -1 if rumble isn't supported on this joystick * - * \return 0, or -1 if rumble isn't supported on this joystick + * \since This function is available since SDL 2.0.9. + * + * \sa SDL_JoystickHasRumble *} -function SDL_JoystickRumble(joystick: PSDL_Joystick; low_frequency_rumble: cuint16; high_frequency_rumble: cuint16; duration_ms: cuint32): cint32; cdecl; +function SDL_JoystickRumble(joystick: PSDL_Joystick; low_frequency_rumble: cuint16; high_frequency_rumble: cuint16; duration_ms: cuint32): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickRumble' {$ENDIF} {$ENDIF}; {** - * Start a rumble effect in the joystick's triggers - * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling. + * Start a rumble effect in the joystick's triggers + * + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. + * + * Note that this is rumbling of the _triggers_ and not the game controller as + * a whole. This is currently only supported on Xbox One controllers. If you + * want the (more common) whole-controller rumble, use SDL_JoystickRumble() + * instead. * - * \param joystick The joystick to vibrate - * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF - * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF - * \param duration_ms The duration of the rumble effect, in milliseconds + * \param joystick The joystick to vibrate + * \param left_rumble The intensity of the left trigger rumble motor, from 0 + * to 0xFFFF + * \param right_rumble The intensity of the right trigger rumble motor, from 0 + * to 0xFFFF + * \param duration_ms The duration of the rumble effect, in milliseconds + * \returns 0, or -1 if trigger rumble isn't supported on this joystick * - * \return 0, or -1 if trigger rumble isn't supported on this joystick + * \since This function is available since SDL 2.0.14. + * + * \sa SDL_JoystickHasRumbleTriggers *} -function SDL_JoystickRumbleTriggerse(joystick: PSDL_Joystick; left_rumble: cuint16; right_rumble: cuint16; duration_ms: cuint32): cint32; cdecl; +function SDL_JoystickRumbleTriggers(joystick: PSDL_Joystick; left_rumble: cuint16; right_rumble: cuint16; duration_ms: cuint32): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickRumbleTriggers' {$ENDIF} {$ENDIF}; {** - * Return whether a joystick has an LED + * Query whether a joystick has an LED. + * + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. * - * \param joystick The joystick to query + * \param joystick The joystick to query + * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. * - * \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED + * \since This function is available since SDL 2.0.14. *} -function SDL_JoystickHasLED(joystick: PSDL_Joystick; button: cint32): TSDL_Bool; cdecl; +function SDL_JoystickHasLED(joystick: PSDL_Joystick): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickHasLED' {$ENDIF} {$ENDIF}; {** - * Update a joystick's LED color. + * Query whether a joystick has rumble support. + * + * \param joystick The joystick to query + * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.18. + * + * \sa SDL_JoystickRumble + *} +function SDL_JoystickHasRumble(joystick: PSDL_Joystick): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickHasRumble' {$ENDIF} {$ENDIF}; + +{** + * Query whether a joystick has rumble support on triggers. + * + * \param joystick The joystick to query + * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.18. + * + * \sa SDL_JoystickRumbleTriggers + *} +function SDL_JoystickHasRumbleTriggers(joystick: PSDL_Joystick): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickHasRumbleTriggers' {$ENDIF} {$ENDIF}; + + +{** + * Update a joystick's LED color. * - * \param joystick The joystick to update - * \param red The intensity of the red LED - * \param green The intensity of the green LED - * \param blue The intensity of the blue LED + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. * - * \return 0, or -1 if this joystick does not have a modifiable LED + * \param joystick The joystick to update + * \param red The intensity of the red LED + * \param green The intensity of the green LED + * \param blue The intensity of the blue LED + * \returns 0 on success, -1 if this joystick does not have a modifiable LED + * + * \since This function is available since SDL 2.0.14. *} -function SDL_JoystickSetLED(joystick: PSDL_Joystick; red: cuint8; green: cuint8; blue: cuint8): cint32; cdecl; +function SDL_JoystickSetLED(joystick: PSDL_Joystick; red: cuint8; green: cuint8; blue: cuint8): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSetLED' {$ENDIF} {$ENDIF}; {** - * Close a joystick previously opened with SDL_JoystickOpen(). + * Send a joystick specific effect packet + * + * \param joystick The joystick to affect + * \param data The data to send to the joystick + * \param size The size of the data to send to the joystick + * \returns 0, or -1 if this joystick or driver doesn't support effect packets + * + * \since This function is available since SDL 2.0.16. + *} +function SDL_JoystickSendEffect(joystick: PSDL_Joystick; const data: Pointer; size: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickSendEffect' {$ENDIF} {$ENDIF}; + +{** + * Close a joystick previously opened with SDL_JoystickOpen(). + * + * \param joystick The joystick device to close + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_JoystickOpen *} procedure SDL_JoystickClose(joystick: PSDL_Joystick); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickClose' {$ENDIF} {$ENDIF}; {** - * Return the battery level of this joystick + * Get the battery level of a joystick as SDL_JoystickPowerLevel. + * + * \param joystick the SDL_Joystick to query + * \returns the current battery level as SDL_JoystickPowerLevel on success or + * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown + * + * \since This function is available since SDL 2.0.4. *} function SDL_JoystickCurrentPowerLevel(joystick: PSDL_Joystick): TSDL_JoystickPowerLevel; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_JoystickCurrentPowerLevel' {$ENDIF} {$ENDIF}; diff --git a/units/sdlkeyboard.inc b/units/sdlkeyboard.inc index 6b05ef11..c126e8a9 100644 --- a/units/sdlkeyboard.inc +++ b/units/sdlkeyboard.inc @@ -1,177 +1,340 @@ //from "sdl_keyboard.h" +{* + * \file SDL_keyboard.h + * + * Include file for SDL keyboard event handling + } + type + { SDL2-for-Pascal: + - Is this type used/needed anywhere? + - It doesn't seem to be part of sdl_keyboard.h + - If not, should be commented out or deleted } + PPKeyStateArr = ^PKeyStateArr; PKeyStateArr = ^TKeyStateArr; TKeyStateArr = array[0..65000] of cuint8; - {** - * The SDL keysym structure, used in key events. - *} + {* + * \brief The SDL keysym structure, used in key events. + * + * \note If you are looking for translated character input, see the:: SDL_TEXTINPUT event. + } + PPSDL_Keysym = ^PSDL_Keysym; PSDL_Keysym = ^TSDL_Keysym; TSDL_Keysym = record - scancode: TSDL_ScanCode; // SDL physical key code - see SDL_Scancode for details - sym: TSDL_KeyCode; // SDL virtual key code - see SDL_Keycode for details - _mod: cuint16; // current key modifiers + scancode: TSDL_ScanCode; // SDL physical key code - see SDL_Scancode for details + sym: TSDL_KeyCode; // SDL virtual key code - see SDL_Keycode for details + mod_: cuint16; // current key modifiers unicode: cuint32; // (deprecated) use SDL_TextInputEvent instead end; - {** - * Get the window which currently has keyboard focus. - *} - - function SDL_GetKeyboardFocus: PSDL_Window cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyboardFocus' {$ENDIF}{$ENDIF}; - - {** - * Get a snapshot of the current state of the keyboard. - * - * numkeys if non-nil, receives the length of the returned array. - * - * An array of key states. Indexes into this array are obtained by using SDL_Scancode values. - * - *} - - function SDL_GetKeyboardState(numkeys: pcint): pcuint8 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyboardState' {$ENDIF}{$ENDIF}; - - {** - * Get the current key modifier state for the keyboard. - *} - - function SDL_GetModState: TSDL_KeyMod cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetModState' {$ENDIF}{$ENDIF}; - - {** - * Set the current key modifier state for the keyboard. - * - * This does not change the keyboard state, only the key modifier flags. - *} - - procedure SDL_SetModState(modstate: TSDL_KeyMod) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetModState' {$ENDIF}{$ENDIF}; - - {** - * Get the key code corresponding to the given scancode according - * to the current keyboard layout. - * - * See SDL_Keycode for details. - * - * SDL_GetKeyName() - *} - - function SDL_GetKeyFromScancode(scancode: TSDL_ScanCode): TSDL_KeyCode cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyFromScancode' {$ENDIF}{$ENDIF}; - - {** - * Get the scancode corresponding to the given key code according to the - * current keyboard layout. - * - * See SDL_Scancode for details. - * - * SDL_GetScancodeName() - *} - - function SDL_GetScancodeFromKey(key: TSDL_KeyCode): TSDL_ScanCode cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeFromKey' {$ENDIF}{$ENDIF}; - - {** - * Get a human-readable name for a scancode. - * - * A pointer to the name for the scancode. - * - * If the scancode doesn't have a name, this function returns - * an empty string (""). - * - *} - - function SDL_GetScancodeName(scancode: TSDL_ScanCode): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeName' {$ENDIF}{$ENDIF}; - - {** - * Get a scancode from a human-readable name - * - * scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized - * - * SDL_Scancode - *} - - function SDL_GetScancodeFromName(const name: PAnsiChar): TSDL_ScanCode cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeFromName' {$ENDIF}{$ENDIF}; - - {** - * Get a human-readable name for a key. - * - * A pointer to a UTF-8 string that stays valid at least until the next - * call to this function. If you need it around any longer, you must - * copy it. If the key doesn't have a name, this function returns an - * empty string (""). - * - * SDL_Key - *} - - function SDL_GetKeyName(key: TSDL_KeyCode): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyName' {$ENDIF}{$ENDIF}; - - {** - * Get a key code from a human-readable name - * - * key code, or SDLK_UNKNOWN if the name wasn't recognized - * - * SDL_Keycode - *} - - function SDL_GetKeyFromName(const name: PAnsiChar): TSDL_KeyCode cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyFromName' {$ENDIF}{$ENDIF}; - - {** - * Start accepting Unicode text input events. - * This function will show the on-screen keyboard if supported. - * - * SDL_StopTextInput() - * SDL_SetTextInputRect() - * SDL_HasScreenKeyboardSupport() - *} - - procedure SDL_StartTextInput cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StartTextInput' {$ENDIF}{$ENDIF}; - - {** - * Return whether or not Unicode text input events are enabled. - * - * SDL_StartTextInput() - * SDL_StopTextInput() - *} - - function SDL_IsTextInputActive: TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsTextInputActive' {$ENDIF}{$ENDIF}; - - {** - * Stop receiving any text input events. - * This function will hide the on-screen keyboard if supported. - * - * SDL_StartTextInput() - * SDL_HasScreenKeyboardSupport() - *} - - procedure SDL_StopTextInput cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StopTextInput' {$ENDIF}{$ENDIF}; - - {** - * Set the rectangle used to type Unicode text inputs. - * This is used as a hint for IME and on-screen keyboard placement. - * - * SDL_StartTextInput() - *} - - procedure SDL_SetTextInputRect(rect: PSDL_Rect) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetTextInputRect' {$ENDIF}{$ENDIF}; - - {** - * Returns whether the platform has some screen keyboard support. - * - * SDL_TRUE if some keyboard support is available else SDL_FALSE. - * - * Not all screen keyboard functions are supported on all platforms. - * - * SDL_IsScreenKeyboardShown() - *} - - function SDL_HasScreenKeyboardSupport: TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasScreenKeyboardSupport' {$ENDIF}{$ENDIF}; - - {** - * Returns whether the screen keyboard is shown for given window. - * - * window The window for which screen keyboard should be queried. - * - * Result - SDL_TRUE if screen keyboard is shown else SDL_FALSE. - * - * SDL_HasScreenKeyboardSupport() - *} +{ Function prototypes } + +{* + * Query the window which currently has keyboard focus. + * + * \returns the window with keyboard focus. + * + * \since This function is available since SDL 2.0.0. + } +function SDL_GetKeyboardFocus: PSDL_Window; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyboardFocus' {$ENDIF} {$ENDIF}; + +{* + * Get a snapshot of the current state of the keyboard. + * + * The pointer returned is a pointer to an internal SDL array. It will be + * valid for the whole lifetime of the application and should not be freed by + * the caller. + * + * A array element with a value of 1 means that the key is pressed and a value + * of 0 means that it is not. Indexes into this array are obtained by using + * SDL_Scancode values. + * + * Use SDL_PumpEvents() to update the state array. + * + * This function gives you the current state after all events have been + * processed, so if a key or button has been pressed and released before you + * process events, then the pressed state will never show up in the + * SDL_GetKeyboardState() calls. + * + * Note: This function doesn't take into account whether shift has been + * pressed or not. + * + * \param numkeys if non-nil, receives the length of the returned array + * \returns a pointer to an array of key states. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_PumpEvents + * \sa SDL_ResetKeyboard + } +function SDL_GetKeyboardState(numkeys: pcint): pcuint8; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyboardState' {$ENDIF} {$ENDIF}; + +{* + * Clear the state of the keyboard + * + * This function will generate key up events for all pressed keys. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GetKeyboardState + } +procedure SDL_ResetKeyboard; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResetKeyboard' {$ENDIF} {$ENDIF}; + +{* + * Get the current key modifier state for the keyboard. + * + * \returns an OR'd combination of the modifier keys for the keyboard. See + * SDL_Keymod for details. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyboardState + * \sa SDL_SetModState + } +function SDL_GetModState: TSDL_Keymod; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetModState' {$ENDIF} {$ENDIF}; + +{* + * Set the current key modifier state for the keyboard. + * + * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose + * modifier key states on your application. Simply pass your desired modifier + * states into `modstate`. This value may be a bitwise, OR'd combination of + * SDL_Keymod values. + * + * This does not change the keyboard state, only the key modifier flags that + * SDL reports. + * + * \param modstate the desired SDL_Keymod for the keyboard + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetModState + } +procedure SDL_SetModState(modstate: TSDL_Keymod); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetModState' {$ENDIF} {$ENDIF}; + +{* + * Get the key code corresponding to the given scancode according to the + * current keyboard layout. + * + * See SDL_Keycode for details. + * + * \param scancode the desired SDL_Scancode to query + * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyName + * \sa SDL_GetScancodeFromKey + } +function SDL_GetKeyFromScancode(scancode: TSDL_Scancode): TSDL_Keycode; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyFromScancode' {$ENDIF} {$ENDIF}; + +{* + * Get the scancode corresponding to the given key code according to the + * current keyboard layout. + * + * See SDL_Scancode for details. + * + * \param key the desired SDL_Keycode to query + * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetScancodeName + } +function SDL_GetScancodeFromKey(key: TSDL_Keycode): TSDL_Scancode; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeFromKey' {$ENDIF} {$ENDIF}; + +{* + * Get a human-readable name for a scancode. + * + * See SDL_Scancode for details. + * + * **Warning**: The returned name is by design not stable across platforms, + * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left + * Windows" under Microsoft Windows, and some scancodes like + * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even + * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and + * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore + * unsuitable for creating a stable cross-platform two-way mapping between + * strings and scancodes. + * + * \param scancode the desired SDL_Scancode to query + * \returns a pointer to the name for the scancode. If the scancode doesn't + * have a name this function returns an empty string (""). + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetScancodeFromKey + * \sa SDL_GetScancodeFromName + } +function SDL_GetScancodeName(scancode: TSDL_Scancode): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeName' {$ENDIF} {$ENDIF}; + +{* + * Get a scancode from a human-readable name. + * + * \param name the human-readable scancode name + * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't + * recognized; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyFromName + * \sa SDL_GetScancodeFromKey + * \sa SDL_GetScancodeName + } +function SDL_GetScancodeFromName(name: PAnsiChar): TSDL_Scancode; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetScancodeFromName' {$ENDIF} {$ENDIF}; + +{* + * Get a human-readable name for a key. + * + * See SDL_Scancode and SDL_Keycode for details. + * + * \param key the desired SDL_Keycode to query + * \returns a pointer to a UTF-8 string that stays valid at least until the + * next call to this function. If you need it around any longer, you + * must copy it. If the key doesn't have a name, this function + * returns an empty string (""). + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyFromName + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetScancodeFromKey + } +function SDL_GetKeyName(key: TSDL_Keycode): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyName' {$ENDIF} {$ENDIF}; + +{* + * Get a key code from a human-readable name. + * + * \param name the human-readable key name + * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetKeyName + * \sa SDL_GetScancodeFromName + } +function SDL_GetKeyFromName(name: PAnsiChar): TSDL_Keycode; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetKeyFromName' {$ENDIF} {$ENDIF}; + +{* + * Start accepting Unicode text input events. + * + * This function will start accepting Unicode text input events in the focused + * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and + * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in + * pair with SDL_StopTextInput(). + * + * On some platforms using this function activates the screen keyboard. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetTextInputRect + * \sa SDL_StopTextInput + } +procedure SDL_StartTextInput; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StartTextInput' {$ENDIF} {$ENDIF}; + +{* + * Check whether or not Unicode text input events are enabled. + * + * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_StartTextInput + } +function SDL_IsTextInputActive: TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsTextInputActive' {$ENDIF} {$ENDIF}; + +{* + * Stop receiving any text input events. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_StartTextInput + } +procedure SDL_StopTextInput; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StopTextInput' {$ENDIF} {$ENDIF}; + +{* + * Dismiss the composition window/IME without disabling the subsystem. + * + * \since This function is available since SDL 2.0.22. + * + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput + } +procedure SDL_ClearComposition; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ClearComposition' {$ENDIF} {$ENDIF}; + +{* + * Returns if an IME Composite or Candidate window is currently shown. + * + * \since This function is available since SDL 2.0.22. + } +function SDL_IsTextInputShown: TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsTextInputShown' {$ENDIF} {$ENDIF}; + +{* + * Set the rectangle used to type Unicode text inputs. + * + * To start text input in a given location, this function is intended to be + * called before SDL_StartTextInput, although some platforms support moving + * the rectangle even while text input (and a composition) is active. + * + * Note: If you want to use the system native IME window, try setting hint + * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you + * any feedback. + * + * \param rect the SDL_Rect structure representing the rectangle to receive + * text (ignored if nil) + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_StartTextInput + } +procedure SDL_SetTextInputRect(rect: PSDL_Rect); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetTextInputRect' {$ENDIF} {$ENDIF}; + +{* + * Check whether the platform has screen keyboard support. + * + * \returns SDL_TRUE if the platform has some screen keyboard support or + * SDL_FALSE if not. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_StartTextInput + * \sa SDL_IsScreenKeyboardShown + } +function SDL_HasScreenKeyboardSupport: TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasScreenKeyboardSupport' {$ENDIF} {$ENDIF}; + +{* + * Check whether the screen keyboard is shown for given window. + * + * \param window the window for which screen keyboard should be queried + * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HasScreenKeyboardSupport + } +function SDL_IsScreenKeyboardShown(window: PSDL_Window): TSDL_bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsScreenKeyboardShown' {$ENDIF} {$ENDIF}; - function SDL_IsScreenKeyboardShown(window: PSDL_Window): TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsScreenKeyboardShown' {$ENDIF}{$ENDIF}; diff --git a/units/sdlkeycode.inc b/units/sdlkeycode.inc new file mode 100644 index 00000000..6f676373 --- /dev/null +++ b/units/sdlkeycode.inc @@ -0,0 +1,320 @@ +//from "sdl_keycode.h" + + {** + * The SDL virtual key representation. + * + * Values of this type are used to represent keyboard keys using the current + * layout of the keyboard. These values include Unicode values representing + * the unmodified character that would be generated by pressing the key, or + * an SDLK_* constant for those keys that do not generate characters. + * + * A special exception is the number keys at the top of the keyboard which + * always map to SDLK_0...SDLK_9, regardless of layout. + *} +type + PPSDL_KeyCode = ^PSDL_KeyCode; + PSDL_KeyCode = ^TSDL_KeyCode; + TSDL_KeyCode = type cint32; + +const + SDLK_SCANCODE_MASK = 1 shl 30; + //#define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) + //SDL2-for-Pascal: Not translated, see comment about this macro below. + + SDLK_UNKNOWN = TSDL_KeyCode(0); + + SDLK_RETURN = TSDL_KeyCode(#13); // C: '\r' + SDLK_ESCAPE = TSDL_KeyCode(#27); // C: '\x1B' + SDLK_BACKSPACE = TSDL_KeyCode(#8); // C: '\b' + SDLK_TAB = TSDL_KeyCode(#9); // C: '\t' + SDLK_SPACE = TSDL_KeyCode(' '); + SDLK_EXCLAIM = TSDL_KeyCode('!'); + SDLK_QUOTEDBL = TSDL_KeyCode('"'); + SDLK_HASH = TSDL_KeyCode('#'); + SDLK_PERCENT = TSDL_KeyCode('%'); + SDLK_DOLLAR = TSDL_KeyCode('$'); + SDLK_AMPERSAND = TSDL_KeyCode('&'); + SDLK_QUOTE = TSDL_KeyCode(''''); + SDLK_LEFTPAREN = TSDL_KeyCode('('); + SDLK_RIGHTPAREN = TSDL_KeyCode(')'); + SDLK_ASTERISK = TSDL_KeyCode('*'); + SDLK_PLUS = TSDL_KeyCode('+'); + SDLK_COMMA = TSDL_KeyCode(','); + SDLK_MINUS = TSDL_KeyCode('-'); + SDLK_PERIOD = TSDL_KeyCode('.'); + SDLK_SLASH = TSDL_KeyCode('/'); + SDLK_0 = TSDL_KeyCode('0'); + SDLK_1 = TSDL_KeyCode('1'); + SDLK_2 = TSDL_KeyCode('2'); + SDLK_3 = TSDL_KeyCode('3'); + SDLK_4 = TSDL_KeyCode('4'); + SDLK_5 = TSDL_KeyCode('5'); + SDLK_6 = TSDL_KeyCode('6'); + SDLK_7 = TSDL_KeyCode('7'); + SDLK_8 = TSDL_KeyCode('8'); + SDLK_9 = TSDL_KeyCode('9'); + SDLK_COLON = TSDL_KeyCode(':'); + SDLK_SEMICOLON = TSDL_KeyCode(';'); + SDLK_LESS = TSDL_KeyCode('<'); + SDLK_EQUALS = TSDL_KeyCode('='); + SDLK_GREATER = TSDL_KeyCode('>'); + SDLK_QUESTION = TSDL_KeyCode('?'); + SDLK_AT = TSDL_KeyCode('@'); + {* + Skip uppercase letters + *} + SDLK_LEFTBRACKET = TSDL_KeyCode('['); + SDLK_BACKSLASH = TSDL_KeyCode('\'); // C: '\\' + SDLK_RIGHTBRACKET = TSDL_KeyCode(']'); + SDLK_CARET = TSDL_KeyCode('^'); + SDLK_UNDERSCORE = TSDL_KeyCode('_'); + SDLK_BACKQUOTE = TSDL_KeyCode('`'); + SDLK_a = TSDL_KeyCode('a'); + SDLK_b = TSDL_KeyCode('b'); + SDLK_c = TSDL_KeyCode('c'); + SDLK_d = TSDL_KeyCode('d'); + SDLK_e = TSDL_KeyCode('e'); + SDLK_f = TSDL_KeyCode('f'); + SDLK_g = TSDL_KeyCode('g'); + SDLK_h = TSDL_KeyCode('h'); + SDLK_i = TSDL_KeyCode('i'); + SDLK_j = TSDL_KeyCode('j'); + SDLK_k = TSDL_KeyCode('k'); + SDLK_l = TSDL_KeyCode('l'); + SDLK_m = TSDL_KeyCode('m'); + SDLK_n = TSDL_KeyCode('n'); + SDLK_o = TSDL_KeyCode('o'); + SDLK_p = TSDL_KeyCode('p'); + SDLK_q = TSDL_KeyCode('q'); + SDLK_r = TSDL_KeyCode('r'); + SDLK_s = TSDL_KeyCode('s'); + SDLK_t = TSDL_KeyCode('t'); + SDLK_u = TSDL_KeyCode('u'); + SDLK_v = TSDL_KeyCode('v'); + SDLK_w = TSDL_KeyCode('w'); + SDLK_x = TSDL_KeyCode('x'); + SDLK_y = TSDL_KeyCode('y'); + SDLK_z = TSDL_KeyCode('z'); + + {SDL2-for-Pascal: In C the following scancodes are or'd by a macro: + SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) + + We convert the scancodes directly by: + TSDL_KeyCode(X or SDLK_SCANCODE_MASK); } + + SDLK_CAPSLOCK = TSDL_KeyCode(SDL_SCANCODE_CAPSLOCK or SDLK_SCANCODE_MASK); + + SDLK_F1 = TSDL_KeyCode(SDL_SCANCODE_F1 or SDLK_SCANCODE_MASK); + SDLK_F2 = TSDL_KeyCode(SDL_SCANCODE_F2 or SDLK_SCANCODE_MASK); + SDLK_F3 = TSDL_KeyCode(SDL_SCANCODE_F3 or SDLK_SCANCODE_MASK); + SDLK_F4 = TSDL_KeyCode(SDL_SCANCODE_F4 or SDLK_SCANCODE_MASK); + SDLK_F5 = TSDL_KeyCode(SDL_SCANCODE_F5 or SDLK_SCANCODE_MASK); + SDLK_F6 = TSDL_KeyCode(SDL_SCANCODE_F6 or SDLK_SCANCODE_MASK); + SDLK_F7 = TSDL_KeyCode(SDL_SCANCODE_F7 or SDLK_SCANCODE_MASK); + SDLK_F8 = TSDL_KeyCode(SDL_SCANCODE_F8 or SDLK_SCANCODE_MASK); + SDLK_F9 = TSDL_KeyCode(SDL_SCANCODE_F9 or SDLK_SCANCODE_MASK); + SDLK_F10 = TSDL_KeyCode(SDL_SCANCODE_F10 or SDLK_SCANCODE_MASK); + SDLK_F11 = TSDL_KeyCode(SDL_SCANCODE_F11 or SDLK_SCANCODE_MASK); + SDLK_F12 = TSDL_KeyCode(SDL_SCANCODE_F12 or SDLK_SCANCODE_MASK); + + SDLK_PRINTSCREEN = TSDL_KeyCode(SDL_SCANCODE_PRINTSCREEN or SDLK_SCANCODE_MASK); + SDLK_SCROLLLOCK = TSDL_KeyCode(SDL_SCANCODE_SCROLLLOCK or SDLK_SCANCODE_MASK); + SDLK_PAUSE = TSDL_KeyCode(SDL_SCANCODE_PAUSE or SDLK_SCANCODE_MASK); + SDLK_INSERT = TSDL_KeyCode(SDL_SCANCODE_INSERT or SDLK_SCANCODE_MASK); + SDLK_HOME = TSDL_KeyCode(SDL_SCANCODE_HOME or SDLK_SCANCODE_MASK); + SDLK_PAGEUP = TSDL_KeyCode(SDL_SCANCODE_PAGEUP or SDLK_SCANCODE_MASK); + SDLK_DELETE = TSDL_KeyCode(#127); // C: '\x7F' + SDLK_END = TSDL_KeyCode(SDL_SCANCODE_END or SDLK_SCANCODE_MASK); + SDLK_PAGEDOWN = TSDL_KeyCode(SDL_SCANCODE_PAGEDOWN or SDLK_SCANCODE_MASK); + SDLK_RIGHT = TSDL_KeyCode(SDL_SCANCODE_RIGHT or SDLK_SCANCODE_MASK); + SDLK_LEFT = TSDL_KeyCode(SDL_SCANCODE_LEFT or SDLK_SCANCODE_MASK); + SDLK_DOWN = TSDL_KeyCode(SDL_SCANCODE_DOWN or SDLK_SCANCODE_MASK); + SDLK_UP = TSDL_KeyCode(SDL_SCANCODE_UP or SDLK_SCANCODE_MASK); + + SDLK_NUMLOCKCLEAR = TSDL_KeyCode(SDL_SCANCODE_NUMLOCKCLEAR or SDLK_SCANCODE_MASK); + SDLK_KP_DIVIDE = TSDL_KeyCode(SDL_SCANCODE_KP_DIVIDE or SDLK_SCANCODE_MASK); + SDLK_KP_MULTIPLY = TSDL_KeyCode(SDL_SCANCODE_KP_MULTIPLY or SDLK_SCANCODE_MASK); + SDLK_KP_MINUS = TSDL_KeyCode(SDL_SCANCODE_KP_MINUS or SDLK_SCANCODE_MASK); + SDLK_KP_PLUS = TSDL_KeyCode(SDL_SCANCODE_KP_PLUS or SDLK_SCANCODE_MASK); + SDLK_KP_ENTER = TSDL_KeyCode(SDL_SCANCODE_KP_ENTER or SDLK_SCANCODE_MASK); + SDLK_KP_1 = TSDL_KeyCode(SDL_SCANCODE_KP_1 or SDLK_SCANCODE_MASK); + SDLK_KP_2 = TSDL_KeyCode(SDL_SCANCODE_KP_2 or SDLK_SCANCODE_MASK); + SDLK_KP_3 = TSDL_KeyCode(SDL_SCANCODE_KP_3 or SDLK_SCANCODE_MASK); + SDLK_KP_4 = TSDL_KeyCode(SDL_SCANCODE_KP_4 or SDLK_SCANCODE_MASK); + SDLK_KP_5 = TSDL_KeyCode(SDL_SCANCODE_KP_5 or SDLK_SCANCODE_MASK); + SDLK_KP_6 = TSDL_KeyCode(SDL_SCANCODE_KP_6 or SDLK_SCANCODE_MASK); + SDLK_KP_7 = TSDL_KeyCode(SDL_SCANCODE_KP_7 or SDLK_SCANCODE_MASK); + SDLK_KP_8 = TSDL_KeyCode(SDL_SCANCODE_KP_8 or SDLK_SCANCODE_MASK); + SDLK_KP_9 = TSDL_KeyCode(SDL_SCANCODE_KP_9 or SDLK_SCANCODE_MASK); + SDLK_KP_0 = TSDL_KeyCode(SDL_SCANCODE_KP_0 or SDLK_SCANCODE_MASK); + SDLK_KP_PERIOD = TSDL_KeyCode(SDL_SCANCODE_KP_PERIOD or SDLK_SCANCODE_MASK); + + SDLK_APPLICATION = TSDL_KeyCode(SDL_SCANCODE_APPLICATION or SDLK_SCANCODE_MASK); + SDLK_POWER = TSDL_KeyCode(SDL_SCANCODE_POWER or SDLK_SCANCODE_MASK); + SDLK_KP_EQUALS = TSDL_KeyCode(SDL_SCANCODE_KP_EQUALS or SDLK_SCANCODE_MASK); + SDLK_F13 = TSDL_KeyCode(SDL_SCANCODE_F13 or SDLK_SCANCODE_MASK); + SDLK_F14 = TSDL_KeyCode(SDL_SCANCODE_F14 or SDLK_SCANCODE_MASK); + SDLK_F15 = TSDL_KeyCode(SDL_SCANCODE_F15 or SDLK_SCANCODE_MASK); + SDLK_F16 = TSDL_KeyCode(SDL_SCANCODE_F16 or SDLK_SCANCODE_MASK); + SDLK_F17 = TSDL_KeyCode(SDL_SCANCODE_F17 or SDLK_SCANCODE_MASK); + SDLK_F18 = TSDL_KeyCode(SDL_SCANCODE_F18 or SDLK_SCANCODE_MASK); + SDLK_F19 = TSDL_KeyCode(SDL_SCANCODE_F19 or SDLK_SCANCODE_MASK); + SDLK_F20 = TSDL_KeyCode(SDL_SCANCODE_F20 or SDLK_SCANCODE_MASK); + SDLK_F21 = TSDL_KeyCode(SDL_SCANCODE_F21 or SDLK_SCANCODE_MASK); + SDLK_F22 = TSDL_KeyCode(SDL_SCANCODE_F22 or SDLK_SCANCODE_MASK); + SDLK_F23 = TSDL_KeyCode(SDL_SCANCODE_F23 or SDLK_SCANCODE_MASK); + SDLK_F24 = TSDL_KeyCode(SDL_SCANCODE_F24 or SDLK_SCANCODE_MASK); + SDLK_EXECUTE = TSDL_KeyCode(SDL_SCANCODE_EXECUTE or SDLK_SCANCODE_MASK); + SDLK_HELP = TSDL_KeyCode(SDL_SCANCODE_HELP or SDLK_SCANCODE_MASK); + SDLK_MENU = TSDL_KeyCode(SDL_SCANCODE_MENU or SDLK_SCANCODE_MASK); + SDLK_SELECT = TSDL_KeyCode(SDL_SCANCODE_SELECT or SDLK_SCANCODE_MASK); + SDLK_STOP = TSDL_KeyCode(SDL_SCANCODE_STOP or SDLK_SCANCODE_MASK); + SDLK_AGAIN = TSDL_KeyCode(SDL_SCANCODE_AGAIN or SDLK_SCANCODE_MASK); + SDLK_UNDO = TSDL_KeyCode(SDL_SCANCODE_UNDO or SDLK_SCANCODE_MASK); + SDLK_CUT = TSDL_KeyCode(SDL_SCANCODE_CUT or SDLK_SCANCODE_MASK); + SDLK_COPY = TSDL_KeyCode(SDL_SCANCODE_COPY or SDLK_SCANCODE_MASK); + SDLK_PASTE = TSDL_KeyCode(SDL_SCANCODE_PASTE or SDLK_SCANCODE_MASK); + SDLK_FIND = TSDL_KeyCode(SDL_SCANCODE_FIND or SDLK_SCANCODE_MASK); + SDLK_MUTE = TSDL_KeyCode(SDL_SCANCODE_MUTE or SDLK_SCANCODE_MASK); + SDLK_VOLUMEUP = TSDL_KeyCode(SDL_SCANCODE_VOLUMEUP or SDLK_SCANCODE_MASK); + SDLK_VOLUMEDOWN = TSDL_KeyCode(SDL_SCANCODE_VOLUMEDOWN or SDLK_SCANCODE_MASK); + SDLK_KP_COMMA = TSDL_KeyCode(SDL_SCANCODE_KP_COMMA or SDLK_SCANCODE_MASK); + SDLK_KP_EQUALSAS400 = TSDL_KeyCode(SDL_SCANCODE_KP_EQUALSAS400 or SDLK_SCANCODE_MASK); + + SDLK_ALTERASE = TSDL_KeyCode(SDL_SCANCODE_ALTERASE or SDLK_SCANCODE_MASK); + SDLK_SYSREQ = TSDL_KeyCode(SDL_SCANCODE_SYSREQ or SDLK_SCANCODE_MASK); + SDLK_CANCEL = TSDL_KeyCode(SDL_SCANCODE_CANCEL or SDLK_SCANCODE_MASK); + SDLK_CLEAR = TSDL_KeyCode(SDL_SCANCODE_CLEAR or SDLK_SCANCODE_MASK); + SDLK_PRIOR = TSDL_KeyCode(SDL_SCANCODE_PRIOR or SDLK_SCANCODE_MASK); + SDLK_RETURN2 = TSDL_KeyCode(SDL_SCANCODE_RETURN2 or SDLK_SCANCODE_MASK); + SDLK_SEPARATOR = TSDL_KeyCode(SDL_SCANCODE_SEPARATOR or SDLK_SCANCODE_MASK); + SDLK_OUT = TSDL_KeyCode(SDL_SCANCODE_OUT or SDLK_SCANCODE_MASK); + SDLK_OPER = TSDL_KeyCode(SDL_SCANCODE_OPER or SDLK_SCANCODE_MASK); + SDLK_CLEARAGAIN = TSDL_KeyCode(SDL_SCANCODE_CLEARAGAIN or SDLK_SCANCODE_MASK); + SDLK_CRSEL = TSDL_KeyCode(SDL_SCANCODE_CRSEL or SDLK_SCANCODE_MASK); + SDLK_EXSEL = TSDL_KeyCode(SDL_SCANCODE_EXSEL or SDLK_SCANCODE_MASK); + + SDLK_KP_00 = TSDL_KeyCode(SDL_SCANCODE_KP_00 or SDLK_SCANCODE_MASK); + SDLK_KP_000 = TSDL_KeyCode(SDL_SCANCODE_KP_000 or SDLK_SCANCODE_MASK); + SDLK_THOUSANDSSEPARATOR = TSDL_KeyCode(SDL_SCANCODE_THOUSANDSSEPARATOR or SDLK_SCANCODE_MASK); + SDLK_DECIMALSEPARATOR = TSDL_KeyCode(SDL_SCANCODE_DECIMALSEPARATOR or SDLK_SCANCODE_MASK); + SDLK_CURRENCYUNIT = TSDL_KeyCode(SDL_SCANCODE_CURRENCYUNIT or SDLK_SCANCODE_MASK); + SDLK_CURRENCYSUBUNIT = TSDL_KeyCode(SDL_SCANCODE_CURRENCYSUBUNIT or SDLK_SCANCODE_MASK); + SDLK_KP_LEFTPAREN = TSDL_KeyCode(SDL_SCANCODE_KP_LEFTPAREN or SDLK_SCANCODE_MASK); + SDLK_KP_RIGHTPAREN = TSDL_KeyCode(SDL_SCANCODE_KP_RIGHTPAREN or SDLK_SCANCODE_MASK); + SDLK_KP_LEFTBRACE = TSDL_KeyCode(SDL_SCANCODE_KP_LEFTBRACE or SDLK_SCANCODE_MASK); + SDLK_KP_RIGHTBRACE = TSDL_KeyCode(SDL_SCANCODE_KP_RIGHTBRACE or SDLK_SCANCODE_MASK); + SDLK_KP_TAB = TSDL_KeyCode(SDL_SCANCODE_KP_TAB or SDLK_SCANCODE_MASK); + SDLK_KP_BACKSPACE = TSDL_KeyCode(SDL_SCANCODE_KP_BACKSPACE or SDLK_SCANCODE_MASK); + SDLK_KP_A = TSDL_KeyCode(SDL_SCANCODE_KP_A or SDLK_SCANCODE_MASK); + SDLK_KP_B = TSDL_KeyCode(SDL_SCANCODE_KP_B or SDLK_SCANCODE_MASK); + SDLK_KP_C = TSDL_KeyCode(SDL_SCANCODE_KP_C or SDLK_SCANCODE_MASK); + SDLK_KP_D = TSDL_KeyCode(SDL_SCANCODE_KP_D or SDLK_SCANCODE_MASK); + SDLK_KP_E = TSDL_KeyCode(SDL_SCANCODE_KP_E or SDLK_SCANCODE_MASK); + SDLK_KP_F = TSDL_KeyCode(SDL_SCANCODE_KP_F or SDLK_SCANCODE_MASK); + SDLK_KP_XOR = TSDL_KeyCode(SDL_SCANCODE_KP_XOR or SDLK_SCANCODE_MASK); + SDLK_KP_POWER = TSDL_KeyCode(SDL_SCANCODE_KP_POWER or SDLK_SCANCODE_MASK); + SDLK_KP_PERCENT = TSDL_KeyCode(SDL_SCANCODE_KP_PERCENT or SDLK_SCANCODE_MASK); + SDLK_KP_LESS = TSDL_KeyCode(SDL_SCANCODE_KP_LESS or SDLK_SCANCODE_MASK); + SDLK_KP_GREATER = TSDL_KeyCode(SDL_SCANCODE_KP_GREATER or SDLK_SCANCODE_MASK); + SDLK_KP_AMPERSAND = TSDL_KeyCode(SDL_SCANCODE_KP_AMPERSAND or SDLK_SCANCODE_MASK); + SDLK_KP_DBLAMPERSAND = TSDL_KeyCode(SDL_SCANCODE_KP_DBLAMPERSAND or SDLK_SCANCODE_MASK); + SDLK_KP_VERTICALBAR = TSDL_KeyCode(SDL_SCANCODE_KP_VERTICALBAR or SDLK_SCANCODE_MASK); + SDLK_KP_DBLVERTICALBAR = TSDL_KeyCode(SDL_SCANCODE_KP_DBLVERTICALBAR or SDLK_SCANCODE_MASK); + SDLK_KP_COLON = TSDL_KeyCode(SDL_SCANCODE_KP_COLON or SDLK_SCANCODE_MASK); + SDLK_KP_HASH = TSDL_KeyCode(SDL_SCANCODE_KP_HASH or SDLK_SCANCODE_MASK); + SDLK_KP_SPACE = TSDL_KeyCode(SDL_SCANCODE_KP_SPACE or SDLK_SCANCODE_MASK); + SDLK_KP_AT = TSDL_KeyCode(SDL_SCANCODE_KP_AT or SDLK_SCANCODE_MASK); + SDLK_KP_EXCLAM = TSDL_KeyCode(SDL_SCANCODE_KP_EXCLAM or SDLK_SCANCODE_MASK); + SDLK_KP_MEMSTORE = TSDL_KeyCode(SDL_SCANCODE_KP_MEMSTORE or SDLK_SCANCODE_MASK); + SDLK_KP_MEMRECALL = TSDL_KeyCode(SDL_SCANCODE_KP_MEMRECALL or SDLK_SCANCODE_MASK); + SDLK_KP_MEMCLEAR = TSDL_KeyCode(SDL_SCANCODE_KP_MEMCLEAR or SDLK_SCANCODE_MASK); + SDLK_KP_MEMADD = TSDL_KeyCode(SDL_SCANCODE_KP_MEMADD or SDLK_SCANCODE_MASK); + SDLK_KP_MEMSUBTRACT = TSDL_KeyCode(SDL_SCANCODE_KP_MEMSUBTRACT or SDLK_SCANCODE_MASK); + SDLK_KP_MEMMULTIPLY = TSDL_KeyCode(SDL_SCANCODE_KP_MEMMULTIPLY or SDLK_SCANCODE_MASK); + SDLK_KP_MEMDIVIDE = TSDL_KeyCode(SDL_SCANCODE_KP_MEMDIVIDE or SDLK_SCANCODE_MASK); + SDLK_KP_PLUSMINUS = TSDL_KeyCode(SDL_SCANCODE_KP_PLUSMINUS or SDLK_SCANCODE_MASK); + SDLK_KP_CLEAR = TSDL_KeyCode(SDL_SCANCODE_KP_CLEAR or SDLK_SCANCODE_MASK); + SDLK_KP_CLEARENTRY = TSDL_KeyCode(SDL_SCANCODE_KP_CLEARENTRY or SDLK_SCANCODE_MASK); + SDLK_KP_BINARY = TSDL_KeyCode(SDL_SCANCODE_KP_BINARY or SDLK_SCANCODE_MASK); + SDLK_KP_OCTAL = TSDL_KeyCode(SDL_SCANCODE_KP_OCTAL or SDLK_SCANCODE_MASK); + SDLK_KP_DECIMAL = TSDL_KeyCode(SDL_SCANCODE_KP_DECIMAL or SDLK_SCANCODE_MASK); + SDLK_KP_HEXADECIMAL = TSDL_KeyCode(SDL_SCANCODE_KP_HEXADECIMAL or SDLK_SCANCODE_MASK); + + SDLK_LCTRL = TSDL_KeyCode(SDL_SCANCODE_LCTRL or SDLK_SCANCODE_MASK); + SDLK_LSHIFT = TSDL_KeyCode(SDL_SCANCODE_LSHIFT or SDLK_SCANCODE_MASK); + SDLK_LALT = TSDL_KeyCode(SDL_SCANCODE_LALT or SDLK_SCANCODE_MASK); + SDLK_LGUI = TSDL_KeyCode(SDL_SCANCODE_LGUI or SDLK_SCANCODE_MASK); + SDLK_RCTRL = TSDL_KeyCode(SDL_SCANCODE_RCTRL or SDLK_SCANCODE_MASK); + SDLK_RSHIFT = TSDL_KeyCode(SDL_SCANCODE_RSHIFT or SDLK_SCANCODE_MASK); + SDLK_RALT = TSDL_KeyCode(SDL_SCANCODE_RALT or SDLK_SCANCODE_MASK); + SDLK_RGUI = TSDL_KeyCode(SDL_SCANCODE_RGUI or SDLK_SCANCODE_MASK); + + SDLK_MODE = TSDL_KeyCode(SDL_SCANCODE_MODE or SDLK_SCANCODE_MASK); + + SDLK_AUDIONEXT = TSDL_KeyCode(SDL_SCANCODE_AUDIONEXT or SDLK_SCANCODE_MASK); + SDLK_AUDIOPREV = TSDL_KeyCode(SDL_SCANCODE_AUDIOPREV or SDLK_SCANCODE_MASK); + SDLK_AUDIOSTOP = TSDL_KeyCode(SDL_SCANCODE_AUDIOSTOP or SDLK_SCANCODE_MASK); + SDLK_AUDIOPLAY = TSDL_KeyCode(SDL_SCANCODE_AUDIOPLAY or SDLK_SCANCODE_MASK); + SDLK_AUDIOMUTE = TSDL_KeyCode(SDL_SCANCODE_AUDIOMUTE or SDLK_SCANCODE_MASK); + SDLK_MEDIASELECT = TSDL_KeyCode(SDL_SCANCODE_MEDIASELECT or SDLK_SCANCODE_MASK); + SDLK_WWW = TSDL_KeyCode(SDL_SCANCODE_WWW or SDLK_SCANCODE_MASK); + SDLK_MAIL = TSDL_KeyCode(SDL_SCANCODE_MAIL or SDLK_SCANCODE_MASK); + SDLK_CALCULATOR = TSDL_KeyCode(SDL_SCANCODE_CALCULATOR or SDLK_SCANCODE_MASK); + SDLK_COMPUTER = TSDL_KeyCode(SDL_SCANCODE_COMPUTER or SDLK_SCANCODE_MASK); + SDLK_AC_SEARCH = TSDL_KeyCode(SDL_SCANCODE_AC_SEARCH or SDLK_SCANCODE_MASK); + SDLK_AC_HOME = TSDL_KeyCode(SDL_SCANCODE_AC_HOME or SDLK_SCANCODE_MASK); + SDLK_AC_BACK = TSDL_KeyCode(SDL_SCANCODE_AC_BACK or SDLK_SCANCODE_MASK); + SDLK_AC_FORWARD = TSDL_KeyCode(SDL_SCANCODE_AC_FORWARD or SDLK_SCANCODE_MASK); + SDLK_AC_STOP = TSDL_KeyCode(SDL_SCANCODE_AC_STOP or SDLK_SCANCODE_MASK); + SDLK_AC_REFRESH = TSDL_KeyCode(SDL_SCANCODE_AC_REFRESH or SDLK_SCANCODE_MASK); + SDLK_AC_BOOKMARKS = TSDL_KeyCode(SDL_SCANCODE_AC_BOOKMARKS or SDLK_SCANCODE_MASK); + + SDLK_BRIGHTNESSDOWN = TSDL_KeyCode(SDL_SCANCODE_BRIGHTNESSDOWN or SDLK_SCANCODE_MASK); + SDLK_BRIGHTNESSUP = TSDL_KeyCode(SDL_SCANCODE_BRIGHTNESSUP or SDLK_SCANCODE_MASK); + SDLK_DISPLAYSWITCH = TSDL_KeyCode(SDL_SCANCODE_DISPLAYSWITCH or SDLK_SCANCODE_MASK); + SDLK_KBDILLUMTOGGLE = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMTOGGLE or SDLK_SCANCODE_MASK); + SDLK_KBDILLUMDOWN = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMDOWN or SDLK_SCANCODE_MASK); + SDLK_KBDILLUMUP = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMUP or SDLK_SCANCODE_MASK); + SDLK_EJECT = TSDL_KeyCode(SDL_SCANCODE_EJECT or SDLK_SCANCODE_MASK); + SDLK_SLEEP = TSDL_KeyCode(SDL_SCANCODE_SLEEP or SDLK_SCANCODE_MASK); + SDLK_APP1 = TSDL_KeyCode(SDL_SCANCODE_APP1 or SDLK_SCANCODE_MASK); + SDLK_APP2 = TSDL_KeyCode(SDL_SCANCODE_APP2 or SDLK_SCANCODE_MASK); + + SDLK_AUDIOREWIND = TSDL_KeyCode(SDL_SCANCODE_AUDIOREWIND or SDLK_SCANCODE_MASK); + SDLK_AUDIOFASTFORWARD = TSDL_KeyCode(SDL_SCANCODE_AUDIOFASTFORWARD or SDLK_SCANCODE_MASK); + + SDLK_SOFTLEFT = TSDL_KeyCode(SDL_SCANCODE_SOFTLEFT or SDLK_SCANCODE_MASK); + SDLK_SOFTRIGHT = TSDL_KeyCode(SDL_SCANCODE_SOFTRIGHT or SDLK_SCANCODE_MASK); + SDLK_CALL = TSDL_KeyCode(SDL_SCANCODE_CALL or SDLK_SCANCODE_MASK); + SDLK_ENDCALL = TSDL_KeyCode(SDL_SCANCODE_ENDCALL or SDLK_SCANCODE_MASK); + + {** + * Enumeration of valid key mods (possibly OR'd together). + *} +type + PPSDL_KeyMod = ^PSDL_KeyMod; + PSDL_KeyMod = ^TSDL_KeyMod; + TSDL_KeyMod = type cint; + +const + KMOD_NONE = TSDL_KeyMod($0000); + KMOD_LSHIFT = TSDL_KeyMod($0001); + KMOD_RSHIFT = TSDL_KeyMod($0002); + KMOD_LCTRL = TSDL_KeyMod($0040); + KMOD_RCTRL = TSDL_KeyMod($0080); + KMOD_LALT = TSDL_KeyMod($0100); + KMOD_RALT = TSDL_KeyMod($0200); + KMOD_LGUI = TSDL_KeyMod($0400); + KMOD_RGUI = TSDL_KeyMod($0800); + KMOD_NUM = TSDL_KeyMod($1000); + KMOD_CAPS = TSDL_KeyMod($2000); + KMOD_MODE = TSDL_KeyMod($4000); + KMOD_SCROLL = TSDL_KeyMod($8000); + + KMOD_CTRL = KMOD_LCTRL or KMOD_RCTRL; + KMOD_SHIFT = KMOD_LSHIFT or KMOD_RSHIFT; + KMOD_ALT = KMOD_LALT or KMOD_RALT; + KMOD_GUI = KMOD_LGUI or KMOD_RGUI; + + KMOD_RESERVED = KMOD_SCROLL; {* This is for source-level compatibility with SDL 2.0.0. *} diff --git a/units/sdlloadso.inc b/units/sdlloadso.inc index 2a7ca133..fb5a4236 100644 --- a/units/sdlloadso.inc +++ b/units/sdlloadso.inc @@ -1,23 +1,76 @@ //from sdl_loadso.h -{** - * This function dynamically loads a shared object and returns a pointer - * to the object handle (or NULL if there was an error). - * The 'sofile' parameter is a system dependent name of the object file. - *} -function SDL_LoadObject(Const sofile: PAnsiChar): Pointer; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadObject' {$ENDIF}{$ENDIF}; +{* + * \file SDL_loadso.h + * + * System dependent library loading routines + * + * Some things to keep in mind: + * \li These functions only work on C function names. Other languages may + * have name mangling and intrinsic language support that varies from + * compiler to compiler. + * \li Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * \li Avoid namespace collisions. If you load a symbol from the library, + * it is not defined whether or not it goes into the global symbol + * namespace for the application. If it does and it conflicts with + * symbols in your code or other shared libraries, you will not get + * the results you expect.:) + } -{** - * Given an object handle, this function looks up the address of the - * named function in the shared object and returns it. This address - * is no longer valid after calling SDL_UnloadObject(). - *} -function SDL_LoadFunction(handle: Pointer; Const name: PAnsiChar): Pointer; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFunction' {$ENDIF}{$ENDIF}; +{* + * Dynamically load a shared object. + * + * \param sofile a system-dependent name of the object file + * \returns an opaque pointer to the object handle or nil if there was an + * error; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + } +function SDL_LoadObject(sofile: PAnsiChar): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadObject' {$ENDIF} {$ENDIF}; -{** - * Unload a shared object from memory. - *} +{* + * Look up the address of the named function in a shared object. + * + * This function pointer is no longer valid after calling SDL_UnloadObject(). + * + * This function can only look up C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * + * Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * + * If the requested function doesn't exist, nil is returned. + * + * \param handle a valid shared object handle returned by SDL_LoadObject() + * \param name the name of the function to look up + * \returns a pointer to the function or nil if there was an error; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadObject + * \sa SDL_UnloadObject + } +function SDL_LoadFunction(handle: Pointer; name: PAnsiChar): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFunction' {$ENDIF} {$ENDIF}; + +{* + * Unload a shared object from memory. + * + * \param handle a valid shared object handle returned by SDL_LoadObject() + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_LoadFunction + * \sa SDL_LoadObject + } procedure SDL_UnloadObject(handle: Pointer); cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnloadObject' {$ENDIF}{$ENDIF}; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnloadObject' {$ENDIF} {$ENDIF}; diff --git a/units/sdllocale.inc b/units/sdllocale.inc new file mode 100644 index 00000000..9230152b --- /dev/null +++ b/units/sdllocale.inc @@ -0,0 +1,54 @@ +// based on SDL_locale.h + +type + PPSDL_Locale = ^PSDL_Locale; + PSDL_Locale = ^TSDL_Locale; + TSDL_Locale = record + // A language name, like 'en' for English. + language: PAnsiChar; + // A country, like 'US' for America. Can be NIL. + country: PAnsiChar; + end; + +{** + * \brief Report the user's preferred locale. + * + * This returns an array of SDL_Locale structs, the final item zeroed out. + * When the caller is done with this array, it should call SDL_free() on + * the returned value; all the memory involved is allocated in a single + * block, so a single SDL_free() will suffice. + * + * Returned language strings are in the format xx, where 'xx' is an ISO-639 + * language specifier (such as 'en' for English, 'de' for German, etc). + * Country strings are in the format YY, where 'YY' is an ISO-3166 country + * code (such as "US" for the United States, 'CA' for Canada, etc). Country + * might be NULL if there's no specific guidance on them (so you might get + * ( 'en', 'US' ) for American English, but ( 'en', NIL ) means "English + * language, generically"). Language strings are never NIL, except to + * terminate the array. + * + * Please note that not all of these strings are 2 characters; some are + * three or more. + * + * The returned list of locales are in the order of the user's preference. + * For example, a German citizen that is fluent in US English and knows + * enough Japanese to navigate around Tokyo might have a list like: + * [ 'de', 'en_US', 'jp', NIL ]. Someone from England might prefer British + * English (where "color" is spelled "colour", etc), but will settle for + * anything like it: [ 'en_GB', 'en', NIL ]. + * + * This function returns NIL on error, including when the platform does not + * supply this information at all. + * + * This might be a "slow" call that has to query the operating system. It's + * best to ask for this once and save the results. However, this list can + * change, usually because the user has changed a system preference outside + * of your program; SDL will send an SDL_LOCALECHANGED event in this case, + * if possible, and you can call this function again to get an updated copy + * of preferred locales. + * + * \return array of locales, terminated with a locale with a NIL language + * field. Will return NIL on error. + *} +function SDL_GetPreferredLocales(): PSDL_Locale; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPreferredLocales' {$ENDIF} {$ENDIF}; diff --git a/units/sdllog.inc b/units/sdllog.inc index ad665581..23e1bc12 100644 --- a/units/sdllog.inc +++ b/units/sdllog.inc @@ -19,6 +19,8 @@ const * CRITICAL level. *} type + PPSDL_LogCategory = ^PSDL_LogCategory; + PSDL_LogCategory = ^TSDL_LogCategory; TSDL_LogCategory = type cint; const @@ -50,7 +52,8 @@ const {** * \brief The predefined log priorities *} -type +type + PPSDL_LogPriority = ^PSDL_LogPriority; PSDL_LogPriority = ^TSDL_LogPriority; TSDL_LogPriority = type cint32; const @@ -146,13 +149,14 @@ procedure SDL_LogMessageV(category: TSDL_LogCategory; priority: TSDL_LogPriority * \brief The prototype for the log output function *} type + PPSDL_LogOutputFunction = ^PSDL_LogOutputFunction; + PSDL_LogOutputFunction = ^TSDL_LogOutputFunction; TSDL_LogOutputFunction = procedure( userdata: Pointer; category: TSDL_LogCategory; priority: TSDL_LogPriority; - const msg: PAnsiChar); - PSDL_LogOutputFunction = ^TSDL_LogOutputFunction; - + const msg: PAnsiChar); cdecl; + {** * \brief Get the current log output function. *} diff --git a/units/sdlmessagebox.inc b/units/sdlmessagebox.inc index 8b086f25..c9926db6 100644 --- a/units/sdlmessagebox.inc +++ b/units/sdlmessagebox.inc @@ -4,6 +4,8 @@ * SDL_MessageBox flags. If supported will display warning icon, etc. *} type + PPSDL_MessageBoxFlags = ^PSDL_MessageBoxFlags; + PSDL_MessageBoxFlags = ^TSDL_MessageBoxFlags; TSDL_MessageBoxFlags = type cuint32; const @@ -17,6 +19,8 @@ const * Flags for SDL_MessageBoxButtonData. *} type + PPSDL_MessageBoxButtonFlags = ^PSDL_MessageBoxButtonFlags; + PSDL_MessageBoxButtonFlags = ^TSDL_MessageBoxButtonFlags; TSDL_MessageBoxButtonFlags = type cuint32; const @@ -28,6 +32,7 @@ const * Individual button data. *} type + PPSDL_MessageBoxButtonData = ^PSDL_MessageBoxButtonData; PSDL_MessageBoxButtonData = ^TSDL_MessageBoxButtonData; TSDL_MessageBoxButtonData = record flags: TSDL_MessageBoxButtonFlags; {**< ::SDL_MessageBoxButtonFlags *} @@ -39,11 +44,13 @@ type * RGB value used in a message box color scheme *} type + PPSDL_MessageBoxColor = ^PSDL_MessageBoxColor; PSDL_MessageBoxColor = ^TSDL_MessageBoxColor; TSDL_MessageBoxColor = record r, g, b: cuint8; end; + PPSDL_MessageBoxColorType = ^PSDL_MessageBoxColorType; PSDL_MessageBoxColorType = ^TSDL_MessageBoxColorType; TSDL_MessageBoxColorType = type Word; @@ -59,6 +66,7 @@ const * A set of colors to use for message box dialogs *} type + PPSDL_MessageBoxColorScheme = ^PSDL_MessageBoxColorScheme; PSDL_MessageBoxColorScheme = ^TSDL_MessageBoxColorScheme; TSDL_MessageBoxColorScheme = record colors: array[0..SDL_MESSAGEBOX_COLOR_MAX-1] of TSDL_MessageBoxColor; @@ -68,6 +76,7 @@ type * MessageBox structure containing title, text, window, etc. *} type + PPSDL_MessageBoxData = ^PSDL_MessageBoxData; PSDL_MessageBoxData = ^TSDL_MessageBoxData; TSDL_MessageBoxData = record flags: TSDL_MessageBoxFlags; {**< SDL_MessageBoxFlags *} diff --git a/units/sdlmisc.inc b/units/sdlmisc.inc new file mode 100644 index 00000000..a975c072 --- /dev/null +++ b/units/sdlmisc.inc @@ -0,0 +1,29 @@ +// based on SDL_misc.h + +{** + * \brief Open an URL / URI in the browser or other + * + * Open a URL in a separate, system-provided application. How this works will + * vary wildly depending on the platform. This will likely launch what + * makes sense to handle a specific URL's protocol (a web browser for http://, + * etc), but it might also be able to launch file managers for directories + * and other things. + * + * What happens when you open a URL varies wildly as well: your game window + * may lose focus (and may or may not lose focus if your game was fullscreen + * or grabbing input at the time). On mobile devices, your app will likely + * move to the background or your process might be paused. Any given platform + * may or may not handle a given URL. + * + * If this is unimplemented (or simply unavailable) for a platform, this will + * fail with an error. A successful result does not mean the URL loaded, just + * that we launched something to handle it (or at least believe we did). + * + * All this to say: this function can be useful, but you should definitely + * test it on every platform you target. + * + * \param url A valid URL to open. + * \return 0 on success, or -1 on error. + *} +function SDL_OpenURL(const url: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenURL' {$ENDIF} {$ENDIF}; diff --git a/units/sdlmouse.inc b/units/sdlmouse.inc index 98adc59b..63ef977b 100644 --- a/units/sdlmouse.inc +++ b/units/sdlmouse.inc @@ -1,260 +1,442 @@ //from "sdl_mouse.h" type - PSDL_Cursor = Pointer; + PPSDL_Cursor = ^PSDL_Cursor; + PSDL_Cursor = type Pointer; {**< Implementation dependent *} {** * Cursor types for SDL_CreateSystemCursor. *} type + PPSDL_SystemCursor = ^PSDL_SystemCursor; PSDL_SystemCursor = ^TSDL_SystemCursor; - TSDL_SystemCursor = type Word; + TSDL_SystemCursor = type Integer; + const - SDL_SYSTEM_CURSOR_ARROW = TSDL_SystemCursor(0); // Arrow - SDL_SYSTEM_CURSOR_IBEAM = TSDL_SystemCursor(1); // I-beam - SDL_SYSTEM_CURSOR_WAIT = TSDL_SystemCursor(2); // Wait - SDL_SYSTEM_CURSOR_CROSSHAIR = TSDL_SystemCursor(3); // Crosshair - SDL_SYSTEM_CURSOR_WAITARROW = TSDL_SystemCursor(4); // Small wait cursor (or Wait if not available) - SDL_SYSTEM_CURSOR_SIZENWSE = TSDL_SystemCursor(5); // Double arrow pointing northwest and southeast - SDL_SYSTEM_CURSOR_SIZENESW = TSDL_SystemCursor(6); // Double arrow pointing northeast and southwest - SDL_SYSTEM_CURSOR_SIZEWE = TSDL_SystemCursor(7); // Double arrow pointing west and east - SDL_SYSTEM_CURSOR_SIZENS = TSDL_SystemCursor(8); // Double arrow pointing north and south - SDL_SYSTEM_CURSOR_SIZEALL = TSDL_SystemCursor(9); // Four pointed arrow pointing north, south, east, and west + SDL_SYSTEM_CURSOR_ARROW = TSDL_SystemCursor(0); // Arrow + SDL_SYSTEM_CURSOR_IBEAM = TSDL_SystemCursor(1); // I-beam + SDL_SYSTEM_CURSOR_WAIT = TSDL_SystemCursor(2); // Wait + SDL_SYSTEM_CURSOR_CROSSHAIR = TSDL_SystemCursor(3); // Crosshair + SDL_SYSTEM_CURSOR_WAITARROW = TSDL_SystemCursor(4); // Small wait cursor (or Wait if not available) + SDL_SYSTEM_CURSOR_SIZENWSE = TSDL_SystemCursor(5); // Double arrow pointing northwest and southeast + SDL_SYSTEM_CURSOR_SIZENESW = TSDL_SystemCursor(6); // Double arrow pointing northeast and southwest + SDL_SYSTEM_CURSOR_SIZEWE = TSDL_SystemCursor(7); // Double arrow pointing west and east + SDL_SYSTEM_CURSOR_SIZENS = TSDL_SystemCursor(8); // Double arrow pointing north and south + SDL_SYSTEM_CURSOR_SIZEALL = TSDL_SystemCursor(9); // Four pointed arrow pointing north, south, east, and west SDL_SYSTEM_CURSOR_NO = TSDL_SystemCursor(10); // Slashed circle or crossbones SDL_SYSTEM_CURSOR_HAND = TSDL_SystemCursor(11); // Hand SDL_NUM_SYSTEM_CURSORS = TSDL_SystemCursor(12); +type + PPSDL_MouseWheelDirection = ^PSDL_MouseWheelDirection; + PSDL_MouseWheelDirection = ^TSDL_MouseWheelDirection; + TSDL_MouseWheelDirection = type Integer; + +const + SDL_MOUSEWHEEL_NORMAL = TSDL_MouseWheelDirection(0); {**< The scroll direction is normal *} + SDL_MOUSEWHEEL_FLIPPED = TSDL_MouseWheelDirection(1); {**< The scroll direction is flipped / natural *} {* Function prototypes *} {** - * Get the window which currently has mouse focus. - *} - - function SDL_GetMouseFocus: PSDL_Window cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMouseFocus' {$ENDIF}{$ENDIF}; + * Get the window which currently has mouse focus. + * + * \returns the window with mouse focus. + * + * \since This function is available since SDL 2.0.0. + *} +function SDL_GetMouseFocus: PSDL_Window; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMouseFocus' {$ENDIF}{$ENDIF}; {** - * Retrieve the current state of the mouse. - * - * The current button state is returned as a button bitmask, which can - * be tested using the SDL_BUTTON(X) macros, and x and y are set to the - * mouse cursor position relative to the focus window for the currently - * selected mouse. You can pass nil for either x or y. - * - * SDL_Button = 1 shl ((X)-1) - *} - - function SDL_GetMouseState(x: pcint; y: pcint): cuint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMouseState' {$ENDIF}{$ENDIF}; + * Retrieve the current state of the mouse. + * + * The current button state is returned as a button bitmask, which can be + * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the + * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the + * mouse cursor position relative to the focus window. You can pass NULL for + * either `x` or `y`. + * + * \param x the x coordinate of the mouse cursor position relative to the + * focus window + * \param y the y coordinate of the mouse cursor position relative to the + * focus window + * \returns a 32-bit button bitmask of the current button state. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetGlobalMouseState + * \sa SDL_GetRelativeMouseState + * \sa SDL_PumpEvents + *} +function SDL_GetMouseState(x: pcint; y: pcint): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMouseState' {$ENDIF}{$ENDIF}; {** - * \brief Get the current state of the mouse, in relation to the desktop - * - * This works just like SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if - * you need to track the mouse outside of a specific window and - * SDL_CaptureMouse() doesn't fit your needs. For example, it could be - * useful if you need to track the mouse while dragging a window, where - * coordinates relative to a window might not be in sync at all times. - * - * \note SDL_GetMouseState() returns the mouse position as SDL understands - * it from the last pump of the event queue. This function, however, - * queries the OS for the current mouse position, and as such, might - * be a slightly less efficient function. Unless you know what you're - * doing and have a good reason to use this function, you probably want - * SDL_GetMouseState() instead. - * - * \param x Returns the current X coord, relative to the desktop. Can be NULL. - * \param y Returns the current Y coord, relative to the desktop. Can be NULL. - * \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros. - * - * \sa SDL_GetMouseState - *} - function SDL_GetGlobalMouseState(x, y: pcint32): cuint32; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGlobalMouseState' {$ENDIF}{$ENDIF}; + * Get the current state of the mouse in relation to the desktop. + * + * This works similarly to SDL_GetMouseState(), but the coordinates will be + * reported relative to the top-left of the desktop. This can be useful if you + * need to track the mouse outside of a specific window and SDL_CaptureMouse() + * doesn't fit your needs. For example, it could be useful if you need to + * track the mouse while dragging a window, where coordinates relative to a + * window might not be in sync at all times. + * + * Note: SDL_GetMouseState() returns the mouse position as SDL understands it + * from the last pump of the event queue. This function, however, queries the + * OS for the current mouse position, and as such, might be a slightly less + * efficient function. Unless you know what you're doing and have a good + * reason to use this function, you probably want SDL_GetMouseState() instead. + * + * \param x filled in with the current X coord relative to the desktop; can be + * NULL + * \param y filled in with the current Y coord relative to the desktop; can be + * NULL + * \returns the current button state as a bitmask which can be tested using + * the SDL_BUTTON(X) macros. + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_CaptureMouse + *} +function SDL_GetGlobalMouseState(x, y: pcint32): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGlobalMouseState' {$ENDIF}{$ENDIF}; {** - * Retrieve the relative state of the mouse. - * - * The current button state is returned as a button bitmask, which can - * be tested using the SDL_BUTTON(X) macros, and x and y are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState(). - *} - - function SDL_GetRelativeMouseState(x: pcint; y: pcint): cuint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRelativeMouseState' {$ENDIF}{$ENDIF}; + * Retrieve the relative state of the mouse. + * + * The current button state is returned as a button bitmask, which can be + * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the + * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the + * mouse deltas since the last call to SDL_GetRelativeMouseState() or since + * event initialization. You can pass NULL for either `x` or `y`. + * + * \param x a pointer filled with the last recorded x coordinate of the mouse + * \param y a pointer filled with the last recorded y coordinate of the mouse + * \returns a 32-bit button bitmask of the relative button state. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetMouseState + *} +function SDL_GetRelativeMouseState(x: pcint; y: pcint): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRelativeMouseState' {$ENDIF}{$ENDIF}; {** - * Moves the mouse to the given position within the window. - * - * window The window to move the mouse into, or nil for the current mouse focus - * x The x coordinate within the window - * y The y coordinate within the window - * - * This function generates a mouse motion event - *} - - procedure SDL_WarpMouseInWindow(window: PSDL_Window; x: cint32; y: cint32) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WarpMouseInWindow' {$ENDIF}{$ENDIF}; + * Move the mouse cursor to the given position within the window. + * + * This function generates a mouse motion event if relative mode is not + * enabled. If relative mode is enabled, you can force mouse events for the + * warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint. + * + * Note that this function will appear to succeed, but not actually move the + * mouse when used over Microsoft Remote Desktop. + * + * \param window the window to move the mouse into, or NULL for the current + * mouse focus + * \param x the x coordinate within the window + * \param y the y coordinate within the window + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_WarpMouseGlobal + *} +procedure SDL_WarpMouseInWindow(window: PSDL_Window; x: cint; y: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WarpMouseInWindow' {$ENDIF}{$ENDIF}; {** - * \brief Moves the mouse to the given position in global screen space. - * - * \param x The x coordinate - * \param y The y coordinate - * \return 0 on success, -1 on error (usually: unsupported by a platform). - * - * \note This function generates a mouse motion event - *} - Function SDL_WarpMouseGlobal(x, y: cint32): cint32; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WarpMouseGlobal' {$ENDIF}{$ENDIF}; + * Move the mouse to the given position in global screen space. + * + * This function generates a mouse motion event. + * + * A failure of this function usually means that it is unsupported by a + * platform. + * + * Note that this function will appear to succeed, but not actually move the + * mouse when used over Microsoft Remote Desktop. + * + * \param x the x coordinate + * \param y the y coordinate + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_WarpMouseInWindow + *} +function SDL_WarpMouseGlobal(x, y: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WarpMouseGlobal' {$ENDIF}{$ENDIF}; {** - * Set relative mouse mode. - * - * enabled Whether or not to enable relative mode - * - * 0 on success, or -1 if relative mode is not supported. - * - * While the mouse is in relative mode, the cursor is hidden, and the - * driver will try to report continuous motion in the current window. - * Only relative motion events will be delivered, the mouse position - * will not change. - * - * This function will flush any pending mouse motion. - * - * SDL_GetRelativeMouseMode() - *} - - function SDL_SetRelativeMouseMode(enabled: TSDL_Bool): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetRelativeMouseMode' {$ENDIF}{$ENDIF}; + * Set relative mouse mode. + * + * While the mouse is in relative mode, the cursor is hidden, and the driver + * will try to report continuous motion in the current window. Only relative + * motion events will be delivered, the mouse position will not change. + * + * Note that this function will not be able to provide continuous relative + * motion when used over Microsoft Remote Desktop, instead motion is limited + * to the bounds of the screen. + * + * This function will flush any pending mouse motion. + * + * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * If relative mode is not supported, this returns -1. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetRelativeMouseMode + *} +function SDL_SetRelativeMouseMode(enabled: TSDL_Bool): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetRelativeMouseMode' {$ENDIF}{$ENDIF}; {** - * \brief Capture the mouse, to track input outside an SDL window. - * - * \param enabled Whether or not to enable capturing - * - * Capturing enables your app to obtain mouse events globally, instead of - * just within your window. Not all video targets support this function. - * When capturing is enabled, the current window will get all mouse events, - * but unlike relative mode, no change is made to the cursor and it is - * not restrained to your window. - * - * This function may also deny mouse input to other windows--both those in - * your application and others on the system--so you should use this - * function sparingly, and in small bursts. For example, you might want to - * track the mouse while the user is dragging something, until the user - * releases a mouse button. It is not recommended that you capture the mouse - * for long periods of time, such as the entire time your app is running. - * - * While captured, mouse events still report coordinates relative to the - * current (foreground) window, but those coordinates may be outside the - * bounds of the window (including negative values). Capturing is only - * allowed for the foreground window. If the window loses focus while - * capturing, the capture will be disabled automatically. - * - * While capturing is enabled, the current window will have the - * SDL_WINDOW_MOUSE_CAPTURE flag set. - * - * \return 0 on success, or -1 if not supported. - *} - function SDL_CaptureMouse(enabled: TSDL_Bool): cint32; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CaptureMouse' {$ENDIF}{$ENDIF}; + * Capture the mouse and to track input outside an SDL window. + * + * Capturing enables your app to obtain mouse events globally, instead of just + * within your window. Not all video targets support this function. When + * capturing is enabled, the current window will get all mouse events, but + * unlike relative mode, no change is made to the cursor and it is not + * restrained to your window. + * + * This function may also deny mouse input to other windows--both those in + * your application and others on the system--so you should use this function + * sparingly, and in small bursts. For example, you might want to track the + * mouse while the user is dragging something, until the user releases a mouse + * button. It is not recommended that you capture the mouse for long periods + * of time, such as the entire time your app is running. For that, you should + * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending + * on your goals. + * + * While captured, mouse events still report coordinates relative to the + * current (foreground) window, but those coordinates may be outside the + * bounds of the window (including negative values). Capturing is only allowed + * for the foreground window. If the window loses focus while capturing, the + * capture will be disabled automatically. + * + * While capturing is enabled, the current window will have the + * `SDL_WINDOW_MOUSE_CAPTURE` flag set. + * + * Please note that as of SDL 2.0.22, SDL will attempt to "auto capture" the + * mouse while the user is pressing a button; this is to try and make mouse + * behavior more consistent between platforms, and deal with the common case + * of a user dragging the mouse outside of the window. This means that if you + * are calling SDL_CaptureMouse() only to deal with this situation, you no + * longer have to (although it is safe to do so). If this causes problems for + * your app, you can disable auto capture by setting the + * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. + * + * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. + * \returns 0 on success or -1 if not supported; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_GetGlobalMouseState + *} + function SDL_CaptureMouse(enabled: TSDL_Bool): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CaptureMouse' {$ENDIF}{$ENDIF}; {** - * Query whether relative mouse mode is enabled. - * - * SDL_SetRelativeMouseMode() - *} - - function SDL_GetRelativeMouseMode: TSDL_Bool cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRelativeMouseMode' {$ENDIF}{$ENDIF}; + * Query whether relative mouse mode is enabled. + * + * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetRelativeMouseMode + *} +function SDL_GetRelativeMouseMode: TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRelativeMouseMode' {$ENDIF}{$ENDIF}; {** - * Create a cursor, using the specified bitmap data and - * mask (in MSB format). - * - * The cursor width must be a multiple of 8 bits. - * - * The cursor is created in black and white according to the following: - * - * - * - * - * - * - *
data mask resulting pixel on screen
0 1 White
1 1 Black
0 0 Transparent
1 0 Inverted color if possible, black - * if not.
- * - * SDL_FreeCursor() - *} - - function SDL_CreateCursor(const data: pcuint8; const mask: pcuint8; w: cint32; h: cint32; hot_x: cint32; hot_y: cint32): PSDL_Cursor cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateCursor' {$ENDIF}{$ENDIF}; + * Create a cursor using the specified bitmap data and mask (in MSB format). + * + * `mask` has to be in MSB (Most Significant Bit) format. + * + * The cursor width (`w`) must be a multiple of 8 bits. + * + * The cursor is created in black and white according to the following: + * + * - data=0, mask=1: white + * - data=1, mask=1: black + * - data=0, mask=0: transparent + * - data=1, mask=0: inverted color if possible, black if not. + * + * Cursors created with this function must be freed with SDL_FreeCursor(). + * + * If you want to have a color cursor, or create your cursor from an + * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can + * hide the cursor and draw your own as part of your game's rendering, but it + * will be bound to the framerate. + * + * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which + * provides twelve readily available system cursors to pick from. + * + * \param data the color value for each pixel of the cursor + * \param mask the mask value for each pixel of the cursor + * \param w the width of the cursor + * \param h the height of the cursor + * \param hot_x the X-axis location of the upper left corner of the cursor + * relative to the actual mouse position + * \param hot_y the Y-axis location of the upper left corner of the cursor + * relative to the actual mouse position + * \returns a new cursor with the specified parameters on success or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_FreeCursor + * \sa SDL_SetCursor + * \sa SDL_ShowCursor + *} +function SDL_CreateCursor( + const data: pcuint8; + const mask: pcuint8; + w: cint; h: cint; + hot_x: cint; hot_y: cint): PSDL_Cursor; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateCursor' {$ENDIF}{$ENDIF}; {** - * Create a color cursor. - * - * SDL_FreeCursor() - *} - - function SDL_CreateColorCursor(surface: PSDL_Surface; hot_x: cint32; hot_y: cint32): PSDL_Cursor cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateColorCursor' {$ENDIF}{$ENDIF}; + * Create a color cursor. + * + * \param surface an SDL_Surface structure representing the cursor image + * \param hot_x the x position of the cursor hot spot + * \param hot_y the y position of the cursor hot spot + * \returns the new cursor on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateCursor + * \sa SDL_FreeCursor + *} +function SDL_CreateColorCursor( + surface: PSDL_Surface; + hot_x: cint; + hot_y: cint): PSDL_Cursor; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateColorCursor' {$ENDIF}{$ENDIF}; {** - * Create a system cursor. - * - * SDL_FreeCursor() - *} - - function SDL_CreateSystemCursor(id: TSDL_SystemCursor): PSDL_Cursor cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateSystemCursor' {$ENDIF}{$ENDIF}; + * Create a system cursor. + * + * \param id an SDL_SystemCursor enum value + * \returns a cursor on success or NULL on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_FreeCursor + *} +function SDL_CreateSystemCursor(id: TSDL_SystemCursor): PSDL_Cursor; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateSystemCursor' {$ENDIF}{$ENDIF}; {** - * Set the active cursor. - *} - - procedure SDL_SetCursor(cursor: PSDL_Cursor) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetCursor' {$ENDIF}{$ENDIF}; + * Set the active cursor. + * + * This function sets the currently active cursor to the specified one. If the + * cursor is currently visible, the change will be immediately represented on + * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if + * this is desired for any reason. + * + * \param cursor a cursor to make active + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateCursor + * \sa SDL_GetCursor + * \sa SDL_ShowCursor + *} +procedure SDL_SetCursor(cursor: PSDL_Cursor); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetCursor' {$ENDIF}{$ENDIF}; {** - * Return the active cursor. - *} - - function SDL_GetCursor: PSDL_Cursor cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCursor' {$ENDIF}{$ENDIF}; + * Get the active cursor. + * + * This function returns a pointer to the current cursor which is owned by the + * library. It is not necessary to free the cursor with SDL_FreeCursor(). + * + * \returns the active cursor or NULL if there is no mouse. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetCursor + *} +function SDL_GetCursor: PSDL_Cursor; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCursor' {$ENDIF}{$ENDIF}; {** - * Return the default cursor. - *} - - function SDL_GetDefaultCursor: PSDL_Cursor cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDefaultCursor' {$ENDIF}{$ENDIF}; + * Get the default cursor. + * + * \returns the default cursor on success or NULL on failure. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateSystemCursor + *} +function SDL_GetDefaultCursor: PSDL_Cursor; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDefaultCursor' {$ENDIF}{$ENDIF}; {** - * Frees a cursor created with SDL_CreateCursor(). - * - * SDL_CreateCursor() - *} - - procedure SDL_FreeCursor(cursor: PSDL_Cursor) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeCursor' {$ENDIF}{$ENDIF}; + * Free a previously-created cursor. + * + * Use this function to free cursor resources created with SDL_CreateCursor(), + * SDL_CreateColorCursor() or SDL_CreateSystemCursor(). + * + * \param cursor the cursor to free + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateColorCursor + * \sa SDL_CreateCursor + * \sa SDL_CreateSystemCursor + *} +procedure SDL_FreeCursor(cursor: PSDL_Cursor); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeCursor' {$ENDIF}{$ENDIF}; {** - * Toggle whether or not the cursor is shown. - * - * toggle 1 to show the cursor, 0 to hide it, -1 to query the current - * state. - * - * 1 if the cursor is shown, or 0 if the cursor is hidden. - *} - - function SDL_ShowCursor(toggle: cint32): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowCursor' {$ENDIF}{$ENDIF}; - - function SDL_Button(button: cint32): cint32; {$IFNDEF DELPHI} inline; {$ELSE} {$IFDEF DELPHI10UP} inline; {$ENDIF} {$ENDIF} + * Toggle whether or not the cursor is shown. + * + * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE` + * displays the cursor and passing `SDL_DISABLE` hides it. + * + * The current state of the mouse cursor can be queried by passing + * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned. + * + * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it, + * `SDL_QUERY` to query the current state without changing it. + * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the + * cursor is hidden, or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateCursor + * \sa SDL_SetCursor + *} +function SDL_ShowCursor(toggle: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowCursor' {$ENDIF}{$ENDIF}; +{** + * Used as a mask when testing buttons in buttonstate. + * - Button 1: Left mouse button + * - Button 2: Middle mouse button + * - Button 3: Right mouse button + *} +function SDL_Button(X: cint): cint; {$IFNDEF DELPHI} inline; {$ELSE} {$IFDEF DELPHI10UP} inline; {$ENDIF} {$ENDIF} const - {** - * Used as a mask when testing buttons in buttonstate. - * - Button 1: Left mouse button - * - Button 2: Middle mouse button - * - Button 3: Right mouse button - *} - - SDL_BUTTON_LEFT = 1; - SDL_BUTTON_MIDDLE = 2; - SDL_BUTTON_RIGHT = 3; + SDL_BUTTON_LEFT = 1; + SDL_BUTTON_MIDDLE = 2; + SDL_BUTTON_RIGHT = 3; SDL_BUTTON_X1 = 4; SDL_BUTTON_X2 = 5; + { Pascal Conv.: For better performance instead of using the + SDL_Button(X) macro, the following defines are + implemented directly. } SDL_BUTTON_LMASK = 1 shl ((SDL_BUTTON_LEFT) - 1); SDL_BUTTON_MMASK = 1 shl ((SDL_BUTTON_MIDDLE) - 1); SDL_BUTTON_RMASK = 1 shl ((SDL_BUTTON_RIGHT) - 1); diff --git a/units/sdlmutex.inc b/units/sdlmutex.inc index 9c5da530..2da3af87 100644 --- a/units/sdlmutex.inc +++ b/units/sdlmutex.inc @@ -1,142 +1,244 @@ -// based on "sdl_mutex.h" (2.0.14) -{ TODO : Add type definitions (see todos below). } +// based on "sdl_mutex.h" +const {** * Synchronization functions which can time out return this value * if they time out. *} -const SDL_MUTEX_TIMEDOUT = 1; {** * This is the timeout value which corresponds to never time out. *} - //SDL_MUTEX_MAXWAIT (~(Uint32)0) + SDL_MUTEX_MAXWAIT = Not cuint32(0); - - {** - * Mutex functions - *} + { -- Mutex functions -- } type - {*The SDL mutex structure, defined in SDL_sysmutex.c *} - PSDL_Mutex = Pointer; //todo! + { The SDL mutex structure, defined in SDL_sysmutex.c } + PPSDL_Mutex = ^PSDL_Mutex; + PSDL_Mutex = Type Pointer; - {** - * Create a mutex, initialized unlocked. - *} +{** + * Create a new mutex. + * + * All newly-created mutexes begin in the _unlocked_ state. + * + * Calls to SDL_LockMutex() will not return while the mutex is locked by + * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. + * + * SDL mutexes are reentrant. + * + * \returns the initialized and unlocked mutex or NIL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CreateMutex: PSDL_Mutex; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateMutex' {$ENDIF} {$ENDIF}; - {** - * Lock the mutex. - * - * 0, or -1 on error. - *} -//#define SDL_mutexP(m) SDL_LockMutex(m) +{** + * Lock the mutex. + * + * This will block until the mutex is available, which is to say it is in the + * unlocked state and the OS has chosen the caller as the next thread to lock + * it. Of all threads waiting to lock the mutex, only one may do so at a time. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * \param mutex the mutex to lock + * \return 0, or -1 on error. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_LockMutex(mutex: PSDL_Mutex): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockMutex' {$ENDIF} {$ENDIF}; - {** - * Try to lock the mutex - * - * 0, SDL_MUTEX_TIMEDOUT, or -1 on error - *} +{ SDL2-for-Pascal: SDL_mutexP macro ignored; no benefit for the Pascal units } +//C: #define SDL_mutexP(m) SDL_UnlockMutex(m) + +{** + * Try to lock a mutex without blocking. + * + * This works just like SDL_LockMutex(), but if the mutex is not available, + * this function returns SDL_MUTEX_TIMEDOUT immediately. + * + * This technique is useful if you need exclusive access to a resource but + * don't want to wait for it, and will return to it to try again later. + * + * \param mutex the mutex to try to lock + * \returns 0, SDL_MUTEX_TIMEDOUT, or -1 on error; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_TryLockMutex(mutex: PSDL_Mutex): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TryLockMutex' {$ENDIF} {$ENDIF}; - {** - * Unlock the mutex. - * - * 0, or -1 on error. - * - * It is an error to unlock a mutex that has not been locked by - * the current thread, and doing so results in undefined behavior. - *} -//#define SDL_mutexV(m) SDL_UnlockMutex(m) +{** + * Unlock the mutex. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * It is an error to unlock a mutex that has not been locked by the current + * thread, and doing so results in undefined behavior. + * + * It is also an error to unlock a mutex that isn't locked at all. + * + * \param mutex the mutex to unlock. + * \returns 0, or -1 on error. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_UnlockMutex(mutex: PSDL_Mutex): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockMutex' {$ENDIF} {$ENDIF}; - {** - * Destroy a mutex. - *} +{ SDL2-for-Pascal: SDL_mutexV macro ignored; no benefit for the Pascal units } +//C: #define SDL_mutexV(m) SDL_UnlockMutex(m) + +{** + * Destroy a mutex created with SDL_CreateMutex(). + * + * This function must be called on any mutex that is no longer needed. Failure + * to destroy a mutex will result in a system memory or resource leak. While + * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt + * to destroy a locked mutex, and may result in undefined behavior depending + * on the platform. + * + * \param mutex the mutex to destroy + * + * \since This function is available since SDL 2.0.0. + *} procedure SDL_DestroyMutex(mutex: PSDL_Mutex); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyMutex' {$ENDIF} {$ENDIF}; - {*Mutex functions*} - - {** - * Semaphore functions - *} + { -- Semaphore functions -- } type - {* The SDL semaphore structure, defined in SDL_sem.c *} - PSDL_Sem = Pointer; //todo! + { The SDL semaphore structure, defined in SDL_sem.c } + PPSDL_Sem = ^PSDL_Sem; + PSDL_Sem = Type Pointer; - {** - * Create a semaphore, initialized with value, returns NULL on failure. - *} +{** + * Create a semaphore. + * + * This function creates a new semaphore and initializes it with the provided + * initial value. Each wait operation on the semaphore will atomically + * decrement the semaphore value and potentially block if the semaphore value + * is 0. Each post operation will atomically increment the semaphore value and + * wake waiting threads and allow them to retry the wait operation. + * + * \param initial_value the starting value of the semaphore + * \returns a new semaphore or NIL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CreateSemaphore(initial_value: cuint32): PSDL_sem; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateSemaphore' {$ENDIF} {$ENDIF}; - {** - * Destroy a semaphore. - *} +{** + * Destroy a semaphore. + * + * It is not safe to destroy a semaphore if there are threads currently + * waiting on it. + * + * \param sem the semaphore to destroy + * + * \since This function is available since SDL 2.0.0. + *} procedure SDL_DestroySemaphore(sem: PSDL_Sem); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroySemaphore' {$ENDIF} {$ENDIF}; - {** - * This function suspends the calling thread until the semaphore pointed - * to by sem has a positive count. It then atomically decreases the - * semaphore count. - *} +{** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until either the semaphore + * pointed to by `sem` has a positive value or the call is interrupted by a + * signal or error. If the call is successful it will atomically decrement the + * semaphore value. + * + * This function is the equivalent of calling SDL_SemWaitTimeout() with a time + * length of SDL_MUTEX_MAXWAIT. + * + * \param sem the semaphore wait on + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_SemWait(sem: PSDL_Sem): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SemWait' {$ENDIF} {$ENDIF}; - {** - * Non-blocking variant of SDL_SemWait(). - * - * 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would - * block, and -1 on error. - *} +{** + * See if a semaphore has a positive value and decrement it if it does. + * + * This function checks to see if the semaphore pointed to by `sem` has a + * positive value and atomically decrements the semaphore value if it does. If + * the semaphore doesn't have a positive value, the function immediately + * returns SDL_MUTEX_TIMEDOUT. + * + * \param sem the semaphore to wait on + * \returns 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would + * block, or a negative error code on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_SemTryWait(sem: PSDL_Sem): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SemTryWait' {$ENDIF} {$ENDIF}; - {** - * Variant of SDL_SemWait() with a timeout in milliseconds. - * - * 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not - * succeed in the allotted time, and -1 on error. - * - * On some platforms this function is implemented by looping with a - * delay of 1 ms, and so should be avoided if possible. - *} +{** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until either the semaphore + * pointed to by `sem` has a positive value, the call is interrupted by a + * signal or error, or the specified time has elapsed. If the call is + * successful it will atomically decrement the semaphore value. + * + * \param sem the semaphore to wait on + * \param ms the length of the timeout, in milliseconds + * \returns 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not + * succeed in the allotted time, or a negative error code on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_SemWaitTimeout(sem: PSDL_Sem; ms: cuint32): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SemWaitTimeout' {$ENDIF} {$ENDIF}; - {** - * Atomically increases the semaphore'_S count (not blocking). - * - * 0, or -1 on error. - *} +{** + * Atomically increment a semaphore's value and wake waiting threads. + * + * \param sem the semaphore to increment + * \returns 0 on success or a negative error code on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_SemPost(sem: PSDL_Sem): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SemPost' {$ENDIF} {$ENDIF}; - {** - * Returns the current count of the semaphore. - *} +{** + * Get the current value of a semaphore. + * + * \param sem the semaphore to query + * \returns the current value of the semaphore. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_SemValue(sem: PSDL_Sem): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SemValue' {$ENDIF} {$ENDIF}; - {*Semaphore functions*} - - {** - * Condition variable functions - * } + { -- Condition variable functions -- } type - {* The SDL condition variable structure, defined in SDL_cond.c *} - PSDL_Cond = Pointer; //todo!! + { The SDL condition variable structure, defined in SDL_cond.c } + PPSDL_Cond = ^PSDL_Cond; {** - * Create a condition variable. + * The condition variable type. * * Typical use of condition variables: * @@ -161,53 +263,99 @@ type * benefit to unlocking first on some platforms, but there are some * potential race conditions depending on how your code is structured. * - * In general it'_S safer to signal the condition variable while the + * In general it's safer to signal the condition variable while the * mutex is locked. *} + PSDL_Cond = Type Pointer; + +{** + * Create a condition variable. + * + * \returns a new condition variable or NIL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CreateCond: PSDL_Cond; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateCond' {$ENDIF} {$ENDIF}; - {** - * Destroy a condition variable. - *} +{** + * Destroy a condition variable. + * + * \param cond the condition variable to destroy + * + * \since This function is available since SDL 2.0.0. + *} procedure SDL_DestroyCond(cond: PSDL_Cond); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyCond' {$ENDIF} {$ENDIF}; - {** - * Restart one of the threads that are waiting on the condition variable. - * - * 0 or -1 on error. - *} +{** + * Restart one of the threads that are waiting on the condition variable. + * + * \param cond the condition variable to signal + * \returns 0 on success or a negative error code on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CondSignal(cond: PSDL_Cond): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CondSignal' {$ENDIF} {$ENDIF}; - {** - * Restart all threads that are waiting on the condition variable. - * - * 0 or -1 on error. - *} +{** + * Restart all threads that are waiting on the condition variable. + * + * \param cond the condition variable to signal + * \returns 0 on success or a negative error code on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CondBroadcast(cond: PSDL_Cond): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CondBroadcast' {$ENDIF} {$ENDIF}; - {** - * Wait on the condition variable, unlocking the provided mutex. - * - * The mutex must be locked before entering this function! - * - * The mutex is re-locked once the condition variable is signaled. - * - * 0 when it is signaled, or -1 on error. - *} +{** + * Wait until a condition variable is signaled. + * + * This function unlocks the specified `mutex` and waits for another thread to + * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable + * `cond`. Once the condition variable is signaled, the mutex is re-locked and + * the function returns. + * + * The mutex must be locked before calling this function. + * + * This function is the equivalent of calling SDL_CondWaitTimeout() with a + * time length of SDL_MUTEX_MAXWAIT. + * + * \param cond the condition variable to wait on + * \param mutex the mutex used to coordinate thread access + * \returns 0 when it is signaled or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CondWait(cond: PSDL_Cond; mutex: PSDL_Mutex): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CondWait' {$ENDIF} {$ENDIF}; - {** - * Waits for at most ms milliseconds, and returns 0 if the condition - * variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not - * signaled in the allotted time, and -1 on error. - * - * On some platforms this function is implemented by looping with a - * delay of 1 ms, and so should be avoided if possible. - *} +{** + * Wait until a condition variable is signaled or a certain time has passed. + * + * This function unlocks the specified `mutex` and waits for another thread to + * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable + * `cond`, or for the specified time to elapse. Once the condition variable is + * signaled or the time elapsed, the mutex is re-locked and the function + * returns. + * + * The mutex must be locked before calling this function. + * + * \param cond the condition variable to wait on + * \param mutex the mutex used to coordinate thread access + * \param ms the maximum time to wait, in milliseconds, or SDL_MUTEX_MAXWAIT + * to wait indefinitely + * \returns 0 if the condition variable is signaled, SDL_MUTEX_TIMEDOUT if + * the condition is not signaled in the allotted time, or a negative + * error code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} function SDL_CondWaitTimeout(cond: PSDL_Cond; mutex: PSDL_Mutex; ms: cuint32): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CondWaitTimeout' {$ENDIF} {$ENDIF}; diff --git a/units/sdlpixels.inc b/units/sdlpixels.inc index 2fef1ac7..bf3b1f2c 100644 --- a/units/sdlpixels.inc +++ b/units/sdlpixels.inc @@ -18,7 +18,9 @@ const {** Pixel type. *} type - TSDL_PixelType = type Cardinal; + PPSDL_PixelType = ^PSDL_PixelType; + PSDL_PixelType = ^TSDL_PixelType; + TSDL_PixelType = type cuint; const SDL_PIXELTYPE_UNKNOWN = TSDL_PixelType(0); @@ -36,7 +38,9 @@ const {** Bitmap pixel order, high bit -> low bit. *} type - TSDL_BitmapOrder = type Cardinal; + PPSDL_BitmapOrder = ^PSDL_BitmapOrder; + PSDL_BitmapOrder = ^TSDL_BitmapOrder; + TSDL_BitmapOrder = type cuint32; const SDL_BITMAPORDER_NONE = TSDL_BitmapOrder(0); @@ -45,7 +49,9 @@ const {** Packed component order, high bit -> low bit. *} type - TSDL_PackOrder = type Cardinal; + PPSDL_PackOrder = ^PSDL_PackOrder; + PSDL_PackOrder = ^TSDL_PackOrder; + TSDL_PackOrder = type cuint32; const SDL_PACKEDORDER_NONE = TSDL_PackOrder(0); @@ -60,7 +66,9 @@ const {** Array component order, low byte -> high byte. *} type - TSDL_ArrayOrder = type Cardinal; + PPSDL_ArrayOrder = ^PSDL_ArrayOrder; + PSDL_ArrayOrder = ^TSDL_ArrayOrder; + TSDL_ArrayOrder = type cuint32; const SDL_ARRAYORDER_NONE = TSDL_ArrayOrder(0); @@ -73,7 +81,9 @@ const {** Packed component layout. *} type - TSDL_PackedLayout = type Cardinal; + PPSDL_PackedLayout = ^PSDL_PackedLayout; + PSDL_PackedLayout = ^TSDL_PackedLayout; + TSDL_PackedLayout = type cuint32; const SDL_PACKEDLAYOUT_NONE = TSDL_PackedLayout(0); @@ -86,23 +96,67 @@ const SDL_PACKEDLAYOUT_2101010 = TSDL_PackedLayout(7); SDL_PACKEDLAYOUT_1010102 = TSDL_PackedLayout(8); - { - //todo!! -function SDL_DEFINE_PIXELFORMAT(type, order, layour, bit, bytes: cuint32): Result; +{ +SDL2-for-Pascal: The SDL_DEFINE_PIXELFOURCC macro is replaced + by another macro, the SDL_FOURCC macro (in SDL_stdinc.h). + + The original C SDL_FOURCC macro: + #define SDL_FOURCC(A, B, C, D) \ + ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24)) + + In Pascal it is cleaner to implement this directly as a + constant instead of a function. So we do, e. g.: + + SDL_PIXELFORMAT_YV12 = (cuint32('Y') ) or + (cuint32('V') shl 8) or + (cuint32('1') shl 16) or + (cuint32('2') shl 24); + + In the future it may be desirable to have a Pascal function. + The prototype could look like this: + function SDL_DEFINE_PIXELFOURCC(A,B,C,D: Variant): Variant; +} + +{ +SDL2-for-Pascal: The SDL_DEFINE_PIXELFORMAT macro returns the underlying + pixel format based on five arguments. + + The original C macro: + #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ + ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ + ((bits) << 8) | ((bytes) << 0)) + + This C implementation could be replaced by a Pascal function, + but from a performance stand point this will be slower. + Therefore we decided to keep it as it has been implemented + before by the original binding authors and translate + every pixel format constant by the very same expression: + + SDL_PIXELFORMAT_[...] = (1 shl 28) or + (SDL_PIXELTYPE_[...] shl 24) or + (SDL_BITMAPORDER_[...] shl 20) or + ([...] shl 16) or + ([...] shl 8) or + ([...] shl 0); + + In the future it may be desirable to have a Pascal function. + The prototype could look like this: + function SDL_DEFINE_PIXELFORMAT(type, order, layour, bit, bytes: cuint32): Result; +} + +function SDL_PIXELFLAG(X: cuint32): cuint32; +function SDL_PIXELTYPE(X: cuint32): cuint32; +function SDL_PIXELORDER(X: cuint32): cuint32; +function SDL_PIXELLAYOUT(X: cuint32): cuint32; +function SDL_BITSPERPIXEL(X: cuint32): cuint32; + +{ +SDL2-for-Pascal: Is it worth translating these macros as they seem to be used + by SDL2 internally only? -function SDL_DEFINE_PIXELFOURCC(A,B,C,D: Variant): Variant; - -#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ - ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ - ((bits) << 8) | ((bytes) << 0)) - } - -function SDL_PIXELFLAG(X: Cardinal): Cardinal; -function SDL_PIXELTYPE(X: Cardinal): Cardinal; -function SDL_PIXELORDER(X: Cardinal): Cardinal; -function SDL_PIXELLAYOUT(X: Cardinal): Cardinal; -function SDL_BITSPERPIXEL(X: Cardinal): Cardinal; - { #define SDL_BYTESPERPIXEL(X) \ (SDL_ISPIXELFORMAT_FOURCC(X) ? \ ((((X) == SDL_PIXELFORMAT_YUY2) || \ @@ -140,12 +194,11 @@ function SDL_BITSPERPIXEL(X: Cardinal): Cardinal; (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) - } +} {* The flag is set to 1 because 0x1? is not in the printable ASCII range *} function SDL_ISPIXELFORMAT_FOURCC(format: Variant): Boolean; - { TODO : Use SDL_DEFINE_FORMAT macro? Examine results in detail. } {* Note: If you modify this list, update SDL_GetPixelFormatName() *} const SDL_PIXELFORMAT_UNKNOWN = 0; @@ -377,48 +430,55 @@ const {$ENDIF} {**< Planar mode: Y + V + U (3 planes) *} - SDL_PIXELFORMAT_YV12 = (cint('Y') ) or - (cint('V') shl 8) or - (cint('1') shl 16) or - (cint('2') shl 24); + SDL_PIXELFORMAT_YV12 = (cuint32('Y') ) or + (cuint32('V') shl 8) or + (cuint32('1') shl 16) or + (cuint32('2') shl 24); {**< Planar mode: Y + U + V (3 planes) *} - SDL_PIXELFORMAT_IYUV = (cint('I') ) or - (cint('Y') shl 8) or - (cint('U') shl 16) or - (cint('V') shl 24); + SDL_PIXELFORMAT_IYUV = (cuint32('I') ) or + (cuint32('Y') shl 8) or + (cuint32('U') shl 16) or + (cuint32('V') shl 24); {**< Packed mode: Y0+U0+Y1+V0 (1 plane) *} - SDL_PIXELFORMAT_YUY2 = (cint('Y') ) or - (cint('U') shl 8) or - (cint('Y') shl 16) or - (cint('2') shl 24); + SDL_PIXELFORMAT_YUY2 = (cuint32('Y') ) or + (cuint32('U') shl 8) or + (cuint32('Y') shl 16) or + (cuint32('2') shl 24); {**< Packed mode: U0+Y0+V0+Y1 (1 plane) *} - SDL_PIXELFORMAT_UYVY = (cint('U') ) or - (cint('Y') shl 8) or - (cint('V') shl 16) or - (cint('Y') shl 24); + SDL_PIXELFORMAT_UYVY = (cuint32('U') ) or + (cuint32('Y') shl 8) or + (cuint32('V') shl 16) or + (cuint32('Y') shl 24); {**< Packed mode: Y0+V0+Y1+U0 (1 plane) *} - SDL_PIXELFORMAT_YVYU = (cint('Y') ) or - (cint('V') shl 8) or - (cint('Y') shl 16) or - (cint('U') shl 24); + SDL_PIXELFORMAT_YVYU = (cuint32('Y') ) or + (cuint32('V') shl 8) or + (cuint32('Y') shl 16) or + (cuint32('U') shl 24); {**< Planar mode: Y + U/V interleaved (2 planes) *} - SDL_PIXELFORMAT_NV12 = (cint('N') ) or - (cint('V') shl 8) or - (cint('1') shl 16) or - (cint('2') shl 24); + SDL_PIXELFORMAT_NV12 = (cuint32('N') ) or + (cuint32('V') shl 8) or + (cuint32('1') shl 16) or + (cuint32('2') shl 24); {**< Planar mode: Y + V/U interleaved (2 planes) *} - SDL_PIXELFORMAT_NV21 = (cint('N') ) or - (cint('V') shl 8) or - (cint('2') shl 16) or - (cint('1') shl 24); + SDL_PIXELFORMAT_NV21 = (cuint32('N') ) or + (cuint32('V') shl 8) or + (cuint32('2') shl 16) or + (cuint32('1') shl 24); {**< Android video texture format *} SDL_PIXELFORMAT_EXTERMAL_OES - = (cint('O') ) or - (cint('E') shl 8) or - (cint('S') shl 16) or - (cint(' ') shl 24); + = (cuint32('O') ) or + (cuint32('E') shl 8) or + (cuint32('S') shl 16) or + (cuint32(' ') shl 24); type + + {** + * The bits of this structure can be directly reinterpreted as an integer-packed + * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 + * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems). + *} + PPSDL_Color = ^PSDL_Color; PSDL_Color = ^TSDL_Color; TSDL_Color = record r: cuint8; @@ -427,9 +487,11 @@ type a: cuint8; end; - TSDL_Colour = TSDL_Color; + PPSDL_Colour = ^PSDL_Colour; PSDL_Colour = ^TSDL_Colour; + TSDL_Colour = TSDL_Color; + PPSDL_Palette = ^PSDL_Palette; PSDL_Palette = ^TSDL_Palette; TSDL_Palette = record ncolors: cint; @@ -441,7 +503,7 @@ type {** * Everything in the pixel format structure is read-only. *} - + PPSDL_PixelFormat = ^PSDL_PixelFormat; PSDL_PixelFormat = ^TSDL_PixelFormat; TSDL_PixelFormat = record format: cuint32; @@ -466,119 +528,279 @@ type end; {** - * Get the human readable name of a pixel format + * Get the human readable name of a pixel format. + * + * \param format the pixel format to query + * \returns the human readable name of the specified pixel format or + * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized. + * + * \since This function is available since SDL 2.0.0. *} function SDL_GetPixelFormatName(format: cuint32): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPixelFormatName' {$ENDIF} {$ENDIF}; {** - * Convert one of the enumerated pixel formats to a bpp and RGBA masks. + * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. * - * SDL_TRUE, or SDL_FALSE if the conversion wasn't possible. + * \param format one of the SDL_PixelFormatEnum values + * \param bpp a bits per pixel value; usually 15, 16, or 32 + * \param Rmask a pointer filled in with the red mask for the format + * \param Gmask a pointer filled in with the green mask for the format + * \param Bmask a pointer filled in with the blue mask for the format + * \param Amask a pointer filled in with the alpha mask for the format + * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't + * possible; call SDL_GetError() for more information. * - * SDL_MasksToPixelFormatEnum() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_MasksToPixelFormatEnum *} function SDL_PixelFormatEnumToMasks(format: cuint32; bpp: pcint; Rmask: pcuint32; Gmask: pcuint32; Bmask: pcuint32; Amask: pcuint32): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PixelFormatEnumToMasks' {$ENDIF} {$ENDIF}; {** - * Convert a bpp and RGBA masks to an enumerated pixel format. + * Convert a bpp value and RGBA masks to an enumerated pixel format. + * + * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't + * possible. + * + * \param bpp a bits per pixel value; usually 15, 16, or 32 + * \param Rmask the red mask for the format + * \param Gmask the green mask for the format + * \param Bmask the blue mask for the format + * \param Amask the alpha mask for the format + * \returns one of the SDL_PixelFormatEnum values * - * The pixel format, or SDL_PIXELFORMAT_UNKNOWN if the conversion - * wasn't possible. + * \since This function is available since SDL 2.0.0. * - * SDL_PixelFormatEnumToMasks() + * \sa SDL_PixelFormatEnumToMasks *} function SDL_MasksToPixelFormatEnum(bpp: cint; Rmask: cuint32; Gmask: cuint32; Bmask: cuint32; Amask: cuint32): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MasksToPixelFormatEnum' {$ENDIF} {$ENDIF}; {** - * Create an SDL_PixelFormat structure from a pixel format enum. + * Create an SDL_PixelFormat structure corresponding to a pixel format. + * + * Returned structure may come from a shared global cache (i.e. not newly + * allocated), and hence should not be modified, especially the palette. Weird + * errors such as `Blit combination not supported` may occur. + * + * \param pixel_format one of the SDL_PixelFormatEnum values + * \returns the new SDL_PixelFormat structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_FreeFormat *} function SDL_AllocFormat(pixel_format: cuint32): PSDL_PixelFormat; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AllocFormat' {$ENDIF} {$ENDIF}; {** - * Free an SDL_PixelFormat structure. + * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). + * + * \param format the SDL_PixelFormat structure to free + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AllocFormat *} procedure SDL_FreeFormat(format: PSDL_PixelFormat); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreeFormat' {$ENDIF} {$ENDIF}; {** - * Create a palette structure with the specified number of color - * entries. + * Create a palette structure with the specified number of color entries. + * + * The palette entries are initialized to white. * - * A new palette, or nil if there wasn't enough memory. + * \param ncolors represents the number of color entries in the color palette + * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if + * there wasn't enough memory); call SDL_GetError() for more + * information. * - * The palette entries are initialized to white. + * \since This function is available since SDL 2.0.0. * - * SDL_FreePalette() + * \sa SDL_FreePalette *} function SDL_AllocPalette(ncolors: cint): PSDL_Palette; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AllocPalette' {$ENDIF} {$ENDIF}; {** - * Set the palette for a pixel format structure. + * Set the palette for a pixel format structure. + * + * \param format the SDL_PixelFormat structure that will use the palette + * \param palette the SDL_Palette structure that will be used + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AllocPalette + * \sa SDL_FreePalette *} function SDL_SetPixelFormatPalette(format: PSDL_PixelFormat; palette: PSDL_Palette): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetPixelFormatPalette' {$ENDIF} {$ENDIF}; {** - * Set a range of colors in a palette. + * Set a range of colors in a palette. + * + * \param palette the SDL_Palette structure to modify + * \param colors an array of SDL_Color structures to copy into the palette + * \param firstcolor the index of the first palette entry to modify + * \param ncolors the number of entries to modify + * \returns 0 on success or a negative error code if not all of the colors + * could be set; call SDL_GetError() for more information. * - * palette The palette to modify. - * colors An array of colors to copy into the palette. - * firstcolor The index of the first palette entry to modify. - * ncolors The number of entries to modify. + * \since This function is available since SDL 2.0.0. * - * 0 on success, or -1 if not all of the colors could be set. + * \sa SDL_AllocPalette + * \sa SDL_CreateRGBSurface *} function SDL_SetPaletteColors(palette: PSDL_Palette; const colors: PSDL_Color; firstcolor: cint; ncolors: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetPaletteColors' {$ENDIF} {$ENDIF}; {** - * Free a palette created with SDL_AllocPalette(). + * Free a palette created with SDL_AllocPalette(). * - * SDL_AllocPalette() + * \param palette the SDL_Palette structure to be freed + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AllocPalette *} procedure SDL_FreePalette(palette: PSDL_Palette); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FreePalette' {$ENDIF} {$ENDIF}; {** - * Maps an RGB triple to an opaque pixel value for a given pixel format. + * Map an RGB triple to an opaque pixel value for a given pixel format. + * + * This function maps the RGB color value to the specified pixel format and + * returns the pixel value best approximating the given RGB color value for + * the given pixel format. + * + * If the format has a palette (8-bit) the index of the closest matching color + * in the palette will be returned. + * + * If the specified pixel format has an alpha component it will be returned as + * all 1 bits (fully opaque). + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param format an SDL_PixelFormat structure describing the pixel format + * \param r the red component of the pixel in the range 0-255 + * \param g the green component of the pixel in the range 0-255 + * \param b the blue component of the pixel in the range 0-255 + * \returns a pixel value * - * SDL_MapRGBA + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetRGB + * \sa SDL_GetRGBA + * \sa SDL_MapRGBA *} function SDL_MapRGB(const format: PSDL_PixelFormat; r: cuint8; g: cuint8; b: cuint8): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MapRGB' {$ENDIF} {$ENDIF}; {** - * Maps an RGBA quadruple to a pixel value for a given pixel format. + * Map an RGBA quadruple to a pixel value for a given pixel format. + * + * This function maps the RGBA color value to the specified pixel format and + * returns the pixel value best approximating the given RGBA color value for + * the given pixel format. + * + * If the specified pixel format has no alpha component the alpha value will + * be ignored (as it will be in formats with a palette). + * + * If the format has a palette (8-bit) the index of the closest matching color + * in the palette will be returned. + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param format an SDL_PixelFormat structure describing the format of the + * pixel + * \param r the red component of the pixel in the range 0-255 + * \param g the green component of the pixel in the range 0-255 + * \param b the blue component of the pixel in the range 0-255 + * \param a the alpha component of the pixel in the range 0-255 + * \returns a pixel value * - * SDL_MapRGB + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetRGB + * \sa SDL_GetRGBA + * \sa SDL_MapRGB *} function SDL_MapRGBA(const format: PSDL_PixelFormat; r: cuint8; g: cuint8; b: cuint8; a: cuint8): cuint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MapRGBA' {$ENDIF} {$ENDIF}; {** - * Get the RGB components from a pixel of the specified format. + * Get RGB values from a pixel in the specified format. + * + * This function uses the entire 8-bit [0..255] range when converting color + * components from pixel formats with less than 8-bits per RGB component + * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, + * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). + * + * \param pixel a pixel value + * \param format an SDL_PixelFormat structure describing the format of the + * pixel + * \param r a pointer filled in with the red component + * \param g a pointer filled in with the green component + * \param b a pointer filled in with the blue component * - * SDL_GetRGBA + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetRGBA + * \sa SDL_MapRGB + * \sa SDL_MapRGBA *} procedure SDL_GetRGB(pixel: cuint32; const format: PSDL_PixelFormat; r: pcuint8; g: pcuint8; b: pcuint8); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRGB' {$ENDIF} {$ENDIF}; {** - * Get the RGBA components from a pixel of the specified format. + * Get RGBA values from a pixel in the specified format. + * + * This function uses the entire 8-bit [0..255] range when converting color + * components from pixel formats with less than 8-bits per RGB component + * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, + * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). + * + * If the surface has no alpha component, the alpha will be returned as 0xff + * (100% opaque). * - * SDL_GetRGB + * \param pixel a pixel value + * \param format an SDL_PixelFormat structure describing the format of the + * pixel + * \param r a pointer filled in with the red component + * \param g a pointer filled in with the green component + * \param b a pointer filled in with the blue component + * \param a a pointer filled in with the alpha component + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetRGB + * \sa SDL_MapRGB + * \sa SDL_MapRGBA *} procedure SDL_GetRGBA(pixel: cuint32; const format: PSDL_PixelFormat; r: pcuint8; g: pcuint8; b: pcuint8; a: pcuint8); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRGBA' {$ENDIF} {$ENDIF}; -{** - * Calculate a 256 entry gamma ramp for a gamma value. +{/** + * Calculate a 256 entry gamma ramp for a gamma value. + * + * \param gamma a gamma value where 0.0 is black and 1.0 is identity + * \param ramp an array of 256 values filled in with the gamma ramp + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetWindowGammaRamp *} procedure SDL_CalculateGammaRamp(gamma: cfloat; ramp: pcuint16); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CalculateGammaRamp' {$ENDIF} {$ENDIF}; diff --git a/units/sdlpower.inc b/units/sdlpower.inc index 406816fc..54d8e6f9 100644 --- a/units/sdlpower.inc +++ b/units/sdlpower.inc @@ -10,6 +10,8 @@ * The basic state for the system's power supply. *} type + PPSDL_PowerState = ^PSDL_PowerState; + PSDL_PowerState = ^TSDL_PowerState; TSDL_PowerState = (SDL_POWERSTATE_UNKNOWN, {**< cannot determine power status *} SDL_POWERSTATE_ON_BATTERY, {**< Not plugged in, running on the battery *} SDL_POWERSTATE_NO_BATTERY, {**< Plugged in, no battery available *} diff --git a/units/sdlrect.inc b/units/sdlrect.inc index b30968a2..fabde395 100644 --- a/units/sdlrect.inc +++ b/units/sdlrect.inc @@ -1,4 +1,4 @@ -//based on "sdl_rect.h" (2.0.14) +// based on "sdl_rect.h" (2.24.0) {** * \file SDL_rect.h @@ -13,6 +13,7 @@ type * \sa SDL_EnclosePoints * \sa SDL_PointInRect *} + PPSDL_Point = ^PSDL_Point; PSDL_Point = ^TSDL_Point; TSDL_Point = record x: cint; @@ -25,6 +26,7 @@ type * \sa SDL_EnclosePoints * \sa SDL_PointInRect *} + PPSDL_FPoint = ^PSDL_FPoint; PSDL_FPoint = ^TSDL_FPoint; TSDL_FPoint = record x: cfloat; @@ -41,6 +43,7 @@ type * \sa SDL_UnionRect * \sa SDL_EnclosePoints *} + PPSDL_Rect = ^PSDL_Rect; PSDL_Rect = ^TSDL_Rect; TSDL_Rect = record x,y: cint; @@ -50,6 +53,7 @@ type {** * A rectangle, with the origin at the upper left. (floating point) *} + PPSDL_FRect = ^PSDL_FRect; PSDL_FRect = ^TSDL_FRect; TSDL_FRect = record x,y: cfloat; @@ -57,16 +61,13 @@ type end; {** - * \brief Returns true if point resides inside a rectangle. + * Returns true if point resides inside a rectangle. *} function SDL_PointInRect(const p: PSDL_Point; const r: PSDL_Rect): Boolean; Inline; {** * Returns true if the rectangle has no area. *} - -//changed from variant(b�����h!) to TSDL_Rect -//maybe PSDL_Rect? function SDL_RectEmpty(const r: PSDL_Rect): Boolean; inline; {** @@ -111,3 +112,117 @@ function SDL_EnclosePoints(const points: PSDL_Point; count: cint; const clip: PS *} function SDL_IntersectRectAndLine(const rect: PSDL_Rect; X1, Y1, X2, Y2: pcint): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IntersectRectAndLine' {$ENDIF} {$ENDIF}; + +{** + * Returns true if point resides inside a rectangle. + *} +function SDL_PointInFRect(const p: PSDL_FPoint; const r: PSDL_FRect): Boolean; Inline; + +{** + * Returns true if the rectangle has no area. + *} +function SDL_FRectEmpty(const r: PSDL_FRect): Boolean; inline; + +{** + * Returns true if the two rectangles are equal, within some given epsilon. + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_FRectEqualsEpsilon(const a, b: PSDL_FRect; const epsilon: cfloat): Boolean; Inline; + +{** + * Returns true if the two rectangles are equal, using a default epsilon. + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_FRectEquals(const a, b: PSDL_FRect): Boolean; Inline; + +{** + * Determine whether two rectangles intersect with float precision. + * + * If either pointer is NIL the function will return SDL_FALSE. + * + * \param A an SDL_FRect structure representing the first rectangle + * \param B an SDL_FRect structure representing the second rectangle + * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.22. + * + * \sa SDL_IntersectRect + *} +function SDL_HasIntersectionF(const a, b: PSDL_FRect): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasIntersectionF' {$ENDIF} {$ENDIF}; + +{** + * Calculate the intersection of two rectangles with float precision. + * + * If `result` is NIL then this function will return SDL_FALSE. + * + * \param A an SDL_FRect structure representing the first rectangle + * \param B an SDL_FRect structure representing the second rectangle + * \param result an SDL_FRect structure filled in with the intersection of + * rectangles `A` and `B` + * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.22. + * + * \sa SDL_HasIntersectionF + *} +function SDL_IntersectFRect(const a, b: PSDL_FRect; result: PSDL_FRect): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IntersectFRect' {$ENDIF} {$ENDIF}; + +{** + * Calculate the union of two rectangles with float precision. + * + * \param A an SDL_FRect structure representing the first rectangle + * \param B an SDL_FRect structure representing the second rectangle + * \param result an SDL_FRect structure filled in with the union of rectangles + * `A` and `B` + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_UnionFRect(const a, b: PSDL_FRect; result: PSDL_FRect): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnionFRect' {$ENDIF} {$ENDIF}; + +{** + * Calculate a minimal rectangle enclosing a set of points with float + * precision. + * + * If `clip` is not NIL then only points inside of the clipping rectangle + * are considered. + * + * \param points an array of SDL_FPoint structures representing points to be + * enclosed + * \param count the number of structures in the `points` array + * \param clip an SDL_FRect used for clipping or NIL to enclose all points + * \param result an SDL_FRect structure filled in with the minimal enclosing + * rectangle + * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the + * points were outside of the clipping rectangle. + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_EncloseFPoints(const points: PSDL_FPoint; count: cint; const clip: PSDL_FRect; result: PSDL_FRect): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EncloseFPoints' {$ENDIF} {$ENDIF}; + +{** + * Calculate the intersection of a rectangle and line segment with float + * precision. + * + * This function is used to clip a line segment to a rectangle. A line segment + * contained entirely within the rectangle or that does not intersect will + * remain unchanged. A line segment that crosses the rectangle at either or + * both ends will be clipped to the boundary of the rectangle and the new + * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. + * + * \param rect an SDL_FRect structure representing the rectangle to intersect + * \param X1 a pointer to the starting X-coordinate of the line + * \param Y1 a pointer to the starting Y-coordinate of the line + * \param X2 a pointer to the ending X-coordinate of the line + * \param Y2 a pointer to the ending Y-coordinate of the line + * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_IntersectFRectAndLine(const rect: PSDL_FRect; X1, Y1, X2, Y2: pcfloat): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IntersectFRectAndLine' {$ENDIF} {$ENDIF}; diff --git a/units/sdlrenderer.inc b/units/sdlrenderer.inc index 360c6bc5..afc8e201 100644 --- a/units/sdlrenderer.inc +++ b/units/sdlrenderer.inc @@ -13,12 +13,14 @@ const rendering to texture *} type + PPSDL_RendererFlags = ^PSDL_RendererFlags; PSDL_RendererFlags = ^TSDL_RendererFlags; TSDL_RendererFlags = Word; {** * Information on the capabilities of a render driver or context. *} + PPSDL_RendererInfo = ^PSDL_RendererInfo; PSDL_RendererInfo = ^TSDL_RendererInfo; TSDL_RendererInfo = record name: PAnsiChar; {**< The name of the renderer *} @@ -29,12 +31,33 @@ type max_texture_height: cint32; {**< The maximimum texture height *} end; + PPSDL_Vertex = ^PSDL_Vertex; + PSDL_Vertex = ^TSDL_Vertex; + TSDL_Vertex = record + position: TSDL_FPoint; + color: TSDL_Color; + tex_coord: TSDL_FPoint; + end; + +{** + * The scaling mode for a texture. + *} + PPSDL_ScaleMode = ^PSDL_ScaleMode; + PSDL_ScaleMode = ^TSDL_ScaleMode; + TSDL_ScaleMode = type cint; + +const + SDL_ScaleModeNearest = TSDL_ScaleMode(0); {**< nearest pixel sampling *} + SDL_ScaleModeLinear = TSDL_ScaleMode(1); {**< linear filtering *} + SDL_ScaleModeBest = TSDL_ScaleMode(2); {**< anisotropic filtering *} + {** * The access pattern allowed for a texture. *} type + PPSDL_TextureAccess = ^PSDL_TextureAccess; PSDL_TextureAccess = ^TSDL_TextureAccess; - TSDL_TextureAccess = cint32; + TSDL_TextureAccess = type cint; const SDL_TEXTUREACCESS_STATIC = 0; {**< Changes rarely, not lockable *} @@ -45,20 +68,27 @@ type {** * The texture channel modulation used in SDL_RenderCopy(). *} + PPSDL_TextureModulate = ^PSDL_TextureModulate; PSDL_TextureModulate = ^TSDL_TextureModulate; - TSDL_TextureModulate = ( - SDL_TEXTUREMODULATE_NONE, {**< No modulation *} - SDL_TEXTUREMODULATE_COLOR, {**< srcC = srcC * color *} - SDL_TEXTUREMODULATE_ALPHA {**< srcA = srcA * alpha *} - ); + TSDL_TextureModulate = type cint; + +const + SDL_TEXTUREMODULATE_NONE = TSDL_TextureModulate(0); {**< No modulation *} + SDL_TEXTUREMODULATE_COLOR = TSDL_TextureModulate(1); {**< srcC = srcC * color *} + SDL_TEXTUREMODULATE_ALPHA = TSDL_TextureModulate(2); {**< srcA = srcA * alpha *} +type {** * Flip constants for SDL_RenderCopyEx *} + PPSDL_RenderFlip = ^PSDL_RenderFlip; + PSDL_RenderFlip = ^TSDL_RenderFlip; + TSDL_RenderFlip = type cint; + const - SDL_FLIP_NONE = $0; {**< Do not flip *} - SDL_FLIP_HORIZONTAL = $1; {**< flip horizontally *} - SDL_FLIP_VERTICAL = $2; {**< flip vertically *} + SDL_FLIP_NONE = TSDL_RenderFlip($0); {**< Do not flip *} + SDL_FLIP_HORIZONTAL = TSDL_RenderFlip($1); {**< flip horizontally *} + SDL_FLIP_VERTICAL = TSDL_RenderFlip($2); {**< flip vertically *} type {** @@ -66,16 +96,13 @@ type *} PPSDL_Renderer = ^PSDL_Renderer; - PSDL_Renderer = ^TSDL_Renderer; - TSDL_Renderer = record - end; + PSDL_Renderer = type Pointer; {** * An efficient driver-specific representation of pixel data *} - PSDL_Texture = ^TSDL_Texture; - TSDL_Texture = record - end; + PPSDL_Texture = ^PSDL_Texture; + PSDL_Texture = type Pointer; {* Function prototypes *} @@ -152,6 +179,12 @@ function SDL_CreateSoftwareRenderer(surface: PSDL_Surface): PSDL_Renderer cdecl; *} function SDL_GetRenderer(window: PSDL_Window): PSDL_Renderer cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRenderer' {$ENDIF} {$ENDIF}; +{** + * Get the window associated with a renderer. + *} +function SDL_RenderGetWindow(renderer: PSDL_Renderer): PSDL_Window; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGetWindow' {$ENDIF} {$ENDIF}; + {** * Get information about a rendering context. *} @@ -293,6 +326,31 @@ function SDL_SetTextureBlendMode(texture: PSDL_Texture; blendMode: TSDL_BlendMod *} function SDL_GetTextureBlendMode(texture: PSDL_Texture; blendMode: PSDL_BlendMode): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTextureBlendMode' {$ENDIF} {$ENDIF}; +{** + * Set the scale mode used for texture scale operations. + * If the scale mode is not supported, the closest supported mode is chosen. + *} +function SDL_SetTextureScaleMode(texture: PSDL_Texture; scaleMode: TSDL_ScaleMode): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetTextureScaleMode' {$ENDIF} {$ENDIF}; + +{** + * Get the scale mode used for texture scale operations. + *} +function SDL_GetTextureScaleMode(texture: PSDL_Texture; scaleMode: PSDL_ScaleMode): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTextureScaleMode' {$ENDIF} {$ENDIF}; + +{** + * Associate a user-specified pointer with a texture. + *} +function SDL_SetTextureUserData(texture: PSDL_Texture; userdata: Pointer): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetTextureUserData' {$ENDIF} {$ENDIF}; + +{** + * Get the user-specified pointer associated with a texture. + *} +function SDL_GetTextureUserData(texture: PSDL_Texture): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTextureUserData' {$ENDIF} {$ENDIF}; + {** * Update the given texture rectangle with new pixel data. * @@ -529,6 +587,22 @@ function SDL_RenderSetScale(renderer: PSDL_Renderer; scaleX: cfloat; scaleY: cfl *} procedure SDL_RenderGetScale(renderer: PSDL_Renderer; scaleX: pcfloat; scaleY: pcfloat) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGetScale' {$ENDIF} {$ENDIF}; +{** + * 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. + *} +procedure SDL_RenderWindowToLogical(renderer: PSDL_Renderer; windowX, windowY: cint; logicalX, logicalY: PSingle); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderWindowToLogical' {$ENDIF} {$ENDIF}; + +{** + * Get real coordinates of point in window when given logical coordinates of + * point in renderer. Logical coordinates will differ from real coordinate + * when render is scaled and logical renderer size set. + *} +procedure SDL_RenderLogicalToWindow(renderer: PSDL_Renderer; logicalX, logicalY: Single; windowX, windowY: Pcint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderLogicalToWindow' {$ENDIF} {$ENDIF}; + {** * Set the color used for drawing operations (Rect, Line and Clear). * @@ -820,7 +894,7 @@ function SDL_RenderCopyF(renderer: PSDL_Renderer; texture: PSDL_Texture; srcrect * * 0 on success, or -1 on error *} -function SDL_RenderCopyEx(renderer: PSDL_Renderer; texture: PSDL_Texture; const srcrect: PSDL_Rect; dstrect: PSDL_Rect; angle: Double; center: PSDL_Point; flip: cint): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderCopyEx' {$ENDIF} {$ENDIF}; +function SDL_RenderCopyEx(renderer: PSDL_Renderer; texture: PSDL_Texture; const srcrect: PSDL_Rect; dstrect: PSDL_Rect; angle: cdouble; center: PSDL_Point; flip: TSDL_RenderFlip): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderCopyEx' {$ENDIF} {$ENDIF}; {** * Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center @@ -835,9 +909,38 @@ function SDL_RenderCopyEx(renderer: PSDL_Renderer; texture: PSDL_Texture; const * * 0 on success, or -1 on error *} -function SDL_RenderCopyExF(renderer: PSDL_Renderer; texture: PSDL_Texture; const srcrect: PSDL_Rect; dstrect: PSDL_FRect; angle: Double; center: PSDL_FPoint; flip: cint): cint32 cdecl; +function SDL_RenderCopyExF(renderer: PSDL_Renderer; texture: PSDL_Texture; const srcrect: PSDL_Rect; dstrect: PSDL_FRect; angle: cdouble; center: PSDL_FPoint; flip: TSDL_RenderFlip): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderCopyExF' {$ENDIF} {$ENDIF}; +{** + * Render a list of triangles, optionally using a texture and indices into the + * vertex array. Color and alpha modulation is done per vertex. + * SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored. + *} +function SDL_RenderGeometry( + renderer: PSDL_Renderer; + texture: PSDL_Texture; + Const vertices: PSDL_Vertex; num_vertices: cint; + Const indices: Pcint; num_indices: cint +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGeometry' {$ENDIF} {$ENDIF}; + +{** + * Render a list of triangles, optionally using a texture and indices into the + * vertex arrays. Color and alpha modulation is done per vertex. + * SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored. + *} +function SDL_RenderGeometryRaw( + renderer: PSDL_Renderer; + texture: PSDL_Texture; + Const xy: PSingle; xy_stride: cint; + Const color: PSDL_Color; color_stride: cint; + Const uv: PSingle; uv_stride: cint; + num_vertices: cint; + Const indices: Pointer; num_indices, size_indices: cint +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGeometryRaw' {$ENDIF} {$ENDIF}; + {** * Read pixels from the current rendering target. * @@ -876,6 +979,32 @@ procedure SDL_DestroyTexture(texture: PSDL_Texture) cdecl; external SDL_LibName *} procedure SDL_DestroyRenderer(renderer: PSDL_Renderer) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyRenderer' {$ENDIF} {$ENDIF}; +{** + * Force the rendering context to flush any pending commands to the underlying + * rendering API. + * + * You do not need to (and in fact, shouldn't) call this function unless you + * are planning to call into OpenGL/Direct3D/Metal/whatever directly in + * addition to using an SDL_Renderer. + * + * This is for a very-specific case: if you are using SDL's render API, you + * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set + * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever + * calls in addition to SDL render API calls. If all of this applies, you + * should call SDL_RenderFlush() between calls to SDL's render API and the + * low-level API you're using in cooperation. + * + * In all other cases, you can ignore this function. This is only here to get + * maximum performance out of a specific situation. In all other cases, SDL + * will do the right thing, perhaps at a performance loss. + * + * This function is first available in SDL 2.0.10, and is not needed in 2.0.9 + * and earlier, as earlier versions did not queue rendering commands at all, + * instead flushing them to the OS immediately. + *} +function SDL_RenderFlush(renderer: PSDL_Renderer): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderFlush' {$ENDIF} {$ENDIF}; + {** * Bind the texture to the current OpenGL/ES/ES2 context for use with * OpenGL instructions. @@ -897,6 +1026,36 @@ function SDL_GL_BindTexture(texture: PSDL_Texture; texw: pcfloat; texh: pcfloat) *} function SDL_GL_UnbindTexture(texture: PSDL_Texture): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GL_UnbindTexture' {$ENDIF} {$ENDIF}; +{** + * Get the CAMetalLayer associated with the given Metal renderer. + * + * This function returns a raw Pointer, so SDL doesn't have to include Metal's headers, + * but it can be safely cast to a pointer to `CAMetalLayer`. + * + *} +function SDL_RenderGetMetalLayer(renderer: PSDL_Renderer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGetMetalLayer' {$ENDIF} {$ENDIF}; + +{** + * Get the Metal command encoder for the current frame + * + * This function returns a raw Pointer, 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 + * hidden/minimized/offscreen. This doesn't apply to command encoders for + * render targets, just the window's backbacker. Check your return values! + *} +function SDL_RenderGetMetalCommandEncoder(renderer: PSDL_Renderer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderGetMetalCommandEncoder' {$ENDIF} {$ENDIF}; + +{** + * Toggle VSync of the given renderer. + *} +function SDL_RenderSetVSync(renderer: PSDL_Renderer; vsync: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenderSetVSync' {$ENDIF} {$ENDIF}; + {** * Update a rectangle within a planar YV12 or IYUV texture with new pixel data. * @@ -917,3 +1076,18 @@ function SDL_GL_UnbindTexture(texture: PSDL_Texture): cint32 cdecl; external SDL *} function SDL_UpdateYUVTexture(texture: PSDL_Texture; rect: PSDL_Rect; Yplane: pcuint8; Ypitch: cint32; Uplane: pcuint8; UPitch: cint32; Vplane: pcuint8; VPitch: cint32):cint32; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UpdateYUVTexture' {$ENDIF} {$ENDIF}; + +{** + * Update a rectangle within a planar NV12 or NV21 texture with new pixels. + * + * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous + * block of NV12/21 planes in the proper order, but this function is available + * if your pixel data is not contiguous. + *} +function SDL_UpdateNVTexture( + texture: PSDL_Texture; + Const rect: PSDL_Rect; + Const Yplane: Pcuint8; Ypitch: cint; + Const UVplane: Pcuint8; UVpitch: cint +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UpdateNVTexture' {$ENDIF} {$ENDIF}; diff --git a/units/sdlrwops.inc b/units/sdlrwops.inc index 53195c52..e0d844e9 100644 --- a/units/sdlrwops.inc +++ b/units/sdlrwops.inc @@ -17,6 +17,7 @@ const SDL_RWOPS_MEMORY_RO = 5; {* Read-Only memory stream *} type + PPSDL_RWops = ^PSDL_RWops; PSDL_RWops = ^TSDL_RWops; {** diff --git a/units/sdlscancode.inc b/units/sdlscancode.inc index 6f1ea1aa..13aafe9c 100644 --- a/units/sdlscancode.inc +++ b/units/sdlscancode.inc @@ -8,11 +8,13 @@ * SDL_Event structure. * * The values in this enumeration are based on the USB usage page standard: - * http://www.usb.org/developers/devclass_docs/Hut1_12v2.pdf + * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf *} type + PPSDL_ScanCode = ^PSDL_ScanCode; PSDL_ScanCode = ^TSDL_ScanCode; - TSDL_ScanCode = type DWord; + TSDL_ScanCode = type cint; + const SDL_SCANCODE_UNKNOWN = TSDL_ScanCode(0); @@ -196,16 +198,16 @@ const SDL_SCANCODE_F23 = TSDL_ScanCode(114); SDL_SCANCODE_F24 = TSDL_ScanCode(115); SDL_SCANCODE_EXECUTE = TSDL_ScanCode(116); - SDL_SCANCODE_HELP = TSDL_ScanCode(117); - SDL_SCANCODE_MENU = TSDL_ScanCode(118); + SDL_SCANCODE_HELP = TSDL_ScanCode(117); { AL Integrated Help Center } + SDL_SCANCODE_MENU = TSDL_ScanCode(118); { Menu (show menu) } SDL_SCANCODE_SELECT = TSDL_ScanCode(119); - SDL_SCANCODE_STOP = TSDL_ScanCode(120); - SDL_SCANCODE_AGAIN = TSDL_ScanCode(121); {**< redo *} - SDL_SCANCODE_UNDO = TSDL_ScanCode(122); - SDL_SCANCODE_CUT = TSDL_ScanCode(123); - SDL_SCANCODE_COPY = TSDL_ScanCode(124); - SDL_SCANCODE_PASTE = TSDL_ScanCode(125); - SDL_SCANCODE_FIND = TSDL_ScanCode(126); + SDL_SCANCODE_STOP = TSDL_ScanCode(120); { AC Stop } + SDL_SCANCODE_AGAIN = TSDL_ScanCode(121); { AC Redo/Repeat } + SDL_SCANCODE_UNDO = TSDL_ScanCode(122); { AC Undo } + SDL_SCANCODE_CUT = TSDL_ScanCode(123); { AC Cut } + SDL_SCANCODE_COPY = TSDL_ScanCode(124); { AC Copy } + SDL_SCANCODE_PASTE = TSDL_ScanCode(125); { AC Paste } + SDL_SCANCODE_FIND = TSDL_ScanCode(126); { AC Find } SDL_SCANCODE_MUTE = TSDL_ScanCode(127); SDL_SCANCODE_VOLUMEUP = TSDL_ScanCode(128); SDL_SCANCODE_VOLUMEDOWN = TSDL_ScanCode(129); @@ -216,7 +218,8 @@ const SDL_SCANCODE_KP_COMMA = TSDL_ScanCode(133); SDL_SCANCODE_KP_EQUALSAS400 = TSDL_ScanCode(134); - SDL_SCANCODE_INTERNATIONAL1 = TSDL_ScanCode(135); {**< used on Asian keyboards; see footnotes in USB doc *} + SDL_SCANCODE_INTERNATIONAL1 = TSDL_ScanCode(135); {**< used on Asian keyboards; see + footnotes in USB doc *} SDL_SCANCODE_INTERNATIONAL2 = TSDL_ScanCode(136); SDL_SCANCODE_INTERNATIONAL3 = TSDL_ScanCode(137); {**< Yen *} SDL_SCANCODE_INTERNATIONAL4 = TSDL_ScanCode(138); @@ -225,11 +228,11 @@ const SDL_SCANCODE_INTERNATIONAL7 = TSDL_ScanCode(141); SDL_SCANCODE_INTERNATIONAL8 = TSDL_ScanCode(142); SDL_SCANCODE_INTERNATIONAL9 = TSDL_ScanCode(143); - SDL_SCANCODE_LANG1 = TSDL_ScanCode(144); {**< Hangul{English toggle *} + SDL_SCANCODE_LANG1 = TSDL_ScanCode(144); {**< Hangul/English toggle *} SDL_SCANCODE_LANG2 = TSDL_ScanCode(145); {**< Hanja conversion *} SDL_SCANCODE_LANG3 = TSDL_ScanCode(146); {**< Katakana *} SDL_SCANCODE_LANG4 = TSDL_ScanCode(147); {**< Hiragana *} - SDL_SCANCODE_LANG5 = TSDL_ScanCode(148); {**< Zenkaku{Hankaku *} + SDL_SCANCODE_LANG5 = TSDL_ScanCode(148); {**< Zenkaku/Hankaku *} SDL_SCANCODE_LANG6 = TSDL_ScanCode(149); {**< reserved *} SDL_SCANCODE_LANG7 = TSDL_ScanCode(150); {**< reserved *} SDL_SCANCODE_LANG8 = TSDL_ScanCode(151); {**< reserved *} @@ -237,7 +240,7 @@ const SDL_SCANCODE_ALTERASE = TSDL_ScanCode(153); {**< Erase-Eaze *} SDL_SCANCODE_SYSREQ = TSDL_ScanCode(154); - SDL_SCANCODE_CANCEL = TSDL_ScanCode(155); + SDL_SCANCODE_CANCEL = TSDL_ScanCode(155); { AC Cancel } SDL_SCANCODE_CLEAR = TSDL_ScanCode(156); SDL_SCANCODE_PRIOR = TSDL_ScanCode(157); SDL_SCANCODE_RETURN2 = TSDL_ScanCode(158); @@ -308,13 +311,17 @@ const * by any of the above; but since there's a * special KMOD_MODE for it I'm adding it here *} - - {*Usage page $07*} {** - * Usage page $0C - * - * These values are mapped from usage page $0C (USB consumer page). + * \name Usage page 0x0C + * + * These values are mapped from usage page 0x0C (USB consumer page). + * See https://usb.org/sites/default/files/hut1_2.pdf + * + * There are way more keys in the spec than we can represent in the + * current scancode range, so pick the ones that commonly come up in + * real world usage. + */ These values are mapped from usage page $0C (USB consumer page). *} SDL_SCANCODE_AUDIONEXT = TSDL_ScanCode(258); @@ -335,8 +342,6 @@ const SDL_SCANCODE_AC_REFRESH = TSDL_ScanCode(273); SDL_SCANCODE_AC_BOOKMARKS = TSDL_ScanCode(274); - {*Usage page $0C*} - {** * Walther keys * @@ -345,316 +350,45 @@ const SDL_SCANCODE_BRIGHTNESSDOWN = TSDL_ScanCode(275); SDL_SCANCODE_BRIGHTNESSUP = TSDL_ScanCode(276); - SDL_SCANCODE_DISPLAYSWITCH = TSDL_ScanCode(277); {**< display mirroring{dual display - switch; video mode switch *} + SDL_SCANCODE_DISPLAYSWITCH = TSDL_ScanCode(277); {**< display mirroring/dual display + switch; video mode switch *} SDL_SCANCODE_KBDILLUMTOGGLE = TSDL_ScanCode(278); SDL_SCANCODE_KBDILLUMDOWN = TSDL_ScanCode(279); SDL_SCANCODE_KBDILLUMUP = TSDL_ScanCode(280); SDL_SCANCODE_EJECT = TSDL_ScanCode(281); - SDL_SCANCODE_SLEEP = TSDL_ScanCode(282); + SDL_SCANCODE_SLEEP = TSDL_ScanCode(282); { SC System Sleep } SDL_SCANCODE_APP1 = TSDL_ScanCode(283); SDL_SCANCODE_APP2 = TSDL_ScanCode(284); - {*Walther keys*} - - {* Add any other keys here. *} - - SDL_NUM_SCANCODES = 512; {**< not a key, just marks the number of scancodes - for array bounds *} - - //from "sdl_keycode.h" - {** - * The SDL virtual key representation. + * \name Usage page 0x0C (additional media keys) * - * Values of this type are used to represent keyboard keys using the current - * layout of the keyboard. These values include Unicode values representing - * the unmodified character that would be generated by pressing the key, or - * an SDLK_* constant for those keys that do not generate characters. + * These values are mapped from usage page 0x0C (USB consumer page). *} -type - PSDL_KeyCode = ^TSDL_KeyCode; - TSDL_KeyCode = type cint32; - -const - SDLK_SCANCODE_MASK = 1 shl 30; - SDLK_UNKNOWN = TSDL_KeyCode(0); + SDL_SCANCODE_AUDIOREWIND = TSDL_ScanCode(285); + SDL_SCANCODE_AUDIOFASTFORWARD = TSDL_ScanCode(286); - SDLK_RETURN = TSDL_KeyCode(#13); // C: '\r' - SDLK_ESCAPE = TSDL_KeyCode(#27); // C: '\033' - SDLK_BACKSPACE = TSDL_KeyCode(#8); // C: '\b' - SDLK_TAB = TSDL_KeyCode(#9); // C: '\t' - SDLK_SPACE = TSDL_KeyCode(' '); - SDLK_EXCLAIM = TSDL_KeyCode('!'); - SDLK_QUOTEDBL = TSDL_KeyCode('"'); - SDLK_HASH = TSDL_KeyCode('#'); - SDLK_PERCENT = TSDL_KeyCode('%'); - SDLK_DOLLAR = TSDL_KeyCode('$'); - SDLK_AMPERSAND = TSDL_KeyCode('&'); - SDLK_QUOTE = TSDL_KeyCode('\'); - SDLK_LEFTPAREN = TSDL_KeyCode('('); - SDLK_RIGHTPAREN = TSDL_KeyCode(')'); - SDLK_ASTERISK = TSDL_KeyCode('*'); - SDLK_PLUS = TSDL_KeyCode('+'); - SDLK_COMMA = TSDL_KeyCode(','); - SDLK_MINUS = TSDL_KeyCode('-'); - SDLK_PERIOD = TSDL_KeyCode('.'); - SDLK_SLASH = TSDL_KeyCode('/'); - SDLK_0 = TSDL_KeyCode('0'); - SDLK_1 = TSDL_KeyCode('1'); - SDLK_2 = TSDL_KeyCode('2'); - SDLK_3 = TSDL_KeyCode('3'); - SDLK_4 = TSDL_KeyCode('4'); - SDLK_5 = TSDL_KeyCode('5'); - SDLK_6 = TSDL_KeyCode('6'); - SDLK_7 = TSDL_KeyCode('7'); - SDLK_8 = TSDL_KeyCode('8'); - SDLK_9 = TSDL_KeyCode('9'); - SDLK_COLON = TSDL_KeyCode(':'); - SDLK_SEMICOLON = TSDL_KeyCode(';'); - SDLK_LESS = TSDL_KeyCode('<'); - SDLK_EQUALS = TSDL_KeyCode('='); - SDLK_GREATER = TSDL_KeyCode('>'); - SDLK_QUESTION = TSDL_KeyCode('?'); - SDLK_AT = TSDL_KeyCode('@'); - {* - Skip uppercase letters + {** + * \name Mobile keys + * + * These are values that are often used on mobile phones. *} - SDLK_LEFTBRACKET = TSDL_KeyCode('['); - SDLK_BACKSLASH = TSDL_KeyCode('\'); - SDLK_RIGHTBRACKET = TSDL_KeyCode(']'); - SDLK_CARET = TSDL_KeyCode('^'); - SDLK_UNDERSCORE = TSDL_KeyCode('_'); - SDLK_BACKQUOTE = TSDL_KeyCode('`'); - SDLK_a = TSDL_KeyCode('a'); - SDLK_b = TSDL_KeyCode('b'); - SDLK_c = TSDL_KeyCode('c'); - SDLK_d = TSDL_KeyCode('d'); - SDLK_e = TSDL_KeyCode('e'); - SDLK_f = TSDL_KeyCode('f'); - SDLK_g = TSDL_KeyCode('g'); - SDLK_h = TSDL_KeyCode('h'); - SDLK_i = TSDL_KeyCode('i'); - SDLK_j = TSDL_KeyCode('j'); - SDLK_k = TSDL_KeyCode('k'); - SDLK_l = TSDL_KeyCode('l'); - SDLK_m = TSDL_KeyCode('m'); - SDLK_n = TSDL_KeyCode('n'); - SDLK_o = TSDL_KeyCode('o'); - SDLK_p = TSDL_KeyCode('p'); - SDLK_q = TSDL_KeyCode('q'); - SDLK_r = TSDL_KeyCode('r'); - SDLK_s = TSDL_KeyCode('s'); - SDLK_t = TSDL_KeyCode('t'); - SDLK_u = TSDL_KeyCode('u'); - SDLK_v = TSDL_KeyCode('v'); - SDLK_w = TSDL_KeyCode('w'); - SDLK_x = TSDL_KeyCode('x'); - SDLK_y = TSDL_KeyCode('y'); - SDLK_z = TSDL_KeyCode('z'); - - SDLK_CAPSLOCK = TSDL_KeyCode(SDL_SCANCODE_CAPSLOCK or SDLK_SCANCODE_MASK); - SDLK_F1 = TSDL_KeyCode(SDL_SCANCODE_F1 or SDLK_SCANCODE_MASK); - SDLK_F2 = TSDL_KeyCode(SDL_SCANCODE_F2 or SDLK_SCANCODE_MASK); - SDLK_F3 = TSDL_KeyCode(SDL_SCANCODE_F3 or SDLK_SCANCODE_MASK); - SDLK_F4 = TSDL_KeyCode(SDL_SCANCODE_F4 or SDLK_SCANCODE_MASK); - SDLK_F5 = TSDL_KeyCode(SDL_SCANCODE_F5 or SDLK_SCANCODE_MASK); - SDLK_F6 = TSDL_KeyCode(SDL_SCANCODE_F6 or SDLK_SCANCODE_MASK); - SDLK_F7 = TSDL_KeyCode(SDL_SCANCODE_F7 or SDLK_SCANCODE_MASK); - SDLK_F8 = TSDL_KeyCode(SDL_SCANCODE_F8 or SDLK_SCANCODE_MASK); - SDLK_F9 = TSDL_KeyCode(SDL_SCANCODE_F9 or SDLK_SCANCODE_MASK); - SDLK_F10 = TSDL_KeyCode(SDL_SCANCODE_F10 or SDLK_SCANCODE_MASK); - SDLK_F11 = TSDL_KeyCode(SDL_SCANCODE_F11 or SDLK_SCANCODE_MASK); - SDLK_F12 = TSDL_KeyCode(SDL_SCANCODE_F12 or SDLK_SCANCODE_MASK); + SDL_SCANCODE_SOFTLEFT = TSDL_ScanCode(287); {**< Usually situated below the display on phones and + used as a multi-function feature key for selecting + a software defined function shown on the bottom left + of the display. *} + SDL_SCANCODE_SOFTRIGHT = TSDL_ScanCode(288); {**< Usually situated below the display on phones and + used as a multi-function feature key for selecting + a software defined function shown on the bottom right + of the display. *} + SDL_SCANCODE_CALL = TSDL_ScanCode(289); {**< Used for accepting phone calls. *} + SDL_SCANCODE_ENDCALL = TSDL_ScanCode(290); {**< Used for rejecting phone calls. *} - SDLK_PRINTSCREEN = TSDL_KeyCode(SDL_SCANCODE_PRINTSCREEN or SDLK_SCANCODE_MASK); - SDLK_SCROLLLOCK = TSDL_KeyCode(SDL_SCANCODE_SCROLLLOCK or SDLK_SCANCODE_MASK); - SDLK_PAUSE = TSDL_KeyCode(SDL_SCANCODE_PAUSE or SDLK_SCANCODE_MASK); - SDLK_INSERT = TSDL_KeyCode(SDL_SCANCODE_INSERT or SDLK_SCANCODE_MASK); - SDLK_HOME = TSDL_KeyCode(SDL_SCANCODE_HOME or SDLK_SCANCODE_MASK); - SDLK_PAGEUP = TSDL_KeyCode(SDL_SCANCODE_PAGEUP or SDLK_SCANCODE_MASK); - SDLK_DELETE = TSDL_KeyCode(#127); // C: '\177' - SDLK_END = TSDL_KeyCode(SDL_SCANCODE_END or SDLK_SCANCODE_MASK); - SDLK_PAGEDOWN = TSDL_KeyCode(SDL_SCANCODE_PAGEDOWN or SDLK_SCANCODE_MASK); - SDLK_RIGHT = TSDL_KeyCode(SDL_SCANCODE_RIGHT or SDLK_SCANCODE_MASK); - SDLK_LEFT = TSDL_KeyCode(SDL_SCANCODE_LEFT or SDLK_SCANCODE_MASK); - SDLK_DOWN = TSDL_KeyCode(SDL_SCANCODE_DOWN or SDLK_SCANCODE_MASK); - SDLK_UP = TSDL_KeyCode(SDL_SCANCODE_UP or SDLK_SCANCODE_MASK); - - SDLK_NUMLOCKCLEAR = TSDL_KeyCode(SDL_SCANCODE_NUMLOCKCLEAR or SDLK_SCANCODE_MASK); - SDLK_KP_DIVIDE = TSDL_KeyCode(SDL_SCANCODE_KP_DIVIDE or SDLK_SCANCODE_MASK); - SDLK_KP_MULTIPLY = TSDL_KeyCode(SDL_SCANCODE_KP_MULTIPLY or SDLK_SCANCODE_MASK); - SDLK_KP_MINUS = TSDL_KeyCode(SDL_SCANCODE_KP_MINUS or SDLK_SCANCODE_MASK); - SDLK_KP_PLUS = TSDL_KeyCode(SDL_SCANCODE_KP_PLUS or SDLK_SCANCODE_MASK); - SDLK_KP_ENTER = TSDL_KeyCode(SDL_SCANCODE_KP_ENTER or SDLK_SCANCODE_MASK); - SDLK_KP_1 = TSDL_KeyCode(SDL_SCANCODE_KP_1 or SDLK_SCANCODE_MASK); - SDLK_KP_2 = TSDL_KeyCode(SDL_SCANCODE_KP_2 or SDLK_SCANCODE_MASK); - SDLK_KP_3 = TSDL_KeyCode(SDL_SCANCODE_KP_3 or SDLK_SCANCODE_MASK); - SDLK_KP_4 = TSDL_KeyCode(SDL_SCANCODE_KP_4 or SDLK_SCANCODE_MASK); - SDLK_KP_5 = TSDL_KeyCode(SDL_SCANCODE_KP_5 or SDLK_SCANCODE_MASK); - SDLK_KP_6 = TSDL_KeyCode(SDL_SCANCODE_KP_6 or SDLK_SCANCODE_MASK); - SDLK_KP_7 = TSDL_KeyCode(SDL_SCANCODE_KP_7 or SDLK_SCANCODE_MASK); - SDLK_KP_8 = TSDL_KeyCode(SDL_SCANCODE_KP_8 or SDLK_SCANCODE_MASK); - SDLK_KP_9 = TSDL_KeyCode(SDL_SCANCODE_KP_9 or SDLK_SCANCODE_MASK); - SDLK_KP_0 = TSDL_KeyCode(SDL_SCANCODE_KP_0 or SDLK_SCANCODE_MASK); - SDLK_KP_PERIOD = TSDL_KeyCode(SDL_SCANCODE_KP_PERIOD or SDLK_SCANCODE_MASK); - - SDLK_APPLICATION = TSDL_KeyCode(SDL_SCANCODE_APPLICATION or SDLK_SCANCODE_MASK); - SDLK_POWER = TSDL_KeyCode(SDL_SCANCODE_POWER or SDLK_SCANCODE_MASK); - SDLK_KP_EQUALS = TSDL_KeyCode(SDL_SCANCODE_KP_EQUALS or SDLK_SCANCODE_MASK); - SDLK_F13 = TSDL_KeyCode(SDL_SCANCODE_F13 or SDLK_SCANCODE_MASK); - SDLK_F14 = TSDL_KeyCode(SDL_SCANCODE_F14 or SDLK_SCANCODE_MASK); - SDLK_F15 = TSDL_KeyCode(SDL_SCANCODE_F15 or SDLK_SCANCODE_MASK); - SDLK_F16 = TSDL_KeyCode(SDL_SCANCODE_F16 or SDLK_SCANCODE_MASK); - SDLK_F17 = TSDL_KeyCode(SDL_SCANCODE_F17 or SDLK_SCANCODE_MASK); - SDLK_F18 = TSDL_KeyCode(SDL_SCANCODE_F18 or SDLK_SCANCODE_MASK); - SDLK_F19 = TSDL_KeyCode(SDL_SCANCODE_F19 or SDLK_SCANCODE_MASK); - SDLK_F20 = TSDL_KeyCode(SDL_SCANCODE_F20 or SDLK_SCANCODE_MASK); - SDLK_F21 = TSDL_KeyCode(SDL_SCANCODE_F21 or SDLK_SCANCODE_MASK); - SDLK_F22 = TSDL_KeyCode(SDL_SCANCODE_F22 or SDLK_SCANCODE_MASK); - SDLK_F23 = TSDL_KeyCode(SDL_SCANCODE_F23 or SDLK_SCANCODE_MASK); - SDLK_F24 = TSDL_KeyCode(SDL_SCANCODE_F24 or SDLK_SCANCODE_MASK); - SDLK_EXECUTE = TSDL_KeyCode(SDL_SCANCODE_EXECUTE or SDLK_SCANCODE_MASK); - SDLK_HELP = TSDL_KeyCode(SDL_SCANCODE_HELP or SDLK_SCANCODE_MASK); - SDLK_MENU = TSDL_KeyCode(SDL_SCANCODE_MENU or SDLK_SCANCODE_MASK); - SDLK_SELECT = TSDL_KeyCode(SDL_SCANCODE_SELECT or SDLK_SCANCODE_MASK); - SDLK_STOP = TSDL_KeyCode(SDL_SCANCODE_STOP or SDLK_SCANCODE_MASK); - SDLK_AGAIN = TSDL_KeyCode(SDL_SCANCODE_AGAIN or SDLK_SCANCODE_MASK); - SDLK_UNDO = TSDL_KeyCode(SDL_SCANCODE_UNDO or SDLK_SCANCODE_MASK); - SDLK_CUT = TSDL_KeyCode(SDL_SCANCODE_CUT or SDLK_SCANCODE_MASK); - SDLK_COPY = TSDL_KeyCode(SDL_SCANCODE_COPY or SDLK_SCANCODE_MASK); - SDLK_PASTE = TSDL_KeyCode(SDL_SCANCODE_PASTE or SDLK_SCANCODE_MASK); - SDLK_FIND = TSDL_KeyCode(SDL_SCANCODE_FIND or SDLK_SCANCODE_MASK); - SDLK_MUTE = TSDL_KeyCode(SDL_SCANCODE_MUTE or SDLK_SCANCODE_MASK); - SDLK_VOLUMEUP = TSDL_KeyCode(SDL_SCANCODE_VOLUMEUP or SDLK_SCANCODE_MASK); - SDLK_VOLUMEDOWN = TSDL_KeyCode(SDL_SCANCODE_VOLUMEDOWN or SDLK_SCANCODE_MASK); - SDLK_KP_COMMA = TSDL_KeyCode(SDL_SCANCODE_KP_COMMA or SDLK_SCANCODE_MASK); - SDLK_KP_EQUALSAS400 = TSDL_KeyCode(SDL_SCANCODE_KP_EQUALSAS400 or SDLK_SCANCODE_MASK); - - SDLK_ALTERASE = TSDL_KeyCode(SDL_SCANCODE_ALTERASE or SDLK_SCANCODE_MASK); - SDLK_SYSREQ = TSDL_KeyCode(SDL_SCANCODE_SYSREQ or SDLK_SCANCODE_MASK); - SDLK_CANCEL = TSDL_KeyCode(SDL_SCANCODE_CANCEL or SDLK_SCANCODE_MASK); - SDLK_CLEAR = TSDL_KeyCode(SDL_SCANCODE_CLEAR or SDLK_SCANCODE_MASK); - SDLK_PRIOR = TSDL_KeyCode(SDL_SCANCODE_PRIOR or SDLK_SCANCODE_MASK); - SDLK_RETURN2 = TSDL_KeyCode(SDL_SCANCODE_RETURN2 or SDLK_SCANCODE_MASK); - SDLK_SEPARATOR = TSDL_KeyCode(SDL_SCANCODE_SEPARATOR or SDLK_SCANCODE_MASK); - SDLK_OUT = TSDL_KeyCode(SDL_SCANCODE_OUT or SDLK_SCANCODE_MASK); - SDLK_OPER = TSDL_KeyCode(SDL_SCANCODE_OPER or SDLK_SCANCODE_MASK); - SDLK_CLEARAGAIN = TSDL_KeyCode(SDL_SCANCODE_CLEARAGAIN or SDLK_SCANCODE_MASK); - SDLK_CRSEL = TSDL_KeyCode(SDL_SCANCODE_CRSEL or SDLK_SCANCODE_MASK); - SDLK_EXSEL = TSDL_KeyCode(SDL_SCANCODE_EXSEL or SDLK_SCANCODE_MASK); - - SDLK_KP_00 = TSDL_KeyCode(SDL_SCANCODE_KP_00 or SDLK_SCANCODE_MASK); - SDLK_KP_000 = TSDL_KeyCode(SDL_SCANCODE_KP_000 or SDLK_SCANCODE_MASK); - SDLK_THOUSANDSSEPARATOR = TSDL_KeyCode(SDL_SCANCODE_THOUSANDSSEPARATOR or SDLK_SCANCODE_MASK); - SDLK_DECIMALSEPARATOR = TSDL_KeyCode(SDL_SCANCODE_DECIMALSEPARATOR or SDLK_SCANCODE_MASK); - SDLK_CURRENCYUNIT = TSDL_KeyCode(SDL_SCANCODE_CURRENCYUNIT or SDLK_SCANCODE_MASK); - SDLK_CURRENCYSUBUNIT = TSDL_KeyCode(SDL_SCANCODE_CURRENCYSUBUNIT or SDLK_SCANCODE_MASK); - SDLK_KP_LEFTPAREN = TSDL_KeyCode(SDL_SCANCODE_KP_LEFTPAREN or SDLK_SCANCODE_MASK); - SDLK_KP_RIGHTPAREN = TSDL_KeyCode(SDL_SCANCODE_KP_RIGHTPAREN or SDLK_SCANCODE_MASK); - SDLK_KP_LEFTBRACE = TSDL_KeyCode(SDL_SCANCODE_KP_LEFTBRACE or SDLK_SCANCODE_MASK); - SDLK_KP_RIGHTBRACE = TSDL_KeyCode(SDL_SCANCODE_KP_RIGHTBRACE or SDLK_SCANCODE_MASK); - SDLK_KP_TAB = TSDL_KeyCode(SDL_SCANCODE_KP_TAB or SDLK_SCANCODE_MASK); - SDLK_KP_BACKSPACE = TSDL_KeyCode(SDL_SCANCODE_KP_BACKSPACE or SDLK_SCANCODE_MASK); - SDLK_KP_A = TSDL_KeyCode(SDL_SCANCODE_KP_A or SDLK_SCANCODE_MASK); - SDLK_KP_B = TSDL_KeyCode(SDL_SCANCODE_KP_B or SDLK_SCANCODE_MASK); - SDLK_KP_C = TSDL_KeyCode(SDL_SCANCODE_KP_C or SDLK_SCANCODE_MASK); - SDLK_KP_D = TSDL_KeyCode(SDL_SCANCODE_KP_D or SDLK_SCANCODE_MASK); - SDLK_KP_E = TSDL_KeyCode(SDL_SCANCODE_KP_E or SDLK_SCANCODE_MASK); - SDLK_KP_F = TSDL_KeyCode(SDL_SCANCODE_KP_F or SDLK_SCANCODE_MASK); - SDLK_KP_XOR = TSDL_KeyCode(SDL_SCANCODE_KP_XOR or SDLK_SCANCODE_MASK); - SDLK_KP_POWER = TSDL_KeyCode(SDL_SCANCODE_KP_POWER or SDLK_SCANCODE_MASK); - SDLK_KP_PERCENT = TSDL_KeyCode(SDL_SCANCODE_KP_PERCENT or SDLK_SCANCODE_MASK); - SDLK_KP_LESS = TSDL_KeyCode(SDL_SCANCODE_KP_LESS or SDLK_SCANCODE_MASK); - SDLK_KP_GREATER = TSDL_KeyCode(SDL_SCANCODE_KP_GREATER or SDLK_SCANCODE_MASK); - SDLK_KP_AMPERSAND = TSDL_KeyCode(SDL_SCANCODE_KP_AMPERSAND or SDLK_SCANCODE_MASK); - SDLK_KP_DBLAMPERSAND = TSDL_KeyCode(SDL_SCANCODE_KP_DBLAMPERSAND or SDLK_SCANCODE_MASK); - SDLK_KP_VERTICALBAR = TSDL_KeyCode(SDL_SCANCODE_KP_VERTICALBAR or SDLK_SCANCODE_MASK); - SDLK_KP_DBLVERTICALBAR = TSDL_KeyCode(SDL_SCANCODE_KP_DBLVERTICALBAR or SDLK_SCANCODE_MASK); - SDLK_KP_COLON = TSDL_KeyCode(SDL_SCANCODE_KP_COLON or SDLK_SCANCODE_MASK); - SDLK_KP_HASH = TSDL_KeyCode(SDL_SCANCODE_KP_HASH or SDLK_SCANCODE_MASK); - SDLK_KP_SPACE = TSDL_KeyCode(SDL_SCANCODE_KP_SPACE or SDLK_SCANCODE_MASK); - SDLK_KP_AT = TSDL_KeyCode(SDL_SCANCODE_KP_AT or SDLK_SCANCODE_MASK); - SDLK_KP_EXCLAM = TSDL_KeyCode(SDL_SCANCODE_KP_EXCLAM or SDLK_SCANCODE_MASK); - SDLK_KP_MEMSTORE = TSDL_KeyCode(SDL_SCANCODE_KP_MEMSTORE or SDLK_SCANCODE_MASK); - SDLK_KP_MEMRECALL = TSDL_KeyCode(SDL_SCANCODE_KP_MEMRECALL or SDLK_SCANCODE_MASK); - SDLK_KP_MEMCLEAR = TSDL_KeyCode(SDL_SCANCODE_KP_MEMCLEAR or SDLK_SCANCODE_MASK); - SDLK_KP_MEMADD = TSDL_KeyCode(SDL_SCANCODE_KP_MEMADD or SDLK_SCANCODE_MASK); - SDLK_KP_MEMSUBTRACT = TSDL_KeyCode(SDL_SCANCODE_KP_MEMSUBTRACT or SDLK_SCANCODE_MASK); - SDLK_KP_MEMMULTIPLY = TSDL_KeyCode(SDL_SCANCODE_KP_MEMMULTIPLY or SDLK_SCANCODE_MASK); - SDLK_KP_MEMDIVIDE = TSDL_KeyCode(SDL_SCANCODE_KP_MEMDIVIDE or SDLK_SCANCODE_MASK); - SDLK_KP_PLUSMINUS = TSDL_KeyCode(SDL_SCANCODE_KP_PLUSMINUS or SDLK_SCANCODE_MASK); - SDLK_KP_CLEAR = TSDL_KeyCode(SDL_SCANCODE_KP_CLEAR or SDLK_SCANCODE_MASK); - SDLK_KP_CLEARENTRY = TSDL_KeyCode(SDL_SCANCODE_KP_CLEARENTRY or SDLK_SCANCODE_MASK); - SDLK_KP_BINARY = TSDL_KeyCode(SDL_SCANCODE_KP_BINARY or SDLK_SCANCODE_MASK); - SDLK_KP_OCTAL = TSDL_KeyCode(SDL_SCANCODE_KP_OCTAL or SDLK_SCANCODE_MASK); - SDLK_KP_DECIMAL = TSDL_KeyCode(SDL_SCANCODE_KP_DECIMAL or SDLK_SCANCODE_MASK); - SDLK_KP_HEXADECIMAL = TSDL_KeyCode(SDL_SCANCODE_KP_HEXADECIMAL or SDLK_SCANCODE_MASK); - - SDLK_LCTRL = TSDL_KeyCode(SDL_SCANCODE_LCTRL or SDLK_SCANCODE_MASK); - SDLK_LSHIFT = TSDL_KeyCode(SDL_SCANCODE_LSHIFT or SDLK_SCANCODE_MASK); - SDLK_LALT = TSDL_KeyCode(SDL_SCANCODE_LALT or SDLK_SCANCODE_MASK); - SDLK_LGUI = TSDL_KeyCode(SDL_SCANCODE_LGUI or SDLK_SCANCODE_MASK); - SDLK_RCTRL = TSDL_KeyCode(SDL_SCANCODE_RCTRL or SDLK_SCANCODE_MASK); - SDLK_RSHIFT = TSDL_KeyCode(SDL_SCANCODE_RSHIFT or SDLK_SCANCODE_MASK); - SDLK_RALT = TSDL_KeyCode(SDL_SCANCODE_RALT or SDLK_SCANCODE_MASK); - SDLK_RGUI = TSDL_KeyCode(SDL_SCANCODE_RGUI or SDLK_SCANCODE_MASK); - - SDLK_MODE = TSDL_KeyCode(SDL_SCANCODE_MODE or SDLK_SCANCODE_MASK); - - SDLK_AUDIONEXT = TSDL_KeyCode(SDL_SCANCODE_AUDIONEXT or SDLK_SCANCODE_MASK); - SDLK_AUDIOPREV = TSDL_KeyCode(SDL_SCANCODE_AUDIOPREV or SDLK_SCANCODE_MASK); - SDLK_AUDIOSTOP = TSDL_KeyCode(SDL_SCANCODE_AUDIOSTOP or SDLK_SCANCODE_MASK); - SDLK_AUDIOPLAY = TSDL_KeyCode(SDL_SCANCODE_AUDIOPLAY or SDLK_SCANCODE_MASK); - SDLK_AUDIOMUTE = TSDL_KeyCode(SDL_SCANCODE_AUDIOMUTE or SDLK_SCANCODE_MASK); - SDLK_MEDIASELECT = TSDL_KeyCode(SDL_SCANCODE_MEDIASELECT or SDLK_SCANCODE_MASK); - SDLK_WWW = TSDL_KeyCode(SDL_SCANCODE_WWW or SDLK_SCANCODE_MASK); - SDLK_MAIL = TSDL_KeyCode(SDL_SCANCODE_MAIL or SDLK_SCANCODE_MASK); - SDLK_CALCULATOR = TSDL_KeyCode(SDL_SCANCODE_CALCULATOR or SDLK_SCANCODE_MASK); - SDLK_COMPUTER = TSDL_KeyCode(SDL_SCANCODE_COMPUTER or SDLK_SCANCODE_MASK); - SDLK_AC_SEARCH = TSDL_KeyCode(SDL_SCANCODE_AC_SEARCH or SDLK_SCANCODE_MASK); - SDLK_AC_HOME = TSDL_KeyCode(SDL_SCANCODE_AC_HOME or SDLK_SCANCODE_MASK); - SDLK_AC_BACK = TSDL_KeyCode(SDL_SCANCODE_AC_BACK or SDLK_SCANCODE_MASK); - SDLK_AC_FORWARD = TSDL_KeyCode(SDL_SCANCODE_AC_FORWARD or SDLK_SCANCODE_MASK); - SDLK_AC_STOP = TSDL_KeyCode(SDL_SCANCODE_AC_STOP or SDLK_SCANCODE_MASK); - SDLK_AC_REFRESH = TSDL_KeyCode(SDL_SCANCODE_AC_REFRESH or SDLK_SCANCODE_MASK); - SDLK_AC_BOOKMARKS = TSDL_KeyCode(SDL_SCANCODE_AC_BOOKMARKS or SDLK_SCANCODE_MASK); - - SDLK_BRIGHTNESSDOWN = TSDL_KeyCode(SDL_SCANCODE_BRIGHTNESSDOWN or SDLK_SCANCODE_MASK); - SDLK_BRIGHTNESSUP = TSDL_KeyCode(SDL_SCANCODE_BRIGHTNESSUP or SDLK_SCANCODE_MASK); - SDLK_DISPLAYSWITCH = TSDL_KeyCode(SDL_SCANCODE_DISPLAYSWITCH or SDLK_SCANCODE_MASK); - SDLK_KBDILLUMTOGGLE = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMTOGGLE or SDLK_SCANCODE_MASK); - SDLK_KBDILLUMDOWN = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMDOWN or SDLK_SCANCODE_MASK); - SDLK_KBDILLUMUP = TSDL_KeyCode(SDL_SCANCODE_KBDILLUMUP or SDLK_SCANCODE_MASK); - SDLK_EJECT = TSDL_KeyCode(SDL_SCANCODE_EJECT or SDLK_SCANCODE_MASK); - SDLK_SLEEP = TSDL_KeyCode(SDL_SCANCODE_SLEEP or SDLK_SCANCODE_MASK); - - {** - * Enumeration of valid key mods (possibly OR'd together). - *} -type - PSDL_KeyMod = ^TSDL_KeyMod; - TSDL_KeyMod = type Word; + {* Add any other keys here. *} -const - KMOD_NONE = TSDL_KeyMod($0000); - KMOD_LSHIFT = TSDL_KeyMod($0001); - KMOD_RSHIFT = TSDL_KeyMod($0002); - KMOD_LCTRL = TSDL_KeyMod($0040); - KMOD_RCTRL = TSDL_KeyMod($0080); - KMOD_LALT = TSDL_KeyMod($0100); - KMOD_RALT = TSDL_KeyMod($0200); - KMOD_LGUI = TSDL_KeyMod($0400); - KMOD_RGUI = TSDL_KeyMod($0800); - KMOD_NUM = TSDL_KeyMod($1000); - KMOD_CAPS = TSDL_KeyMod($2000); - KMOD_MODE = TSDL_KeyMod($4000); - KMOD_RESERVED = TSDL_KeyMod($8000); + SDL_NUM_SCANCODES = TSDL_ScanCode(512); {**< not a key, just marks the number of scancodes + for array bounds *} - KMOD_CTRL = KMOD_LCTRL or KMOD_RCTRL; - KMOD_SHIFT = KMOD_LSHIFT or KMOD_RSHIFT; - KMOD_ALT = KMOD_LALT or KMOD_RALT; - KMOD_GUI = KMOD_LGUI or KMOD_RGUI; diff --git a/units/sdlsensor.inc b/units/sdlsensor.inc index 7b5a1a3b..995fa7d1 100644 --- a/units/sdlsensor.inc +++ b/units/sdlsensor.inc @@ -9,8 +9,8 @@ * for sensors, and load appropriate drivers. *} type - TSDL_Sensor = record end; - PSDL_Sensor = ^TSDL_Sensor; + PPSDL_Sensor = ^PSDL_Sensor; + PSDL_Sensor = type Pointer; {** * This is a unique ID for a sensor for the time it is connected to the system, @@ -19,6 +19,8 @@ type * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. *} type + PPSDL_SensorID = ^PSDL_SensorID; + PSDL_SensorID = ^TSDL_SensorID; TSDL_SensorID = type cint32; {** @@ -30,13 +32,19 @@ type * https://developer.android.com/reference/android/hardware/SensorEvent.html#values *} type - TSDL_SensorType = type cint32; + PPSDL_SensorType = ^PSDL_SensorType; + PSDL_SensorType = ^TSDL_SensorType; + TSDL_SensorType = type cint; const SDL_SENSOR_INVALID = TSDL_SensorType(-1); {**< Returned for an invalid sensor *} SDL_SENSOR_UNKNOWN = TSDL_SensorType(0); {**< Unknown sensor type *} SDL_SENSOR_ACCEL = TSDL_SensorType(1); {**< Accelerometer *} SDL_SENSOR_GYRO = TSDL_SensorType(2); {**< Gyroscope *} + SDL_SENSOR_ACCEL_L = TSDL_SensorType(3); {**< Accelerometer for left Joy-Con controller and Wii nunchuk *} + SDL_SENSOR_GYRO_L = TSDL_SensorType(4); {**< Gyroscope for left Joy-Con controller *} + SDL_SENSOR_ACCEL_R = TSDL_SensorType(5); {**< Accelerometer for right Joy-Con controller *} + SDL_SENSOR_GYRO_R = TSDL_SensorType(6); {**< Gyroscope for right Joy-Con controller *} {** * Accelerometer sensor @@ -98,6 +106,8 @@ const * In particular, you are guaranteed that the sensor list won't change, so * the API functions that take a sensor index will be valid, and sensor * events will not be delivered. + * + * \since This function is available since SDL 2.0.14. *} procedure SDL_LockSensors(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockSensors' {$ENDIF} {$ENDIF}; @@ -105,131 +115,181 @@ procedure SDL_UnlockSensors(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockSensors' {$ENDIF} {$ENDIF}; {** - * \brief Count the number of sensors attached to the system right now + * Count the number of sensors attached to the system right now. + * + * \returns the number of sensors detected. + * + * \since This function is available since SDL 2.0.9. *} -function SDL_NumSensors(): cint32; cdecl; +function SDL_NumSensors(): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_NumSensors' {$ENDIF} {$ENDIF}; {** - * \brief Get the implementation dependent name of a sensor. + * Get the implementation dependent name of a sensor. * - * This can be called before any sensors are opened. + * \param device_index The sensor to obtain name from + * \returns the sensor name, or NIL if `device_index` is out of range. * - * \return The sensor name, or NIL if device_index is out of range. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetDeviceName(device_index: cint32): PChar; cdecl; +function SDL_SensorGetDeviceName(device_index: cint): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetDeviceName' {$ENDIF} {$ENDIF}; {** - * \brief Get the type of a sensor. + * Get the type of a sensor. * - * This can be called before any sensors are opened. + * \param device_index The sensor to get the type from + * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is + * out of range. * - * \return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetDeviceType(device_index: cint32): TSDL_SensorType; cdecl; +function SDL_SensorGetDeviceType(device_index: cint): TSDL_SensorType; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetDeviceType' {$ENDIF} {$ENDIF}; {** - * \brief Get the platform dependent type of a sensor. + * Get the platform dependent type of a sensor. * - * This can be called before any sensors are opened. + * \param device_index The sensor to check + * \returns the sensor platform dependent type, or -1 if `device_index` is out + * of range. * - * \return The sensor platform dependent type, or -1 if device_index is out of range. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetDeviceNonPortableType(device_index: cint32): cint32; cdecl; +function SDL_SensorGetDeviceNonPortableType(device_index: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetDeviceNonPortableType' {$ENDIF} {$ENDIF}; {** - * \brief Get the instance ID of a sensor. + * Get the instance ID of a sensor. * - * This can be called before any sensors are opened. + * \param device_index The sensor to get instance id from + * \returns the sensor instance ID, or -1 if `device_index` is out of range. * - * \return The sensor instance ID, or -1 if device_index is out of range. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetDeviceInstanceID(device_index: cint32): TSDL_SensorID; cdecl; +function SDL_SensorGetDeviceInstanceID(device_index: cint): TSDL_SensorID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetDeviceInstanceID' {$ENDIF} {$ENDIF}; {** - * \brief Open a sensor for use. + * Open a sensor for use. * - * The index passed as an argument refers to the N'th sensor on the system. + * \param device_index The sensor to open + * \returns an SDL_Sensor sensor object, or NIL if an error occurred. * - * \return A sensor identifier, or NIL if an error occurred. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorOpen(device_index: cint32): PSDL_Sensor; cdecl; +function SDL_SensorOpen(device_index: cint): PSDL_Sensor; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorOpen' {$ENDIF} {$ENDIF}; {** * Return the SDL_Sensor associated with an instance id. + * + * \param instance_id The sensor from instance id + * \returns an SDL_Sensor object. + * + * \since This function is available since SDL 2.0.9. *} function SDL_SensorFromInstanceID(instance_id: TSDL_SensorID): PSDL_Sensor; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorFromInstanceID' {$ENDIF} {$ENDIF}; {** - * \brief Get the implementation dependent name of a sensor. + * Get the implementation dependent name of a sensor + * + * \param sensor The SDL_Sensor object + * \returns the sensor name, or NIL if `sensor` is NIL. * - * \return The sensor name, or NIL if the sensor is NIL. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetName(sensor: PSDL_Sensor): PChar; cdecl; +function SDL_SensorGetName(sensor: PSDL_Sensor): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetName' {$ENDIF} {$ENDIF}; {** - * \brief Get the type of a sensor. + * Get the type of a sensor. * - * This can be called before any sensors are opened. + * \param sensor The SDL_Sensor object to inspect + * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` + * if `sensor` is NIL. * - * \return The sensor type, or SDL_SENSOR_INVALID if the sensor is NIL. + * \since This function is available since SDL 2.0.9. *} function SDL_SensorGetType(sensor: PSDL_Sensor): TSDL_SensorType; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetType' {$ENDIF} {$ENDIF}; {** - * \brief Get the platform dependent type of a sensor. + * Get the platform dependent type of a sensor. * - * This can be called before any sensors are opened. + * \param sensor The SDL_Sensor object to inspect + * \returns the sensor platform dependent type, or -1 if `sensor` is NIL. * - * \return The sensor platform dependent type, or -1 if the sensor is NIL. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetNonPortableType(sensor: PSDL_Sensor): cint32; cdecl; +function SDL_SensorGetNonPortableType(sensor: PSDL_Sensor): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetNonPortableType' {$ENDIF} {$ENDIF}; {** - * \brief Get the instance ID of a sensor. + * Get the instance ID of a sensor. * - * This can be called before any sensors are opened. + * \param sensor The SDL_Sensor object to inspect + * \returns the sensor instance ID, or -1 if `sensor` is NIL. * - * \return The sensor instance ID, or -1 if the sensor is NIL. + * \since This function is available since SDL 2.0.9. *} function SDL_SensorGetInstanceID(sensor: PSDL_Sensor): TSDL_SensorID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetInstanceID' {$ENDIF} {$ENDIF}; {** - * Get the current state of an opened sensor. + * Get the current state of an opened sensor. * - * The number of values and interpretation of the data is sensor dependent. + * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The sensor to query - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * \param sensor The SDL_Sensor object to query + * \param data A pointer filled with the current sensor state + * \param num_values The number of values to write to data + * \returns 0 or -1 if an error occurred. * - * \return 0 or -1 if an error occurred. + * \since This function is available since SDL 2.0.9. *} -function SDL_SensorGetData(sensor: PSDL_Sensor; data: pcfloat; num_values: cint32): cint32; cdecl; +function SDL_SensorGetData(sensor: PSDL_Sensor; data: pcfloat; num_values: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetData' {$ENDIF} {$ENDIF}; {** - * Close a sensor previously opened with SDL_SensorOpen() + * Get the current state of an opened sensor with the timestamp of the last + * update. + * + * The number of values and interpretation of the data is sensor dependent. + * + * \param sensor The SDL_Sensor object to query + * \param timestamp A pointer filled with the timestamp in microseconds of the + * current sensor reading if available, or 0 if not + * \param data A pointer filled with the current sensor state + * \param num_values The number of values to write to data + * \returns 0 or -1 if an error occurred. + * + * \since This function is available since SDL 2.26.0. + *} +function SDL_SensorGetDataWithTimestamp(sensor: PSDL_Sensor; timestamp: pcuint64; data: pcfloat; num_values: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorGetDataWithTimestamp' {$ENDIF} {$ENDIF}; + +{** + * Close a sensor previously opened with SDL_SensorOpen(). + * + * \param sensor The SDL_Sensor object to close + * + * \since This function is available since SDL 2.0.9. *} procedure SDL_SensorClose(sensor: PSDL_Sensor); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorClose' {$ENDIF} {$ENDIF}; {** - * Update the current state of the open sensors. + * Update the current state of the open sensors. + * + * This is called automatically by the event loop if sensor events are + * enabled. * - * This is called automatically by the event loop if sensor events are enabled. + * This needs to be called from the thread that initialized the sensor + * subsystem. * - * This needs to be called from the thread that initialized the sensor subsystem. + * \since This function is available since SDL 2.0.9. *} procedure SDL_SensorUpdate(); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SensorUpdate' {$ENDIF} {$ENDIF}; diff --git a/units/sdlshape.inc b/units/sdlshape.inc index 49172472..56f6826c 100644 --- a/units/sdlshape.inc +++ b/units/sdlshape.inc @@ -1,4 +1,4 @@ -//from "sdl_shape.h" +// from "sdl_shape.h" {** SDL_shape.h * @@ -9,21 +9,52 @@ const SDL_INVALID_SHAPE_ARGUMENT = -2; SDL_WINDOW_LACKS_SHAPE = -3; - { Conv.: - - ATTENTION: A few function delcarations are missing here. - They would need forward declaration. +{** + * Create a window that can be shaped with the specified position, dimensions, + * and flags. + * + * \param title The title of the window, in UTF-8 encoding. + * \param x The x position of the window, SDL_WINDOWPOS_CENTERED, + * or SDL_WINDOWPOS_UNDEFINED. + * \param y The y position of the window, SDL_WINDOWPOS_CENTERED, + * or SDL_WINDOWPOS_UNDEFINED. + * \param w The width of the window. + * \param h The height of the window. + * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with + * any of the following: SDL_WINDOW_OPENGL, + * SDL_WINDOW_INPUT_GRABBED, SDL_WINDOW_HIDDEN, + * SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, + * SDL_WINDOW_MINIMIZED. + * SDL_WINDOW_BORDERLESS is always set, + * and SDL_WINDOW_FULLSCREEN is always unset. + * \return the window created, or NIL if window creation failed. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_DestroyWindow + *} +function SDL_CreateShapedWindow(title: PAnsiChar; x: cuint; y: cuint; w: cuint; h: cuint; flags: cuint32): PSDL_Window; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateShapedWindow' {$ENDIF} {$ENDIF}; - They are found in sdlvideo.inc! +{** + * Return whether the given window is a shaped window. + * + * \param window The window to query for being shaped. + * \return SDL_TRUE if the window is a window that can be shaped, + * SDL_FALSE if the window is unshaped or NIL. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateShapedWindow + *} +function SDL_IsShapedWindow(window: PSDL_Window): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsShapedWindow' {$ENDIF} {$ENDIF}; - - SDL_CreateShapedWindow - - SDL_IsShapedWindow - - SDL_GetShapedWindow - - SDL_SetShapedWindow - } -{** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. *} type + {** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. *} + PPWindowShapeMode = ^PWindowShapeMode; + PWindowShapeMode = ^TWindowShapeMode; TWindowShapeMode = type Integer; const @@ -36,12 +67,12 @@ const {** \brief A color key is applied. *} ShapeModeColorKey = TWindowShapeMode(3); -{ #todo : Conv.: Macro interpreted correctly? - //#define SDL_SHAPEMODEALPHA(mode) (mode == ShapeModeDefault || mode == ShapeModeBinarizeAlpha || mode == ShapeModeReverseBinarizeAlpha)} function SDL_SHAPEMODEALPHA(mode: TWindowShapeMode): Boolean; type {** A union containing parameters for shaped windows. *} + PPSDL_WindowShapeParams = ^PSDL_WindowShapeParams; + PSDL_WindowShapeParams = ^TSDL_WindowShapeParams; TSDL_WindowShapeParams = record case cint of {** a cutoff alpha value for binarization of the window shape's alpha channel. *} @@ -50,6 +81,7 @@ type end; {** A struct that tags the SDL_WindowShapeParams union with an enum describing the type of its contents. *} + PPSDL_WindowShapeMode = ^PSDL_WindowShapeMode; PSDL_WindowShapeMode = ^TSDL_WindowShapeMode; TSDL_WindowShapeMode = record {** The mode of these window-shape parameters. *} @@ -57,3 +89,41 @@ type {** Window-shape parameters. *} parameters: TSDL_WindowShapeParams; end; + +{** + * Set the shape and parameters of a shaped window. + * + * \param window The shaped window whose parameters should be set. + * \param shape A surface encoding the desired shape for the window. + * \param shape_mode The parameters to set for the shaped window. + * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape + * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does + * not reference a valid shaped window. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_WindowShapeMode + * \sa SDL_GetShapedWindowMode + *} +function SDL_SetWindowShape(window: PSDL_Window; shape: PSDL_Surface; shape_mode: PSDL_WindowShapeMode): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowShape' {$ENDIF} {$ENDIF}; + +{** + * Get the shape parameters of a shaped window. + * + * \param window The shaped window whose parameters should be retrieved. + * \param shape_mode An empty shape-mode structure to fill, or NIL to check + * whether the window has a shape. + * \return 0 if the window has a shape and, provided shape_mode was not NIL, + * shape_mode has been filled with the mode data, + * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped + * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a + * shapeable window currently lacking a shape. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_WindowShapeMode + * \sa SDL_SetWindowShape + *} +function SDL_GetShapedWindowMode(window: PSDL_Window; shape_mode: PSDL_WindowShapeMode): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetShapedWindowMode' {$ENDIF} {$ENDIF}; diff --git a/units/sdlstdinc.inc b/units/sdlstdinc.inc index a0f0d415..c6aca345 100644 --- a/units/sdlstdinc.inc +++ b/units/sdlstdinc.inc @@ -1,9 +1,697 @@ //types from SDL_stdinc.h + +{ SDL-For-Pascal: A lot of the functions are missing. Some functions are useless + if working with Pascal (e. g. memory management functions), + others could be useful (e. g. math functions). + + TODO: Investigate header file and translate potentially useful functions. } + +type + PPSDL_Bool = ^PSDL_Bool; + PSDL_Bool = ^TSDL_Bool; + TSDL_Bool = cbool; + +const + SDL_FALSE = TSDL_Bool(0); + SDL_TRUE = TSDL_Bool(1); + + SDL_MAX_SINT8 = High(cint8); + SDL_MIN_SINT8 = Low(cint8); + + SDL_MAX_UINT8 = High(cuint8); + SDL_MIN_UINT8 = Low(cuint8); + + SDL_MAX_SINT16 = High(cint16); + SDL_MIN_SINT16 = Low(cint16); + + SDL_MAX_UINT16 = High(cuint16); + SDL_MIN_UINT16 = Low(cuint16); + + SDL_MAX_SINT32 = High(cint32); + SDL_MIN_SINT32 = Low(cint32); + + SDL_MAX_UINT32 = High(cuint32); + SDL_MIN_UINT32 = Low(cuint32); + + {$IFDEF Has_Int64} + SDL_MAX_SINT64 = High(cint64); + SDL_MIN_SINT64 = Low(cint64); + + SDL_MAX_UINT64 = High(cuint64); + SDL_MIN_UINT64 = Low(cuint64); + {$ELSE} + SDL_MAX_SINT64: cuint64 = (hi: SDL_MAX_SINT32; lo: SDL_MAX_UINT32); + SDL_MIN_SINT64: cuint64 = (hi: SDL_MIN_SINT32; lo: 0); + + SDL_MAX_UINT64: cuint64 = (hi: SDL_MAX_UINT32; lo: SDL_MAX_UINT32); + SDL_MIN_UINT64: cuint64 = (hi: 0; lo: 0); + {$ENDIF} + + SDL_FLT_EPSILON = cfloat(1.1920928955078125e-07); + type + PPSDL_malloc_func = ^PSDL_malloc_func; + PSDL_malloc_func = ^TSDL_malloc_func; + TSDL_malloc_func = function(size: csize_t): Pointer; cdecl; + + PPSDL_calloc_func = ^PSDL_calloc_func; + PSDL_calloc_func = ^TSDL_calloc_func; + TSDL_calloc_func = function(nmemb, size: csize_t): Pointer; cdecl; - TSDL_Bool = (SDL_FALSE = 0,SDL_TRUE = 1); + PPSDL_realloc_func = ^PSDL_realloc_func; + PSDL_realloc_func = ^TSDL_realloc_func; + TSDL_realloc_func = function(mem: Pointer; size: csize_t): Pointer; cdecl; + + PPSDL_free_func = ^PSDL_free_func; + PSDL_free_func = ^TSDL_free_func; + TSDL_free_func = procedure(mem: Pointer); cdecl; {** -* Free memory returned by functions like SDL_GetBasePath(), SDL_GetPrefPath(), etc. -*} -procedure SDL_free(mem: Pointer); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_free' {$ENDIF} {$ENDIF}; + * Get the original set of SDL memory functions + * + * \since This function is available since SDL 2.24.0. + *} +procedure SDL_GetOriginalMemoryFunctions( + malloc_func: PSDL_malloc_func; + calloc_func: PSDL_calloc_func; + realloc_func: PSDL_realloc_func; + free_func: PSDL_free_func +); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetOriginalMemoryFunctions' {$ENDIF} {$ENDIF}; + +(** + * Get the current set of SDL memory functions + * + * \since This function is available since SDL 2.0.7. + *) +procedure SDL_GetMemoryFunctions( + malloc_func: PSDL_malloc_func; + calloc_func: PSDL_calloc_func; + realloc_func: PSDL_realloc_func; + free_func: PSDL_free_func +); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMemoryFunctions' {$ENDIF} {$ENDIF}; + +(** + * Replace SDL's memory allocation functions with a custom set + * + * \since This function is available since SDL 2.0.7. + *) +function SDL_SetMemoryFunctions( + malloc_func: TSDL_malloc_func; + calloc_func: TSDL_calloc_func; + realloc_func: TSDL_realloc_func; + free_func: TSDL_free_func +): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetMemoryFunctions' {$ENDIF} {$ENDIF}; + +(** + * Get the number of outstanding (unfreed) allocations + * + * \since This function is available since SDL 2.0.7. + *) +function SDL_GetNumAllocations(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumAllocations' {$ENDIF} {$ENDIF}; + +(** + * Allocate a block of memory. The memory is *not* initialized. + *) +function SDL_malloc(size: csize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_malloc' {$ENDIF} {$ENDIF}; + +(** + * Allocate a block of memory that can fit an array of nmemb elements, each of given size. + * The memory is initialized by setting every byte to 0. + *) +function SDL_calloc(nmemb, size: csize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_calloc' {$ENDIF} {$ENDIF}; + +(** + * Resize a block of memory allocated previously with SDL_malloc() or SDL_calloc(). + * + * The returned pointer may or may not be the same as the original pointer. + * If the new size is larger than the old size, any new memory will *not* be initialized. + *) +function SDL_realloc(mem: Pointer; size: csize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_realloc' {$ENDIF} {$ENDIF}; + +(** + * Free memory returned by functions like SDL_GetBasePath(), SDL_GetPrefPath(), etc. + * + * Calling SDL_free() on the same pointer twice is undefined behaviour and may cause + * your program to crash or behave in unexpected ways. + *) +procedure SDL_free(mem: Pointer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_free' {$ENDIF} {$ENDIF}; + + + +{*** --- Character functions --- *** + +SDL2-for-Pascal: All comments are added by us and not found in the include file.} + + +(** + * Check if the provided ASCII character is an alphabetic character (a letter). + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isalpha(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isalpha' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is an alphanumeric character. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isalnum(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isalnum' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a blank character (a space or a tab). + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isblank(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isblank' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a control character. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_iscntrl(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_iscntrl' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a decimal digit. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_isdigit(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isdigit' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a hexadecimal digit. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isxdigit(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isxdigit' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is any printable character + * which is not a space or an alphanumeric character. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_ispunct(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ispunct' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a whitespace character. + * This set includes the following characters: space, + * form feed (FF), newline/line feed (LF), carriage return (CR), + * horizontal tab (HT), vertical tab (VT). + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_isspace(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isspace' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is an uppercase letter. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.12. + *) +function SDL_isupper(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isupper' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a lowercase letter. + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.12. + *) +function SDL_islower(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_islower' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a printable character (including space). + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isprint(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isprint' {$ENDIF} {$ENDIF}; + +(** + * Check if the provided ASCII character is a printable character (excluding space). + * + * \returns 1 if the check passes, 0 otherwise. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_isgraph(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_isgraph' {$ENDIF} {$ENDIF}; + +(** + * If the given ASCII character is a lowercase letter, converts it to uppercase. + * Otherwise returns the original value. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_toupper(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_toupper' {$ENDIF} {$ENDIF}; + +(** + * If the given ASCII character is an uppercase letter, converts it to lowercase. + * Otherwise returns the original value. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_tolower(x: cint):cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_tolower' {$ENDIF} {$ENDIF}; + + + +(*** --- Math functions --- ***) + + +(** + * Calculate the arc cosine of x; + * that is, the value (in radians) whose cosine equals x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_acos(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_acos' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc cosine of x; + * that is, the value (in radians) whose cosine equals x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_acosf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_acosf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc sine of x; + * that is, the value (in radians) whose sine equals x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_asin(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_asin' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc sine of x; + * that is, the value (in radians) whose sine equals x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_asinf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_asinf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc tangent of x; + * that is, the value (in radians) whose tangent equals x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_atan(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_atan' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc tangent of x; + * that is, the value (in radians) whose tangent equals x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_atanf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_atanf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc tangent of y/x, using the signs of the two arguments + * to determine the quadrant of the result. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_atan2(y, x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_atan2' {$ENDIF} {$ENDIF}; + +(** + * Calculate the arc tangent of y/x, using the signs of the two arguments + * to determine the quadrant of the result. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_atan2f(y, x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_atan2f' {$ENDIF} {$ENDIF}; + +(** + * Calculate the smallest integral value that is not less than x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_ceil(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ceil' {$ENDIF} {$ENDIF}; + +(** + * Calculate the smallest integral value that is not less than x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_ceilf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ceilf' {$ENDIF} {$ENDIF}; + +(** + * Return a number whose absolute value matches that of x, + * but the sign matches that of y. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_copysign(x, y: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_copysign' {$ENDIF} {$ENDIF}; + +(** + * Return a number whose absolute value matches that of x, + * but the sign matches that of y. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_copysignf(x, y: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_copysignf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the cosine of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_cos(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_cos' {$ENDIF} {$ENDIF}; + +(** + * Calculate the cosine of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_cosf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_cosf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the value of e (the base of natural logarithms) + * raised to the power of x. + * + * \since This function is available since SDL 2.0.9. + *) +function SDL_exp(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_exp' {$ENDIF} {$ENDIF}; + +(** + * Calculate the value of e (the base of natural logarithms) + * raised to the power of x. + * + * \since This function is available since SDL 2.0.9. + *) +function SDL_expf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_expf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the absolute value of x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_fabs(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_fabs' {$ENDIF} {$ENDIF}; + +(** + * Calculate the absolute value of x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_fabsf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_fabsf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the largest integral value that is not greater than x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_floor(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_floor' {$ENDIF} {$ENDIF}; + +(** + * Calculate the largest integral value that is not greater than x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_floorf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_floorf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the floating-point remainder of dividing x by y. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_fmod(x, y: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_fmod' {$ENDIF} {$ENDIF}; + +(** + * Calculate the floating-point remainder of dividing x by y. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_fmodf(x, y: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_fmodf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the natural logarithm of x. + * + * \since This function is available since SDL 2.0.4. + + SDL2-for-Pascal: ATTENTION: The original C name of this function is SDL_log, + but since Pascal names are case-insensitive, it is in conflict with SDL_Log (logging function). + Hence we decided to rename it. + *) +function SDL_nlog(x: cdouble): cdouble; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_log' {$ELSE} 'SDL_log' {$ENDIF}; + +(** + * Calculate the natural logarithm of x. + * + * \since This function is available since SDL 2.0.8. + + SDL2-for-Pascal: ATTENTION: The original C name of this function is SDL_logf, + but to be consistent with the renamed SDL_log function (see comment of SDL_nlog + for details), we decided to rename it. + *) +function SDL_nlogf(x: cfloat): cfloat; cdecl; + external SDL_LibName + name {$IF DEFINED(DELPHI) AND DEFINED(MACOS)} '_SDL_logf' {$ELSE} 'SDL_logf' {$ENDIF}; + +(** + * Calculate the base 10 logarithm of x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_log10(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_log10' {$ENDIF} {$ENDIF}; + +(** + * Calculate the base 10 logarithm of x. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_log10f(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_log10f' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integer, away from zero. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_lround(x: cdouble): clong; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_lround' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integer, away from zero. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_lroundf(x: cfloat): clong; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_lroundf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the value of x raised to the power of y. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_pow(x, y: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_pow' {$ENDIF} {$ENDIF}; + +(** + * Calculate the value of x raised to the power of y. + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_powf(x, y: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_powf' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integral value, away from zero. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_round(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_round' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integral value, away from zero. + * + * \since This function is available since SDL 2.0.16. + *) +function SDL_roundf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_roundf' {$ENDIF} {$ENDIF}; + +(** + * Calculate x multiplied by the floating-point radix to the power of n. + * On most systems, the radix is 2, making this equivalent to x*(2**n). + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_scalbn(x: cdouble; n: cint): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_scalbn' {$ENDIF} {$ENDIF}; + +(** + * Calculate x multiplied by the floating-point radix to the power of n. + * On most systems, the radix is 2, making this equivalent to x*(2**n). + * + * \since This function is available since SDL 2.0.8. + *) +function SDL_scalbnf(x: cfloat; n: cint): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_scalbnf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the sine of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_sin(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_sin' {$ENDIF} {$ENDIF}; + +(** + * Calculate the sine of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_sinf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_sinf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the non-negative square root of x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_sqrt(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_sqrt' {$ENDIF} {$ENDIF}; + +(** + * Calculate the non-negative square root of x. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_sqrtf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_sqrtf' {$ENDIF} {$ENDIF}; + +(** + * Calculate the tangent of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_tan(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_tan' {$ENDIF} {$ENDIF}; + +(** + * Calculate the tangent of x, where x is given in radians. + * + * \since This function is available since SDL 2.0.4. + *) +function SDL_tanf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_tanf' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integral value, towards zero. + * + * \since This function is available since SDL 2.0.14. + *) +function SDL_trunc(x: cdouble): cdouble; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_trunc' {$ENDIF} {$ENDIF}; + +(** + * Round to nearest integral value, towards zero. + * + * \since This function is available since SDL 2.0.14. + *) +function SDL_truncf(x: cfloat): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_truncf' {$ENDIF} {$ENDIF}; + + + +(*** --- iconv functions --- ***) + + +(** + * This function converts a string between encodings in one pass, returning a + * string that must be freed with SDL_free(), or NIL on error. + * + * \since This function is available since SDL 2.0.0. + *) +function SDL_iconv_string(Const tocode, fromcode, inbuf: PAnsiChar; inbytesleft: csize_t): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_iconv_string' {$ENDIF} {$ENDIF}; + +// These are macros in the original C headers, we will reimplement them as simple Pascal functions. +function SDL_iconv_utf8_locale(Const str: PAnsiChar): PAnsiChar; cdecl; +function SDL_iconv_utf8_ucs2(Const str: PAnsiChar): pcUint16; cdecl; +function SDL_iconv_utf8_ucs4(Const str: PAnsiChar): pcUint32; cdecl; + +(* The SDL implementation of iconv() returns these error codes *) +const + SDL_ICONV_ERROR = csize_t(-1); + SDL_ICONV_E2BIG = csize_t(-2); + SDL_ICONV_EILSEQ = csize_t(-3); + SDL_ICONV_EINVAL = csize_t(-4); + +type + PSDL_iconv = type Pointer; + +function SDL_iconv_open(Const tocode, fromcode: PAnsiChar): PSDL_iconv; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_iconv_open' {$ENDIF} {$ENDIF}; + +function SDL_iconv_close(cd: PSDL_iconv): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_iconv_close' {$ENDIF} {$ENDIF}; + +function SDL_iconv(cd: PSDL_iconv; Const inbuf: PPAnsiChar; inbytesleft: pcsize_t; outbuf: PPAnsiChar; outbytesleft: pcsize_t): csize_t; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_iconv' {$ENDIF} {$ENDIF}; diff --git a/units/sdlsurface.inc b/units/sdlsurface.inc index 3bd9009f..61a458b8 100644 --- a/units/sdlsurface.inc +++ b/units/sdlsurface.inc @@ -22,11 +22,8 @@ type * This structure should be treated as read-only, except for \c pixels, * which, if not NULL, contains the raw pixel data for the surface. *} - - PSDL_BlitMap = ^TSDL_BlitMap; - TSDL_BlitMap = record - map: Pointer; - end; + PPSDL_BlitMap = ^PSDL_BlitMap; + PSDL_BlitMap = type Pointer; PPSDL_Surface = ^PSDL_Surface; PSDL_Surface = ^TSDL_Surface; @@ -51,7 +48,7 @@ type clip_rect: TSDL_Rect; {**< Read-only *} {** info for fast blit mapping to other surfaces *} - map: Pointer; {**< Private *} // TODO: Check: Why Pointer and not PSDL_BlitMap used here? + map: PSDL_BlitMap; {**< Private *} {** Reference count -- used when freeing surface *} refcount: cint; {**< Read-mostly *} @@ -64,6 +61,8 @@ type {** * The type of function used for surface blitting functions. *} + PPSDL_Blit = ^PSDL_Blit; + PSDL_Blit = ^TSDL_Blit; TSDL_Blit = function(src: PSDL_Surface; srcrect: PSDL_Rect; dst: PSDL_Surface; dstrect: PSDL_Rect): cint; type diff --git a/units/sdlsystem.inc b/units/sdlsystem.inc index 2c404d51..0aa3cbd0 100644 --- a/units/sdlsystem.inc +++ b/units/sdlsystem.inc @@ -2,66 +2,463 @@ (* Platform specific functions for Windows *) {$IF DEFINED(WIN32) OR DEFINED(WIN64)} +type + PPSDL_WindowsMessageHook = ^PSDL_WindowsMessageHook; + PSDL_WindowsMessageHook = ^TSDL_WindowsMessageHook; + TSDL_WindowsMessageHook = procedure(userdata, hWnd: Pointer; mesage: cuint; wParam: cuint64; lParam: cint64); cdecl; - {** - * \brief Set a function that is called for every windows message, before TranslateMessage() - *} -Type - TSDL_WindowsMessageHook = Procedure(userdata, hWnd: Pointer; mesage: cuint32; wParam: cuint64; lParam: cint64); cdecl; +{** + * Set a callback for every Windows message, run before TranslateMessage(). + * + * \param callback The SDL_WindowsMessageHook function to call. + * \param userdata a pointer to pass to every iteration of `callback` + * + * \since This function is available since SDL 2.0.4. + *} +procedure SDL_SetWindowsMessageHook(callback: TSDL_WindowsMessageHook; userdata: Pointer); cdecl; + external SDL_LibName; -Procedure SDL_SetWindowsMessageHook(callback: TSDL_WindowsMessageHook; userdata: Pointer); cdecl; +{** + * Get the D3D9 adapter index that matches the specified display index. + * + * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and + * controls on which monitor a full screen application will appear. + * + * \param displayIndex the display index for which to get the D3D9 adapter + * index + * \returns the D3D9 adapter index on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.1. + *} +function SDL_Direct3D9GetAdapterIndex(displayIndex:cint):cint; cdecl; external SDL_LibName; - {* Returns the D3D9 adapter index that matches the specified display index. - * This adapter index can be passed to IDirect3D9::CreateDevice and controls - * on which monitor a full screen application will appear. - *} -Function SDL_Direct3D9GetAdapterIndex(displayIndex:cint32):cint32; - cdecl; external SDL_LibName; +type + PIDirect3DDevice9 = type Pointer; + PID3D11Device = type Pointer; + PID3D12Device = type Pointer; - {* Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer. - * Once you are done using the device, you should release it to avoid a resource leak. - *} -Type PIDirect3DDevice9 = Pointer; -Function SDL_RenderGetD3D9Device(renderer:PSDL_Renderer):PIDirect3DDevice9; - cdecl; external SDL_LibName; +{** + * Get the D3D9 device associated with a renderer. + * + * Once you are done using the device, you should release it to avoid a + * resource leak. + * + * \param renderer the renderer from which to get the associated D3D device + * \returns the D3D9 device associated with given renderer or NIL if it is + * not a D3D9 renderer; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.1. + *} +function SDL_RenderGetD3D9Device(renderer:PSDL_Renderer):PIDirect3DDevice9; cdecl; + external SDL_LibName; -{* Returns the DXGI Adapter and Output indices for the specified display index. - * These can be passed to EnumAdapters and EnumOutputs respectively to get the objects - * required to create a DX10 or DX11 device and swap chain. +{** + * Get the D3D11 device associated with a renderer. + * + * Once you are done using the device, you should release it to avoid a + * resource leak. + * + * \param renderer the renderer from which to get the associated D3D11 device + * \returns the D3D11 device associated with given renderer or NIL if it is + * not a D3D11 renderer; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.16. *} -function SDL_DXGIGetOutputInfo(displayIndex :cint32; adapterIndex, outputIndex :pcint32): TSDL_Bool; - cdecl; external SDL_LibName; +function SDL_RenderGetD3D11Device(renderer:PSDL_Renderer):PID3D11Device; cdecl; + external SDL_LibName; + +{** + * Get the D3D12 device associated with a renderer. + * + * Once you are done using the device, you should release it to avoid a + * resource leak. + * + * \param renderer the renderer from which to get the associated D3D12 device + * \returns the D3D12 device associated with given renderer or NIL if it is + * not a D3D12 renderer; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.24.0. + *} +function SDL_RenderGetD3D12Device(renderer:PSDL_Renderer):PID3D12Device; cdecl; + external SDL_LibName; + +{** + * Get the DXGI Adapter and Output indices for the specified display index. + * + * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and + * `EnumOutputs` respectively to get the objects required to create a DX10 or + * DX11 device and swap chain. + * + * Before SDL 2.0.4 this function did not return a value. + * Since SDL 2.0.4 it returns a TSDL_bool. + * + * \param displayIndex the display index for which to get both indices + * \param adapterIndex a pointer to be filled in with the adapter index + * \param outputIndex a pointer to be filled in with the output index + * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 2.0.2. + *} +function SDL_DXGIGetOutputInfo(displayIndex: cint; adapterIndex, outputIndex: pcint): TSDL_Bool; + external SDL_LibName; +{$ENDIF WIN32 OR WIN64} + + +(* Platform specific functions for Linux *) +{$IFDEF LINUX} +{** + * Sets the UNIX nice value for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID the Unix thread ID to change priority of. + * \param priority The new, Unix-specific, priority value. + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_LinuxSetThreadPriority(threadID: cint64; priority: cint): cint; cdecl; + external SDL_LibName; + +{** + * Sets the priority (not nice level) and scheduling policy for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID The Unix thread ID to change priority of. + * \param sdlPriority The new TSDL_ThreadPriority value. + * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, + * SCHED_OTHER, etc...) + * \returns 0 on success, or -1 on error. + * + * \since This function is available since SDL 2.0.18. + *} +function SDL_LinuxSetThreadPriorityAndPolicy(threadID: cint64; sdlPriority, schedPolicy: cint): cint; cdecl; + external SDL_LibName; +{$ENDIF LINUX} + + +(* Platform specific functions for iOS *) +{$IFDEF __IPHONEOS__} +type + PPSDL_iPhoneAnimationCallback = ^PSDL_iPhoneAnimationCallback; + PSDL_iPhoneAnimationCallback = ^TSDL_iPhoneAnimationCallback; + TSDL_iPhoneAnimationCallback = procedure(callbackParam: Pointer); cdecl; + +{** + * Use this function to set the animation callback on Apple iOS. + * + * This function is only available on Apple iOS. + * + * For more information see: + * https://github.com/libsdl-org/SDL/blob/main/docs/README-ios.md + * + * \param window the window for which the animation callback should be set + * \param interval the number of frames after which **callback** will be + * called + * \param callback the function to call for every frame. + * \param callbackParam a pointer that is passed to `callback`. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_iPhoneSetEventPump + *} +function SDL_iPhoneSetAnimationCallback(window: PSDL_Window; interval: cint; callback: TSDL_iPhoneAnimationCallback; callbackParam: Pointer); cdecl; + external SDL_LibName; + +{** + * Use this function to enable or disable the SDL event pump on Apple iOS. + * + * This function is only available on Apple iOS. + * + * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_iPhoneSetAnimationCallback + *} +procedure SDL_iPhoneSetEventPump(enabled: TSDL_Bool); cdecl; + external SDL_LibName; +{$ENDIF __IPHONEOS__} -{$IFEND} + +(* Platform specific functions for Android *) +{$IFDEF ANDROID} + +{** + * Get the Android Java Native Interface Environment of the current thread. + * + * This is the JNIEnv one needs to access the Java virtual machine from native + * code, and is needed for many Android APIs to be usable from Pascal. + * + * The prototype of the function in SDL's code actually declare a Pointer return + * type, even if the implementation returns a pointer to a JNIEnv. The + * rationale being that the SDL units can avoid using the JNI unit. + * + * \returns a pointer to Java native interface object (JNIEnv) to which the + * current thread is attached, or NIL on error. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AndroidGetActivity + *} +function SDL_AndroidGetJNIEnv(): Pointer; cdecl; + external SDL_LibName; + +(** + * Retrieve the Java instance of the Android activity class. + * + * The prototype of the function in SDL's code actually declares a Pointer + * return type, even if the implementation returns a JObject. The rationale + * being that the SDL units can avoid using the JNI unit. + * + * The JObject returned by the function is a local reference and must be + * released by the caller. See the PushLocalFrame() and PopLocalFrame() or + * DeleteLocalRef() functions of the Java native interface: + * + * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html + * + * \returns the jobject representing the instance of the Activity class of the + * Android application, or NIL on error. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AndroidGetJNIEnv + *) +function SDL_AndroidGetActivity(): Pointer; cdecl; + external SDL_LibName; + +{** + * Query Android API level of the current device. + * + * - API level 34: Android 14 + * - API level 33: Android 13 + * - API level 32: Android 12L + * - API level 31: Android 12 + * - API level 30: Android 11 + * - API level 29: Android 10 + * - API level 28: Android 9 "Pie" + * - API level 27: Android 8.1 "Oreo" + * - API level 26: Android 8.0 "Oreo" + * - API level 25: Android 7.1 "Nougat" + * - API level 24: Android 7.0 "Nougat" + * - API level 23: Android 6.0 "Marshmallow" + * - API level 22: Android 5.1 "Lollipop" + * - API level 21: Android 5.0 "Lollipop" + * - API level 20: Android 4.4W "KitKat" + * - API level 19: Android 4.4 "KitKat" + * - API level 18: Android 4.3 "Jelly Bean" + * - API level 17: Android 4.2 "Jelly Bean" + * - API level 16: Android 4.1 "Jelly Bean" + * - API level 15: Android 4.0.3 "Ice Cream Sandwich" + * - API level 14: Android 4.0 "Ice Cream Sandwich" + * - API level 13: Android 3.2 "Honeycomb" + * - API level 12: Android 3.1 "Honeycomb" + * - API level 11: Android 3.0 "Honeycomb" + * - API level 10: Android 2.3.3 "Gingerbread" + * + * \returns the Android API level. + * + * \since This function is available since SDL 2.0.12. + *} +function SDL_GetAndroidSDKVersion(): cint; cdecl; + external SDL_LibName; + +{** + * Query if the application is running on Android TV. + * + * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.8. + *} +function SDL_IsAndroidTV(): TSDL_Bool; cdecl; + external SDL_LibName; + +{** + * Query if the application is running on a Chromebook. + * + * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_IsChromebook(): TSDL_Bool; cdecl; + external SDL_LibName; + +{** + * Query if the application is running on a Samsung DeX docking station. + * + * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_IsDeXMode(): TSDL_Bool; cdecl; + external SDL_LibName; + +{** + * Trigger the Android system back button behavior. + * + * \since This function is available since SDL 2.0.9. + *} +procedure SDL_AndroidBackButton(); cdecl; + external SDL_LibName; + +{** + See the official Android developer guide for more information: + http://developer.android.com/guide/topics/data/data-storage.html +*} +const + SDL_ANDROID_EXTERNAL_STORAGE_READ = $01; + SDL_ANDROID_EXTERNAL_STORAGE_WRITE = $02; + +{** + * Get the path used for internal storage for this application. + * + * This path is unique to your application and cannot be written to by other + * applications. + * + * Your internal storage path is typically: + * `/data/data/your.app.package/files`. + * + * \returns the path used for internal storage or NIL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AndroidGetExternalStorageState + *} +function SDL_AndroidGetInternalStoragePath(): PAnsiChar; cdecl; + external SDL_LibName; + +{** + * Get the current state of external storage. + * + * The current state of external storage, a bitmask of these values: + * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`. + * + * If external storage is currently unavailable, this will return 0. + * + * \returns the current state of external storage on success or 0 on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AndroidGetExternalStoragePath + *} +function SDL_AndroidGetExternalStorageState(): cint; cdecl; + external SDL_LibName; + +{** + * Get the path used for external storage for this application. + * + * This path is unique to your application, but is public and can be written + * to by other applications. + * + * Your external storage path is typically: + * `/storage/sdcard0/Android/data/your.app.package/files`. + * + * \returns the path used for external storage for this application on success + * or NIL on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_AndroidGetExternalStorageState + *} +function SDL_AndroidGetExternalStoragePath(): PAnsiChar; cdecl; + external SDL_LibName; + +{** + * Request permissions at runtime. + * + * This blocks the calling thread until the permission is granted or denied. + * + * For a full list of possible permission names, consult the Android docs: + * https://developer.android.com/reference/android/Manifest.permission + * + * \param permission The permission to request. + * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.14. + *} +function SDL_AndroidRequestPermission(const permission: PAnsiChar): TSDL_Bool; cdecl; + external SDL_LibName; + +{** + * Shows an Android toast notification. + * + * Toasts are a sort of lightweight notification that are unique to Android. + * + * https://developer.android.com/guide/topics/ui/notifiers/toasts + * + * Shows toast in UI thread. + * + * For the `gravity` parameter, choose a value from here, or -1 if you don't + * have a preference: + * + * https://developer.android.com/reference/android/view/Gravity + * + * \param message text message to be shown + * \param duration 0=short, 1=long + * \param gravity where the notification should appear on the screen. + * \param xoffset set this parameter only when gravity >=0 + * \param yoffset set this parameter only when gravity >=0 + * \returns 0 if success, -1 if any error occurs. + * + * \since This function is available since SDL 2.0.16. + *} +function SDL_AndroidShowToast(const message: PAnsiChar; duration, gravity, xoffset, yoffset: cint): cint; cdecl; + external SDL_LibName; + +{** + * Send a user command to SDLActivity. + * + * Override "boolean onUnhandledMessage(Message msg)" to handle the message. + * + * \param command user command that must be greater or equal to 0x8000 + * \param param user parameter + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_AndroidSendMessage(command: cUint32; param: cint): cint; cdecl; + external SDL_LibName; +{$ENDIF ANDROID} (* Platform specific functions for WinRT *) {$IFDEF __WINRT__} - - {** - * \brief WinRT / Windows Phone path types - *} Type + {** WinRT / Windows Phone path types *} + PPSDL_WinRT_Path = ^PSDL_WinRT_Path; + PSDL_WinRT_Path = ^TSDL_WinRT_Path; TSDL_WinRT_Path = ( - - {** \brief The installed app's root directory. + {** The installed app's root directory. Files here are likely to be read-only. *} SDL_WINRT_PATH_INSTALLED_LOCATION = 0, - - {** \brief The app's local data store. Files may be written here *} + {** The app's local data store. Files may be written here *} SDL_WINRT_PATH_LOCAL_FOLDER = 1, - - {** \brief The app's roaming data store. Unsupported on Windows Phone. + {** The app's roaming data store. Unsupported on Windows Phone. Files written here may be copied to other machines via a network connection. *} SDL_WINRT_PATH_ROAMING_FOLDER = 2, - - {** \brief The app's temporary data store. Unsupported on Windows Phone. + {** The app's temporary data store. Unsupported on Windows Phone. Files written here may be deleted at any time. *} SDL_WINRT_PATH_TEMP_FOLDER = 3 + ); + TSDL_WinRT_DeviceFamily = ( + {** Unknown family *} + SDL_WINRT_DEVICEFAMILY_UNKNOWN, + {** Desktop family *} + SDL_WINRT_DEVICEFAMILY_DESKTOP, + {** Mobile family (for example smartphone) *} + SDL_WINRT_DEVICEFAMILY_MOBILE, + {** XBox family *} + SDL_WINRT_DEVICEFAMILY_XBOX ); @@ -80,7 +477,7 @@ Type * SDL_WinRT_Path for more information on which path types are * supported where. *} -Function SDL_WinRTGetFSPathUNICODE(pathType :TSDL_WinRT_Path):PWideChar; +function SDL_WinRTGetFSPathUNICODE(pathType :TSDL_WinRT_Path):PWideChar; cdecl; external SDL_LibName; @@ -99,7 +496,42 @@ Function SDL_WinRTGetFSPathUNICODE(pathType :TSDL_WinRT_Path):PWideChar; * SDL_WinRT_Path for more information on which path types are * supported where. *} -Function SDL_WinRTGetFSPathUTF8(pathType :TSDL_WinRT_Path):PChar; +function SDL_WinRTGetFSPathUTF8(pathType :TSDL_WinRT_Path):PChar; cdecl; external SDL_LibName; + +{** + * Detects the device family of WinRT platform at runtime. + * + * \returns a value from the SDL_WinRT_DeviceFamily enum. + * + * \since This function is available since SDL 2.0.8. + *} +function SDL_WinRTGetDeviceFamily(): TSDL_WinRT_DeviceFamily; + cdecl; external SDL_LibName; +{$ENDIF __WINRT__} + + +{** + * Query if the current device is a tablet. + * + * If SDL can't determine this, it will return SDL_FALSE. + * + * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.9. + *} +function SDL_IsTablet(): TSDL_Bool; cdecl; + external SDL_LibName; + + +{ Functions used by iOS application delegates to notify SDL about state changes } +procedure SDL_OnApplicationWillTerminate(); cdecl; external SDL_LibName; +procedure SDL_OnApplicationDidReceiveMemoryWarning(); cdecl; external SDL_LibName; +procedure SDL_OnApplicationWillResignActive(); cdecl; external SDL_LibName; +procedure SDL_OnApplicationDidEnterBackground(); cdecl; external SDL_LibName; +procedure SDL_OnApplicationWillEnterForeground(); cdecl; external SDL_LibName; +procedure SDL_OnApplicationDidBecomeActive(); cdecl; external SDL_LibName; +{$IFDEF __IPHONEOS__} +procedure SDL_OnApplicationDidChangeStatusBarOrientation(); cdecl; external SDL_LibName; {$ENDIF} diff --git a/units/sdlsyswm.inc b/units/sdlsyswm.inc index e17f8393..69bcc655 100644 --- a/units/sdlsyswm.inc +++ b/units/sdlsyswm.inc @@ -1,18 +1,27 @@ // from sdl_syswm.h +{** + * \brief SDL_syswm.h + * + * Your application has access to a special type of event ::SDL_SYSWMEVENT, + * which contains window-manager specific information and arrives whenever + * an unhandled window event occurs. This event is ignored by default, but + * you can enable it with SDL_EventState(). + *} + {$IFDEF WINDOWS} {$DEFINE SDL_VIDEO_DRIVER_WINDOWS} {$ENDIF} -{$IF DEFINED (LINUX) OR DEFINED(UNIX)} +{$IFDEF UNIX} {$IF NOT (DEFINED(DARWIN) OR DEFINED(ANDROID))} {$DEFINE SDL_VIDEO_DRIVER_X11} - {$ENDIF} -{$IFEND} + {$IFEND} +{$ENDIF} (* * Disabled because FPC does not ship a DirectFB unit. - * If you have some working DirectDB bindings, feel welcome to enable this and check if it breaks anything. + * If you have some working DirectFB bindings, feel welcome to enable this and check if it breaks anything. *) {$UNDEF SDL_VIDEO_DRIVER_DIRECTFB} @@ -59,6 +68,9 @@ {$DEFINE SDL_VIDEO_DRIVER_OS2} {$ENDIF} +{ SDL2-for-Pascal: Disabled because there are no FPC/Delphi units available. } +{$UNDEF SDL_VIDEO_DRIVER_KMSDRM} + {$IFDEF HAIKU} {$DEFINE SDL_VIDEO_DRIVER_HAIKU} {$ENDIF} @@ -67,35 +79,35 @@ {** * These are the various supported windowing subsystems *} -Type - TSDL_SYSWM_TYPE = ( - SDL_SYSWM_UNKNOWN, - SDL_SYSWM_WINDOWS, - SDL_SYSWM_X11, - SDL_SYSWM_DIRECTFB, - SDL_SYSWM_COCOA, - SDL_SYSWM_UIKIT, - SDL_SYSWM_WAYLAND, // Since SDL 2.0.2 - REMOVED in SDL 2.0.10! - SDL_SYSWM_MIR, // Since SDL 2.0.2 - SDL_SYSWM_WINRT, // Since SDL 2.0.3 - SDL_SYSWM_ANDROID, // Since SDL 2.0.4 - SDL_SYSWM_VIVANTE, // Since SDL 2.0.5 - SDL_SYSWM_OS2, // Since SDL 2.0.6 - SDL_SYSWM_HAIKU // Since SDL 2.0.12 - ); +type + TSDL_SYSWM_TYPE = type cint; + +const + SDL_SYSWM_UNKNOWN = TSDL_SYSWM_TYPE(0); + SDL_SYSWM_WINDOWS = TSDL_SYSWM_TYPE(1); + SDL_SYSWM_X11 = TSDL_SYSWM_TYPE(2); + SDL_SYSWM_DIRECTFB = TSDL_SYSWM_TYPE(3); + SDL_SYSWM_COCOA = TSDL_SYSWM_TYPE(4); + SDL_SYSWM_UIKIT = TSDL_SYSWM_TYPE(5); + SDL_SYSWM_WAYLAND = TSDL_SYSWM_TYPE(6); + SDL_SYSWM_MIR = TSDL_SYSWM_TYPE(7); // * no longer available, left for API/ABI compatibility. Remove in 2.1! * + SDL_SYSWM_WINRT = TSDL_SYSWM_TYPE(8); + SDL_SYSWM_ANDROID = TSDL_SYSWM_TYPE(9); + SDL_SYSWM_VIVANTE = TSDL_SYSWM_TYPE(10); + SDL_SYSWM_OS2 = TSDL_SYSWM_TYPE(11); + SDL_SYSWM_HAIKU = TSDL_SYSWM_TYPE(12); + SDL_SYSWM_KMSDRM = TSDL_SYSWM_TYPE(13); + SDL_SYSWM_RISCOS = TSDL_SYSWM_TYPE(14); /// sdl_syswm.h uses anonymous structs, declared right in SDL_SysWMmsg and SDL_SysWMinfo. /// Since Pascal does not allow this, we workaround by introducing named types. +type {$IFDEF SDL_VIDEO_DRIVER_WINDOWS} __SYSWM_WINDOWS = record hwnd: HWND; {**< The window for the message } - msg: uInt; {**< The type of message *} + msg: UINT; {**< The type of message *} wParam: WPARAM; {**< WORD message parameter *} - lParam: LPARAM; {**< WORD message parameter *} - end; - __WMINFO_WINDOWS = record - window: HWND; {**< The window handle *} - hdc: HDC; {**< The window device context *} + lParam: LPARAM; {**< LONG message parameter *} end; {$ENDIF} @@ -103,6 +115,67 @@ Type __SYSWM_X11 = record event: {$IFDEF FPC} TXEvent {$ELSE} XEvent {$ENDIF}; end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_DIRECTFB} + __SYSWM_DIRECTFB = record + event: DFBEvent; + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_COCOA} + __SYSWM_COCOA = record + (* No Cocoa window events yet *) + dummy: cint; + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_UIKIT} + __SYSWM_UIKIT = record + (* No UIKit window events yet *) + dummy: cint; + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_VIVANTE} + __SYSWM_VIVANTE = record + (* No Vivante window events yet *) + dummy: cint; + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_OS2} + __SYSWM_OS2 = record + fFrame: Boolean; {**< TRUE if hwnd is a frame window *} + hwnd: HWND; {**< The window receiving the message *} + msg: ULONG; {**< The message identifier *} + mp1: MPARAM; {**< The first first message parameter *} + mp2: MPARAM; {**< The second first message parameter *} + end; +{$ENDIF} + +{** + * The custom window manager information structure. + * + * When this structure is returned, it holds information about which + * low level system it is using, and will be one of SDL_SYSWM_TYPE. + *} + +{$IFDEF SDL_VIDEO_DRIVER_WINDOWS} + __WMINFO_WINDOWS = record + window: HWND; {**< The window handle *} + hdc: HDC; {**< The window device context *} + hinstance: HINST; {**< The instance handle *} + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_WINRT} + __WMINFO_WINRT = record + window: IInspectable; {**< The WinRT CoreWindow *} + end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_X11} __WMINFO_X11 = record display: PDisplay; {**< The X11 display *} window: TWindow; {**< The X11 window *} @@ -110,9 +183,6 @@ Type {$ENDIF} {$IFDEF SDL_VIDEO_DRIVER_DIRECTFB} - __SYSWM_DIRECTFB = record - event: DFBEvent; - end; __WMINFO_DIRECTFB = record dfb: IDirectFB; {**< The directfb main interface *} window: IDirectFBWindow; {**< The directfb window handle *} @@ -121,20 +191,12 @@ Type {$ENDIF} {$IFDEF SDL_VIDEO_DRIVER_COCOA} - __SYSWM_COCOA = record - (* No Cocoa window events yet *) - dummy: integer; - end; __WMINFO_COCOA = record window: NSWindow; {* The Cocoa window *} end; {$ENDIF} {$IFDEF SDL_VIDEO_DRIVER_UIKIT} - __SYSWM_UIKIT = record - (* No UIKit window events yet *) - dummy: integer; - end; __WMINFO_UIKIT = record window: UIWindow; {* The UIKit window *} framebuffer: GLuint; {* The GL view's Framebuffer Object. It must be bound when rendering to the screen using GL. *} @@ -147,23 +209,22 @@ Type __WMINFO_WAYLAND = record display: wl_display; {**< Wayland display *} surface: wl_surface; {**< Wayland surface *} - shell_surface: wl_shell_surface; {**< Wayland shell_surface (window manager handle) *} + shell_surface: Pointer; {**< DEPRECATED Wayland shell_surface (window manager handle) *} + egl_window: wl_egl_window; {**< Wayland EGL window (native window) *} + xdg_surface: xdg_surface; {**< Wayland xdg surface (window manager handle) *} + xdg_toplevel: xdg_toplevel; {**< Wayland xdg toplevel role *} + xdg_popup: xdg_popup; {**< Wayland xdg popup role *} + xdg_positioner: xdg_positioner; {**< Wayland xdg positioner, for popup *} end; {$ENDIF} -{$IFDEF SDL_VIDEO_DRIVER_MIR} +{$IFDEF SDL_VIDEO_DRIVER_MIR} {* no longer available, left for API/ABI compatibility. Remove in 2.1! *} __WMINFO_MIR = record connection: PMirConnection; {**< Mir display server connection *} surface: PMirSurface; {**< Mir surface *} end; {$ENDIF} -{$IFDEF SDL_VIDEO_DRIVER_WINRT} - __WMINFO_WINRT = record - window: IInspectable; {**< The WinRT CoreWindow *} - end; -{$ENDIF} - {$IFDEF SDL_VIDEO_DRIVER_ANDROID} __WMINFO_ANDROID = record window: Pointer; // PANativeWindow; @@ -171,35 +232,35 @@ Type end; {$ENDIF} -{$IFDEF SDL_VIDEO_DRIVER_VIVANTE} - __SYSWM_VIVANTE = record - (* No Vivante window events yet *) - dummy: integer; +{$IFDEF SDL_VIDEO_DRIVER_OS2} + __WMINFO_OS2 = record + hwnd: HWND; {**< The window handle *} + hwndFrame: HWND; {**< The frame window handle *} end; +{$ENDIF} + +{$IFDEF SDL_VIDEO_DRIVER_VIVANTE} __WMINFO_VIVANTE = record display: EGLNativeDisplayType; window: EGLNativeWindowType; end; {$ENDIF} -{$IFDEF SDL_VIDEO_DRIVER_OS2} - __SYSWM_OS2 = record - fFrame: Boolean; {**< TRUE if hwnd is a frame window *} - hwnd: HWND; {**< The window receiving the message *} - msg: uInt; {**< The message identifier *} - mp1: MPARAM; {**< The first first message parameter *} - mp2: MPARAM; {**< The second first message parameter *} - end; - __WMINFO_OS2 = record - hwnd: HWND; {**< The window handle *} - hwndFrame: HWND; {**< The frame window handle *} +{$IFDEF SDL_VIDEO_DRIVER_KMSDRM} + __WMINFO_KMSDRM = record + dev_index: cint; {**< Device index (ex: the X in /dev/dri/cardX) *} + drm_fd: cint; {**< DRM FD (unavailable on Vulkan windows) *} + gbm_device: Pointer; // *gbm_dev {**< GBM device (unavailable on Vulkan windows) *} end; {$ENDIF} + + {** * The custom event structure. *} + PPSDL_SysWMmsg = ^PSDL_SysWMmsg; PSDL_SysWMmsg = ^TSDL_SysWMmsg; TSDL_SysWMmsg = record version: TSDL_version; @@ -234,6 +295,7 @@ Type * When this structure is returned, it holds information about which * low level system it is using, and will be one of SDL_SYSWM_TYPE. *} + PPSDL_SysWMinfo = ^PSDL_SysWMinfo; PSDL_SysWMinfo = ^TSDL_SysWMinfo; TSDL_SysWMinfo = record version: TSDL_version; @@ -271,27 +333,29 @@ Type {$IFDEF SDL_VIDEO_DRIVER_OS2} SDL_SYSWM_OS2: (os2: __WMINFO_OS2); {$ENDIF} + {$IFDEF SDL_VIDEO_DRIVER_KMSDRM} + SDL_SYSWM_KMSDRM: (kmsdrm: __WMINFO_KMSDRM); + {$ENDIF} (* Ensure this union is always 64 bytes (8 64-bit pointers) *) SDL_SYSWM_UNKNOWN: (dummy: array[0..63] of Byte); end; -{* Function prototypes *} (** - * \brief This function allows access to driver-dependent window information. + * Get driver-specific information about a window. + * + * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo. * - * \param window The window about which information is being requested - * \param info This structure must be initialized with the SDL version, and is - * then filled in with information about the given window. + * The caller must initialize the `info` structure's version by using + * `SDL_VERSION(&info.version)`, and then this function will fill in the rest + * of the structure with information about the given window. * - * \return SDL_TRUE if the function is implemented and the version member of - * the \c info struct is valid, SDL_FALSE otherwise. + * \param window the window about which information is being requested + * \param info an SDL_SysWMinfo structure filled in with window information + * \returns SDL_TRUE if the function is implemented and the `version` member + * of the `info` struct is valid, or SDL_FALSE if the information + * could not be retrieved; call SDL_GetError() for more information. * - * You typically use this function like this: - * \code - * SDL_SysWMinfo info; - * SDL_VERSION(&info.version); - * if ( SDL_GetWindowWMInfo(window, &info) ) { ... } - * \endcode + * \since This function is available since SDL 2.0.0. *) -Function SDL_GetWindowWMInfo(window:PSDL_Window; info : PSDL_SysWMinfo):TSDL_bool; cdecl; +function SDL_GetWindowWMInfo(window: PSDL_Window; info: PSDL_SysWMinfo): TSDL_bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowWMInfo' {$ENDIF} {$ENDIF}; diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 9536f043..bd27ec4e 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -1,16 +1,25 @@ // based on "sdl_thread.h" +{** + * \file SDL_thread.h + * + * Header for the SDL thread management routines. + *} + {* The SDL thread structure, defined in SDL_thread.c *} -{ TODO : Update this file } type + PSDL_Thread = type Pointer; {* The SDL thread ID *} + PPSDL_threadID = ^PSDL_threadID; + PSDL_threadID = ^TSDL_threadID; TSDL_threadID = culong; {* Thread local storage ID, 0 is the invalid ID *} + PPSDL_TLSID = ^PSDL_TLSID; + PSDL_TLSID = ^TSDL_TLSID; TSDL_TLSID = cuint; - {** * The SDL thread priority. * @@ -21,27 +30,28 @@ type * * \note On many systems you require special privileges to set high or time critical priority. *} - TSDL_ThreadPriority = (SDL_THREAD_PRIORITY_LOW, - SDL_THREAD_PRIORITY_NORMAL, - SDL_THREAD_PRIORITY_HIGH, - SDL_THREAD_PRIORITY_TIME_CRITICAL); +type + PPSDL_ThreadPriority = ^PSDL_ThreadPriority; + PSDL_ThreadPriority = ^TSDL_ThreadPriority; + TSDL_ThreadPriority = cint; - {* The function passed to SDL_CreateThread() - It is passed a void* user context parameter and returns an int. - *} +const + SDL_THREAD_PRIORITY_LOW = TSDL_ThreadPriority(0); + SDL_THREAD_PRIORITY_NORMAL = TSDL_ThreadPriority(1); + SDL_THREAD_PRIORITY_HIGH = TSDL_ThreadPriority(2); + SDL_THREAD_PRIORITY_TIME_CRITICAL = TSDL_ThreadPriority(3); + + {** + * The function passed to SDL_CreateThread(). + * + * \param data what was passed as `data` to SDL_CreateThread() + * \returns a value that can be reported through SDL_WaitThread(). + *} +type + PPSDL_ThreadFunction = ^PSDL_ThreadFunction; PSDL_ThreadFunction = ^TSDL_ThreadFunction; TSDL_ThreadFunction = function(data: Pointer): cint; cdecl; - PSDL_Thread = ^TSDL_Thread; - TSDL_Thread = record - threadid: TSDL_ThreadID; - handle: THandle; - status: cint32; - errbuf: TSDL_Error; - name: PAnsiChar; - data: Pointer; - end; - {$IFDEF WINDOWS} {** * SDL_thread.h @@ -66,27 +76,55 @@ type {$DEFINE SDL_PASSED_BEGINTHREAD_ENDTHREAD} type - {$IFNDEF DELPHI16UP} - TThreadID = Cardinal; + { SDL2-for-Pascal: #todo : Needed? } + {$IFNDEF FPC} + {$IFNDEF DELPHI16UP} + TThreadID = Cardinal; + {$ENDIF} {$ENDIF} - TpfnSDL_CurrentBeginThread = function(SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; Parameter: Pointer; CreationFlags: LongWord; var ThreadId: TThreadID): cint; + { SDL2-for-Pascal #todo : Explanation needed } + TpfnSDL_CurrentBeginThread = function( + SecurityAttributes: Pointer; StackSize: cuint; ThreadFunc: TThreadFunc; + Parameter: Pointer {arg}; CreationFlags: cuint; var ThreadId: TThreadID {threadID}): cuintptr_t; cdecl; + + TpfnSDL_CurrentEndThread = procedure(code: cuint); cdecl; - TpfnSDL_CurrentEndThread = procedure(ExitCode: cint); - {** - * Create a thread. - *} function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; - data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF}; + data: Pointer; + pfnBeginThread: TpfnSDL_CurrentBeginThread; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; + external SDL_LibName; - {** - * Create a thread. - *} +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; + name: PAnsiChar; const stacksize: csize_t; data: Pointer; + pfnBeginThread: TpfnSDL_CurrentBeginThread; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; + external SDL_LibName; + +{ SDL2-For-Pascal: #note : In the C header are two versions + of these macro functions. One for SDL's dynamic API and one without. + We can go with this for the moment. Improvement surely possible. } function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; overload; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; + const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; + + +{ SDL2-For-Pascal: #todo : + The OS2 part of SDL_thread.h is not translated, yet. + The ELSE block is covering this right now. Not sure if the + OS2 platform switch is implemented in Delphi. } +//{$ELSEIF OS2} +//{* +// * just like the windows case above: We compile SDL2 +// * into a dll with Watcom's runtime statically linked. +// *} + +{ ... } + {$ELSE} {** @@ -111,123 +149,270 @@ function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF}; +{** + * Create a new thread with a specific stack size. + * + * SDL makes an attempt to report `name` to the system, so that debuggers can + * display it. Not all platforms support this. + * + * Thread naming is a little complicated: Most systems have very small limits + * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual + * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to + * see what happens with your system's debugger. The name should be UTF-8 (but + * using the naming limits of C identifiers is a better bet). There are no + * requirements for thread naming conventions, so long as the string is + * null-terminated UTF-8, but these guidelines are helpful in choosing a name: + * + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for it + * (truncate, etc), but the original string contents will be available from + * SDL_GetThreadName(). + * + * The size (in bytes) of the new stack can be specified. Zero means "use the + * system default" which might be wildly different between platforms. x86 + * Linux generally defaults to eight megabytes, an embedded device might be a + * few kilobytes instead. You generally need to specify a stack that is a + * multiple of the system's page size (in many cases, this is 4 kilobytes, but + * check your system documentation). + * + * In SDL 2.1, stack size will be folded into the original SDL_CreateThread + * function, but for backwards compatibility, this is currently a separate + * function. + * + * \param fn the SDL_ThreadFunction function to call in the new thread + * \param name the name of the thread + * \param stacksize the size, in bytes, to allocate for the new thread stack. + * \param data a pointer that is passed to `fn` + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.9. + * + * \sa SDL_WaitThread + *} +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; + stacksize: csize_t; data: Pointer): PSDL_Thread; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; + + {$ENDIF} {** - * Get the thread name, as it was specified in SDL_CreateThread(). - * This function returns a pointer to a UTF-8 string that names the - * specified thread, or NULL if it doesn't have a name. This is internal - * memory, not to be free()'d by the caller, and remains valid until the - * specified thread is cleaned up by SDL_WaitThread(). - *} -function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF}; + * Get the thread name as it was specified in SDL_CreateThread(). + * + * This is internal memory, not to be freed by the caller, and remains valid + * until the specified thread is cleaned up by SDL_WaitThread(). + * + * \param thread the thread to query + * \returns a pointer to a UTF-8 string that names the specified thread, or + * NULL if it doesn't have a name. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateThread + *} +function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF}; {** - * Get the thread identifier for the current thread. - *} -function SDL_ThreadID: TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF}; + * Get the thread identifier for the current thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * This function also returns a valid thread ID when called from the main + * thread. + * + * \returns the ID of the current thread. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetThreadID + *} +function SDL_ThreadID: TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF}; {** - * Get the thread identifier for the specified thread. - * - * Equivalent to SDL_ThreadID() if the specified thread is NULL. - *} -function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF}; + * Get the thread identifier for the specified thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * \param thread the thread to query + * \returns the ID of the specified thread, or the ID of the current thread if + * `thread` is NULL. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_ThreadID + *} +function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF}; {** - * Set the priority for the current thread - *} -function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF}; + * Set the priority for the current thread. + * + * Note that some platforms will not let you alter the priority (or at least, + * promote the thread to a higher priority) at all, and some require you to be + * an administrator account. Be prepared for this to fail. + * + * \param priority the SDL_ThreadPriority to set + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} +function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF}; {** - * Wait for a thread to finish. - * - * The return code for the thread function is placed in the area - * pointed to by status, if status is not NULL. - *} -procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF}; + * Wait for a thread to finish. + * + * Threads that haven't been detached will remain (as a "zombie") until this + * function cleans them up. Not doing so is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. As + * such, only one thread may call SDL_WaitThread() on another. + * + * The return code for the thread function is placed in the area pointed to by + * `status`, if `status` is not NULL. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not both, or + * behavior is undefined. + * + * It is safe to pass a NULL thread to this function; it is a no-op. + * + * Note that the thread pointer is freed by this function and is not valid + * afterward. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread + * \param status pointer to an integer that will receive the value returned + * from the thread function by its 'return', or NULL to not + * receive such value back. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateThread + * \sa SDL_DetachThread + *} +procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF}; {** - * A thread may be "detached" to signify that it should not remain until - * another thread has called SDL_WaitThread() on it. Detaching a thread - * is useful for long-running threads that nothing needs to synchronize - * with or further manage. When a detached thread is done, it simply - * goes away. - * - * There is no way to recover the return code of a detached thread. If you - * need this, don't detach the thread and instead use SDL_WaitThread(). - * - * Once a thread is detached, you should usually assume the SDL_Thread isn't - * safe to reference again, as it will become invalid immediately upon - * the detached thread's exit, instead of remaining until someone has called - * SDL_WaitThread() to finally clean it up. As such, don't detach the same - * thread more than once. - * - * If a thread has already exited when passed to SDL_DetachThread(), it will - * stop waiting for a call to SDL_WaitThread() and clean up immediately. - * It is not safe to detach a thread that might be used with SDL_WaitThread(). - * - * You may not call SDL_WaitThread() on a thread that has been detached. - * Use either that function or this one, but not both, or behavior is - * undefined. - * - * It is safe to pass NIL to this function; it is a no-op. - *} -procedure SDL_DetachThread(thread:TSDL_Thread); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF}; + * Let a thread clean up on exit without intervention. + * + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread is + * useful for long-running threads that nothing needs to synchronize with or + * further manage. When a detached thread is done, it simply goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon the + * detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is + * not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. Use + * either that function or this one, but not both, or behavior is undefined. + * + * It is safe to pass NULL to this function; it is a no-op. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread + * + * \since This function is available since SDL 2.0.2. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + *} +procedure SDL_DetachThread(thread:PSDL_Thread); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF}; {** - * Create an identifier that is globally visible to all threads but refers to data that is thread-specific. - * - * The newly created thread local storage identifier, or 0 on error - * - * var tls_lock: TSDL_SpinLock; - * thread_local_storage: TSDL_TLSID; - * - * procedure SetMyThreadData(value: Pointer) - * - * if not (thread_local_storage) then - * begin - * SDL_AtomicLock(@tls_lock); - * if (!thread_local_storage) - * thread_local_storage = SDL_TLSCreate(); - * - * SDL_AtomicUnLock(@tls_lock); - * - * SDL_TLSSet(thread_local_storage, value); - * end; - * - * function GetMyThreadData(): Pointer; - * begin - * Result := SDL_TLSGet(thread_local_storage); - * end; - * - * SDL_TLSGet() - * SDL_TLSSet() - *} -function SDL_TLSCreate: TSDL_TLSID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF}; + * Create a piece of thread-local storage. + * + * This creates an identifier that is globally visible to all threads but + * refers to data that is thread-specific. + * + * \returns the newly created thread local storage identifier or 0 on error. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSGet + * \sa SDL_TLSSet + *} +function SDL_TLSCreate: TSDL_TLSID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF}; {** - * Get the value associated with a thread local storage ID for the current thread. - * - * id The thread local storage ID - * - * The value associated with the ID for the current thread, or NULL if no value has been set. - * - * SDL_TLSCreate() - * SDL_TLSSet() - *} -function SDL_TLSGet(id: TSDL_TLSID): Pointer cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; + * Get the current thread's value associated with a thread local storage ID. + * + * \param id the thread local storage ID + * \returns the value associated with the ID for the current thread or NULL if + * no value has been set; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSCreate + * \sa SDL_TLSSet + *} +function SDL_TLSGet(id: TSDL_TLSID): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; + +type + { SDL2-For-Pascal: This function pointer is introduced to specifiy the + destructor pointer in the SDL_TLSSet function + according to C headers. + + The TTLSDestructor type itself is not defined + by the original SDL2 headers. } + TTLSDestructor = procedure(value: Pointer); cdecl; {** - * Set the value associated with a thread local storage ID for the current thread. - * - * id The thread local storage ID - * value The value to associate with the ID for the current thread - * destructor_ A function called when the thread exits, to free the value. - * - * 0 on success, -1 on error - * - * SDL_TLSCreate() - * SDL_TLSGet() - *} -function SDL_TLSSet(id: TSDL_TLSID; value: Pointer; destructor_: Pointer): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF}; + * Set the current thread's value associated with a thread local storage ID. + * + * The function prototype for `destructor` is: + * + * ```c + * void destructor(void *value) + * ``` + * + * where its parameter `value` is what was passed as `value` to SDL_TLSSet(). + * + * \param id the thread local storage ID + * \param value the value to associate with the ID for the current thread + * \param destructor a function called when the thread exits, to free the + * value + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSCreate + * \sa SDL_TLSGet + *} +function SDL_TLSSet(id: TSDL_TLSID; const value: Pointer; destructor_: TTLSDestructor): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF}; + +{** + * Cleanup all TLS data for this thread. + * + * \since This function is available since SDL 2.0.16. + *} +procedure SDL_TLSCleanup; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCleanup' {$ENDIF} {$ENDIF}; + diff --git a/units/sdltimer.inc b/units/sdltimer.inc index 1874b2c0..ea336c91 100644 --- a/units/sdltimer.inc +++ b/units/sdltimer.inc @@ -59,11 +59,15 @@ type * passed in, the periodic alarm continues, otherwise a new alarm is * scheduled. If the callback returns 0, the periodic alarm is cancelled. *} + PPSDL_TimerCallback = ^PSDL_TimerCallback; + PSDL_TimerCallback = ^TSDL_TimerCallback; TSDL_TimerCallback = function(interval: cuint32; param: Pointer): cuint32; cdecl; {** * Definition of the timer ID type. *} + PPSDL_TimerID = ^PSDL_TimerID; + PSDL_TimerID = ^TSDL_TimerID; TSDL_TimerID = cint; {** diff --git a/units/sdltouch.inc b/units/sdltouch.inc index d1e81fbe..bcb1079f 100644 --- a/units/sdltouch.inc +++ b/units/sdltouch.inc @@ -1,12 +1,26 @@ //from "sdl_touch.h" type + PPSDL_TouchID = ^PSDL_TouchID; PSDL_TouchID = ^TSDL_TouchID; TSDL_TouchID = type cint64; + PPSDL_FingerID = ^PSDL_FingerID; PSDL_FingerID = ^TSDL_FingerID; TSDL_FingerID = type cint64; + PPSDL_TouchDeviceType = ^PSDL_TouchDeviceType; + PSDL_TouchDeviceType = ^TSDL_TouchDeviceType; + TSDL_TouchDeviceType = type cint; + +const + SDL_TOUCH_DEVICE_INVALID = TSDL_TouchDeviceType(-1); + SDL_TOUCH_DEVICE_DIRECT = TSDL_TouchDeviceType(0); {* touch screen with window-relative coordinates *} + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE = TSDL_TouchDeviceType(1); {* trackpad with absolute device coordinates *} + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE = TSDL_TouchDeviceType(2); {* trackpad with relative device coordinates *} + +type + PPSDL_Finger = ^PSDL_Finger; PSDL_Finger = ^TSDL_Finger; TSDL_Finger = record id: TSDL_FingerID; @@ -15,29 +29,52 @@ type pressure: cfloat; end; -{* Used as the device ID for mouse events simulated with touch input *} const + {* Used as the device ID for mouse events simulated with touch input *} SDL_TOUCH_MOUSEID = cuint32(-1); + {* Used as the SDL_TouchID for touch events simulated with mouse input *} + SDL_MOUSE_TOUCHID = TSDL_TouchID(-1); {* Function prototypes *} {** * Get the number of registered touch devices. *} -function SDL_GetNumTouchDevices: cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumTouchDevices' {$ENDIF} {$ENDIF}; +function SDL_GetNumTouchDevices(): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumTouchDevices' {$ENDIF} {$ENDIF}; {** * Get the touch ID with the given index, or 0 if the index is invalid. *} -function SDL_GetTouchDevice(index: cint32): TSDL_TouchID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDevice' {$ENDIF} {$ENDIF}; +function SDL_GetTouchDevice(index: cint): TSDL_TouchID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDevice' {$ENDIF} {$ENDIF}; + +{** + * Get the touch device name as reported from the driver, + * or NIL if the index is invalid. + * + * \since This function is available since SDL 2.0.22. + *} +function SDL_GetTouchName(index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchName' {$ENDIF} {$ENDIF}; + +{** + * Get the type of the given touch device. + * + * \since This function is available since SDL 2.0.10. + *} +function SDL_GetTouchDeviceType(touchID: TSDL_TouchID): TSDL_TouchDeviceType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDeviceType' {$ENDIF} {$ENDIF}; {** * Get the number of active fingers for a given touch device. *} -function SDL_GetNumTouchFingers(touchID: TSDL_TouchID): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumTouchFingers' {$ENDIF} {$ENDIF}; +function SDL_GetNumTouchFingers(touchID: TSDL_TouchID): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumTouchFingers' {$ENDIF} {$ENDIF}; {** * Get the finger object of the given touch, with the given index. *} -function SDL_GetTouchFinger(touchID: TSDL_TouchID; index: cint32): PSDL_Finger cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchFinger' {$ENDIF} {$ENDIF}; +function SDL_GetTouchFinger(touchID: TSDL_TouchID; index: cint): PSDL_Finger; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchFinger' {$ENDIF} {$ENDIF}; diff --git a/units/sdlversion.inc b/units/sdlversion.inc index f97ada33..a187840c 100644 --- a/units/sdlversion.inc +++ b/units/sdlversion.inc @@ -19,6 +19,7 @@ * SDL_GetVersion *} type + PPSDL_Version = ^PSDL_Version; PSDL_Version = ^TSDL_Version; TSDL_Version = record major, {**< major version *} diff --git a/units/sdlvideo.inc b/units/sdlvideo.inc index c934191d..9c39010e 100644 --- a/units/sdlvideo.inc +++ b/units/sdlvideo.inc @@ -1,96 +1,9 @@ -//from "sdl_video.h" and "sdl_sysvideo.h" and "sdl_shape.h" +// from "sdl_video.h" -{ ATTENTION Conv.: - The SDL_HitTestResult-Enum. and the SDL_HitTest func. are shifted before - TSDL_Window decl. because it need this. - - Since the HitTest constants would break Pascal's - forward declaration rules, it has to be above - forward declaration of TSDL_Window. - -} - - {** - * \brief Possible return values from the SDL_HitTest callback. - * - * \sa SDL_HitTest - *} - type - TSDL_HitTestResult = type Integer; - - const - SDL_HITTEST_NORMAL = TSDL_HitTestResult(0); {**< Region is normal. No special properties. *} - SDL_HITTEST_DRAGGABLE = TSDL_HitTestResult(1); {**< Region can drag entire window. *} - SDL_HITTEST_RESIZE_TOPLEFT = TSDL_HitTestResult(2); - SDL_HITTEST_RESIZE_TOP = TSDL_HitTestResult(3); - SDL_HITTEST_RESIZE_TOPRIGHT = TSDL_HitTestResult(4); - SDL_HITTEST_RESIZE_RIGHT = TSDL_HitTestResult(5); - SDL_HITTEST_RESIZE_BOTTOMRIGHT = TSDL_HitTestResult(6); - SDL_HITTEST_RESIZE_BOTTOM = TSDL_HitTestResult(7); - SDL_HITTEST_RESIZE_BOTTOMLEFT = TSDL_HitTestResult(8); - SDL_HITTEST_RESIZE_LEFT = TSDL_HitTestResult(9); - -{ Conv.: Important forward declaration of SDL_Window. } type PPSDL_Window = ^PSDL_Window; - PSDL_Window = ^TSDL_Window; - - {** - * \brief Callback used for hit-testing. - * - * \sa SDL_SetWindowHitTest - *} -TSDL_HitTest = function(win: PSDL_Window; const area: PSDL_Point; data: Pointer): TSDL_HitTestResult; cdecl; - -{ ATTENTION Conv.: - - The following declarations are from SDL_sysvideo.h. - - Remark: The way SDL_video.h and SDL_sysvideo.h are intertwisted - it is best to keep them both in sdlvideo.inc because - Pascal has more strict rules regarding forward declarations. - -} - - {* Define the SDL window-shaper structure *} - PSDL_WindowShaper = ^TSDL_WindowShaper; - TSDL_WindowShaper = record - {* The window associated with the shaper *} - window: PSDL_Window; - - {* The user's specified coordinates for the window, for once we give it a shape. *} - userx,usery: cuint32; - - {* The parameters for shape calculation. *} - mode: TSDL_WindowShapeMode; - - {* Has this window been assigned a shape? *} - hasshape: TSDL_Bool; - - driverdata: Pointer; - end; - - {* Define the SDL shape driver structure *} - PSDL_ShapeDriver = ^TSDL_ShapeDriver; - TSDL_ShapeDriver = record - CreateShaper: function(window: PSDL_Window): PSDL_WindowShaper; cdecl; - SetWindowShaper: function(shaper: PSDL_WindowShaper; shape: PSDL_Surface; shape_mode: PSDL_WindowShapeMode): cint; cdecl; - ResizeWindowShape: function(window: PSDL_Window): cint; cdecl; - end; - - PSDL_WindowUserData = ^TSDL_WindowUserData; - TSDL_WindowUserData = record - name: PAnsiChar; - data: Pointer; - next: PSDL_WindowUserData; - end; - -{ ATTENTION Conv.: - - Everything below this comment is mostly from SDL_video.h. - -} + PSDL_Window = type Pointer; {** * The structure that defines a display mode @@ -103,6 +16,7 @@ TSDL_HitTest = function(win: PSDL_Window; const area: PSDL_Point; data: Pointer) * SDL_SetWindowDisplayMode() * SDL_GetWindowDisplayMode() *} + PPSDL_DisplayMode = ^PSDL_DisplayMode; PSDL_DisplayMode = ^TSDL_DisplayMode; TSDL_DisplayMode = record format: cuint32; {**< pixel format *} @@ -112,156 +26,15 @@ TSDL_HitTest = function(win: PSDL_Window; const area: PSDL_Point; data: Pointer) driverdata: Pointer; {**< driver-specific data, initialize to 0 *} end; - {** - * The type used to identify a window - * - * SDL_CreateWindow() - * SDL_CreateWindowFrom() - * SDL_DestroyWindow() - * SDL_GetWindowData() - * SDL_GetWindowFlags() - * SDL_GetWindowGrab() - * SDL_GetWindowPosition() - * SDL_GetWindowSize() - * SDL_GetWindowTitle() - * SDL_HideWindow() - * SDL_MaximizeWindow() - * SDL_MinimizeWindow() - * SDL_RaiseWindow() - * SDL_RestoreWindow() - * SDL_SetWindowData() - * SDL_SetWindowFullscreen() - * SDL_SetWindowGrab() - * SDL_SetWindowIcon() - * SDL_SetWindowPosition() - * SDL_SetWindowSize() - * SDL_SetWindowBordered() - * SDL_SetWindowTitle() - * SDL_ShowWindow() - *} - - { ATTENTION Conv.: TSDL_Window declaration from SDL_sysvideo.h. } - {* Define the SDL window structure, corresponding to toplevel windows *} - TSDL_Window = record - magic: Pointer; - id: cuint32; - title: PAnsiChar; - icon: PSDL_Surface; - x,y: cint; - w,h: cint; - min_w, min_h: cint; - max_w, max_h: cint; - flags: cuint32; - last_fullscreen_flags: cuint32; - - {* Stored position and size for windowed mode * } - windowed: TSDL_Rect; - - fullscreen_mode: TSDL_DisplayMode; - - opacity: cfloat; - - brightness: cfloat; - gamma: pcuint16; - saved_gamma: pcuint16; {* (just offset into gamma) *} - - surface: PSDL_Surface; - surface_valid: TSDL_Bool; - - is_hiding: TSDL_Bool; - is_destroying: TSDL_Bool; - is_dropping: TSDL_Bool; {* drag/drop in progress, expecting SDL_SendDropComplete(). *} - - shaper: PSDL_WindowShaper; - - hit_test: TSDL_HitTest; - hit_test_data: Pointer; - - data: PSDL_WindowUserData; - - driverdata: Pointer; - - prev: PSDL_Window; - next: PSDL_Window; - end; - - function FULLSCREEN_VISIBLE(W: PSDL_Window): Variant; - -{ Functions from "sdl_shape.h" } - - {** - * Create a window that can be shaped with the specified position, dimensions, and flags. - * - * title The title of the window, in UTF-8 encoding. - * x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or - * ::SDL_WINDOWPOS_UNDEFINED. - * y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or - * ::SDL_WINDOWPOS_UNDEFINED. - * w The width of the window. - * h The height of the window. - * flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following: - * SDL_WINDOW_OPENGL, SDL_WINDOW_INPUT_GRABBED, - * SDL_WINDOW_SHOWN, SDL_WINDOW_RESIZABLE, - * SDL_WINDOW_MAXIMIZED, SDL_WINDOW_MINIMIZED, - * SDL_WINDOW_BORDERLESS is always set, and SDL_WINDOW_FULLSCREEN is always unset. - * - * The window created, or NULL if window creation failed. - * - * SDL_DestroyWindow() - *} -function SDL_CreateShapedWindow(title: PAnsiChar; x: cuint; y: cuint; w: cuint; h: cuint; flags: cuint32): PSDL_Window; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateShapedWindow' {$ENDIF} {$ENDIF}; - - {** - * Return whether the given window is a shaped window. - * - * window The window to query for being shaped. - * - * SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL. - * SDL_CreateShapedWindow - *} -function SDL_IsShapedWindow(window: PSDL_Window): TSDL_Bool; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsShapedWindow' {$ENDIF} {$ENDIF}; - - {** - * Set the shape and parameters of a shaped window. - * - * window The shaped window whose parameters should be set. - * shape A surface encoding the desired shape for the window. - * shape_mode The parameters to set for the shaped window. - * - * 0 on success, SDL_INVALID_SHAPE_ARGUMENT on invalid an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW - * if the SDL_Window* given does not reference a valid shaped window. - * - * SDL_WindowShapeMode - * SDL_GetShapedWindowMode. - *} -function SDL_SetWindowShape(window: PSDL_Window; shape: PSDL_Surface; shape_mode: PSDL_WindowShapeMode): cint; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowShape' {$ENDIF} {$ENDIF}; - - {** - * Get the shape parameters of a shaped window. - * - * window The shaped window whose parameters should be retrieved. - * shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape. - * - * 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode - * data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if - * the SDL_Window* given is a shapeable window currently lacking a shape. - * - * SDL_WindowShapeMode - * SDL_SetWindowShape - *} -function SDL_GetShapedWindowMode(window: PSDL_Window; shape_mode: TSDL_WindowShapeMode): cint; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetShapedWindowMode' {$ENDIF} {$ENDIF}; - {** * The flags on a window * * SDL_GetWindowFlags() *} type - TSDL_WindowFlags = type cuint32; + PPSDL_WindowFlags = ^PSDL_WindowFlags; + PSDL_WindowFlags = ^TSDL_WindowFlags; + TSDL_WindowFlags = type cuint; const SDL_WINDOW_FULLSCREEN = TSDL_WindowFlags($00000001); {**< fullscreen window *} @@ -272,7 +45,7 @@ const SDL_WINDOW_RESIZABLE = TSDL_WindowFlags($00000020); {**< window can be resized *} SDL_WINDOW_MINIMIZED = TSDL_WindowFlags($00000040); {**< window is minimized *} SDL_WINDOW_MAXIMIZED = TSDL_WindowFlags($00000080); {**< window is maximized *} - SDL_WINDOW_INPUT_GRABBED = TSDL_WindowFlags($00000100); {**< window has grabbed input focus *} + SDL_WINDOW_MOUSE_GRABBED = TSDL_WindowFlags($00000100); {**< window has grabbed mouse input *} SDL_WINDOW_INPUT_FOCUS = TSDL_WindowFlags($00000200); {**< window has input focus *} SDL_WINDOW_MOUSE_FOCUS = TSDL_WindowFlags($00000400); {**< window has mouse focus *} SDL_WINDOW_FULLSCREEN_DESKTOP = TSDL_WindowFlags(SDL_WINDOW_FULLSCREEN or $00001000); @@ -280,14 +53,17 @@ const SDL_WINDOW_ALLOW_HIGHDPI = TSDL_WindowFlags($00002000); {**< window should be created in high-DPI mode if supported. On macOS NSHighResolutionCapable must be set true in the application's Info.plist for this to have any effect. *} - SDL_WINDOW_MOUSE_CAPTURE = TSDL_WindowFlags($00004000); {**< window has mouse captured (unrelated to INPUT_GRABBED) *} - SDL_WINDOW_ALWAYS_ON_TOP = TSDL_WindowFlags($00008000); {**< window should always be above others *} - SDL_WINDOW_SKIP_TASKBAR = TSDL_WindowFlags($00010000); {**< window should not be added to the taskbar *} - SDL_WINDOW_UTILITY = TSDL_WindowFlags($00020000); {**< window should be treated as a utility window *} - SDL_WINDOW_TOOLTIP = TSDL_WindowFlags($00040000); {**< window should be treated as a tooltip *} - SDL_WINDOW_POPUP_MENU = TSDL_WindowFlags($00080000); {**< window should be treated as a popup menu *} - SDL_WINDOW_VULKAN = TSDL_WindowFlags($10000000); {**< window usable for Vulkan surface *} - SDL_WINDOW_METAL = TSDL_WindowFlags($20000000); {**< window usable for Metal view *} + SDL_WINDOW_MOUSE_CAPTURE = TSDL_WindowFlags($00004000); {**< window has mouse captured (unrelated to MOUSE_GRABBED) *} + SDL_WINDOW_ALWAYS_ON_TOP = TSDL_WindowFlags($00008000); {**< window should always be above others *} + SDL_WINDOW_SKIP_TASKBAR = TSDL_WindowFlags($00010000); {**< window should not be added to the taskbar *} + SDL_WINDOW_UTILITY = TSDL_WindowFlags($00020000); {**< window should be treated as a utility window *} + SDL_WINDOW_TOOLTIP = TSDL_WindowFlags($00040000); {**< window should be treated as a tooltip *} + SDL_WINDOW_POPUP_MENU = TSDL_WindowFlags($00080000); {**< window should be treated as a popup menu *} + SDL_WINDOW_KEYBOARD_GRABBED = TSDL_WindowFlags($00100000); {**< window has grabbed keyboard input *} + SDL_WINDOW_VULKAN = TSDL_WindowFlags($10000000); {**< window usable for Vulkan surface *} + SDL_WINDOW_METAL = TSDL_WindowFlags($20000000); {**< window usable for Metal view *} + + SDL_WINDOW_INPUT_GRABBED = SDL_WINDOW_MOUSE_GRABBED; {**< equivalent to SDL_WINDOW_MOUSE_GRABBED for compatibility *} {** * Used to indicate that you don't care what the window position is. @@ -310,31 +86,36 @@ function SDL_WINDOWPOS_ISCENTERED(X: Variant): Variant; * Event subtype for window events *} type + PPSDL_WindowEventID = ^PSDL_WindowEventID; PSDL_WindowEventID = ^TSDL_WindowEventID; - TSDL_WindowEventID = type DWord; + TSDL_WindowEventID = type cint; const - SDL_WINDOWEVENT_NONE = TSDL_WindowEventID(0); {**< Never used *} - SDL_WINDOWEVENT_SHOWN = TSDL_WindowEventID(1); {**< Window has been shown *} - SDL_WINDOWEVENT_HIDDEN = TSDL_WindowEventID(2); {**< Window has been hidden *} - SDL_WINDOWEVENT_EXPOSED = TSDL_WindowEventID(3); {**< Window has been exposed and should be redrawn *} - SDL_WINDOWEVENT_MOVED = TSDL_WindowEventID(4); {**< Window has been moved to data1; data2 *} - SDL_WINDOWEVENT_RESIZED = TSDL_WindowEventID(5); {**< Window has been resized to data1xdata2 *} - SDL_WINDOWEVENT_SIZE_CHANGED = TSDL_WindowEventID(6); {**< The window size has changed; either as a result of an API call or through the system or user changing the window size. *} - SDL_WINDOWEVENT_MINIMIZED = TSDL_WindowEventID(7); {**< Window has been minimized *} - SDL_WINDOWEVENT_MAXIMIZED = TSDL_WindowEventID(8); {**< Window has been maximized *} - SDL_WINDOWEVENT_RESTORED = TSDL_WindowEventID(9); {**< Window has been restored to normal size and position *} - SDL_WINDOWEVENT_ENTER = TSDL_WindowEventID(10); {**< Window has gained mouse focus *} - SDL_WINDOWEVENT_LEAVE = TSDL_WindowEventID(11); {**< Window has lost mouse focus *} - SDL_WINDOWEVENT_FOCUS_GAINED = TSDL_WindowEventID(12); {**< Window has gained keyboard focus *} - SDL_WINDOWEVENT_FOCUS_LOST = TSDL_WindowEventID(13); {**< Window has lost keyboard focus *} - SDL_WINDOWEVENT_CLOSE = TSDL_WindowEventID(14); {**< The window manager requests that the window be closed *} - SDL_WINDOWEVENT_TAKE_FOCUS = TSDL_WindowEventID(15); {**< Window is being offered a focus (should SetWindowInputFocus() on itself or a subwindow, or ignore) *} - SDL_WINDOWEVENT_HIT_TEST = TSDL_WindowEventID(16); {**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. *} + SDL_WINDOWEVENT_NONE = TSDL_WindowEventID(0); {**< Never used *} + SDL_WINDOWEVENT_SHOWN = TSDL_WindowEventID(1); {**< Window has been shown *} + SDL_WINDOWEVENT_HIDDEN = TSDL_WindowEventID(2); {**< Window has been hidden *} + SDL_WINDOWEVENT_EXPOSED = TSDL_WindowEventID(3); {**< Window has been exposed and should be redrawn *} + SDL_WINDOWEVENT_MOVED = TSDL_WindowEventID(4); {**< Window has been moved to data1; data2 *} + SDL_WINDOWEVENT_RESIZED = TSDL_WindowEventID(5); {**< Window has been resized to data1xdata2 *} + SDL_WINDOWEVENT_SIZE_CHANGED = TSDL_WindowEventID(6); {**< The window size has changed; either as a result of an API call or through the system or user changing the window size. *} + SDL_WINDOWEVENT_MINIMIZED = TSDL_WindowEventID(7); {**< Window has been minimized *} + SDL_WINDOWEVENT_MAXIMIZED = TSDL_WindowEventID(8); {**< Window has been maximized *} + SDL_WINDOWEVENT_RESTORED = TSDL_WindowEventID(9); {**< Window has been restored to normal size and position *} + SDL_WINDOWEVENT_ENTER = TSDL_WindowEventID(10); {**< Window has gained mouse focus *} + SDL_WINDOWEVENT_LEAVE = TSDL_WindowEventID(11); {**< Window has lost mouse focus *} + SDL_WINDOWEVENT_FOCUS_GAINED = TSDL_WindowEventID(12); {**< Window has gained keyboard focus *} + SDL_WINDOWEVENT_FOCUS_LOST = TSDL_WindowEventID(13); {**< Window has lost keyboard focus *} + SDL_WINDOWEVENT_CLOSE = TSDL_WindowEventID(14); {**< The window manager requests that the window be closed *} + SDL_WINDOWEVENT_TAKE_FOCUS = TSDL_WindowEventID(15); {**< Window is being offered a focus (should SetWindowInputFocus() on itself or a subwindow, or ignore) *} + SDL_WINDOWEVENT_HIT_TEST = TSDL_WindowEventID(16); {**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. *} + SDL_WINDOWEVENT_ICCPROF_CHANGED = TSDL_WindowEventID(17); {**< The ICC profile of the window's display has changed. *} + SDL_WINDOWEVENT_DISPLAY_CHANGED = TSDL_WindowEventID(18); {**< Window has been moved to display data1. *} {** * \brief Event subtype for display events *} type + PPSDL_DisplayEventID = ^PSDL_DisplayEventID; + PSDL_DisplayEventID = ^TSDL_DisplayEventID; TSDL_DisplayEventID = type Integer; const @@ -344,6 +125,8 @@ const SDL_DISPLAYEVENT_DISCONNECTED = TSDL_DisplayEventID(3); {**< Display has been removed from the system *} type + PPSDL_DisplayOrientation = ^PSDL_DisplayOrientation; + PSDL_DisplayOrientation = ^TSDL_DisplayOrientation; TSDL_DisplayOrientation = type Integer; const @@ -353,16 +136,33 @@ const SDL_ORIENTATION_PORTRAIT = TSDL_DisplayOrientation(3); {**< The display is in portrait mode *} SDL_ORIENTATION_PORTRAIT_FLIPPED = TSDL_DisplayOrientation(4); {**< The display is in portrait mode, upside down *} + {** + * \brief Window flash operation + *} +type + PPSDL_FlashOperation = ^PSDL_FlashOperation; + PSDL_FlashOperation = ^TSDL_FlashOperation; + TSDL_FlashOperation = type Integer; + +const + SDL_FLASH_CANCEL = TSDL_FlashOperation(0); {**< Cancel any window flash state *} + SDL_FLASH_BRIEFLY = TSDL_FlashOperation(1); {**< Flash the window briefly to get attention *} + SDL_FLASH_UNTIL_FOCUSED = TSDL_FlashOperation(2); {**< Flash the window until it gets focus *} + {** * An opaque handle to an OpenGL context. *} type + PPSDL_GLContext = ^PSDL_GLContext; + PSDL_GLContext = ^TSDL_GLContext; TSDL_GLContext = Pointer; {** * OpenGL configuration attributes *} type + PPSDL_GLattr = ^PSDL_GLattr; + PSDL_GLattr = ^TSDL_GLattr; TSDL_GLattr = type Integer; const @@ -393,8 +193,11 @@ const SDL_GL_CONTEXT_RELEASE_BEHAVIOR = TSDL_GLattr(24); SDL_GL_CONTEXT_RESET_NOTIFICATION = TSDL_GLattr(25); SDL_GL_CONTEXT_NO_ERROR = TSDL_GLattr(26); + SDL_GL_FLOATBUFFERS = TSDL_GLattr(27); type + PPSDL_GLprofile = ^PSDL_GLprofile; + PSDL_GLprofile = ^TSDL_GLprofile; TSDL_GLprofile = type Integer; const @@ -403,6 +206,8 @@ const SDL_GL_CONTEXT_PROFILE_ES = TSDL_GLprofile($0004); type + PPSDL_GLcontextFlag = ^PSDL_GLcontextFlag; + PSDL_GLcontextFlag = ^TSDL_GLcontextFlag; TSDL_GLcontextFlag = type Integer; const @@ -412,6 +217,8 @@ const SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = TSDL_GLcontextFlag($0008); type + PPSDL_GLcontextReleaseFlag = ^PSDL_GLcontextReleaseFlag; + PSDL_GLcontextReleaseFlag = ^TSDL_GLcontextReleaseFlag; TSDL_GLcontextReleaseFlag = type Integer; const @@ -419,6 +226,8 @@ const SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = TSDL_GLcontextReleaseFlag($0001); type + PPSDL_GLContextResetNotification = ^PSDL_GLContextResetNotification; + PSDL_GLContextResetNotification = ^TSDL_GLContextResetNotification; TSDL_GLContextResetNotification = type Integer; const @@ -561,8 +370,8 @@ function SDL_GetDisplayDPI(displayIndex: cint; ddpi, hdpi, vdpi: pcfloat): cint; * * \sa SDL_GetNumVideoDisplays() *} -function SDL_DisplayOrientation(displayIndex: cint): TSDL_DisplayOrientation; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DisplayOrientation' {$ENDIF} {$ENDIF}; +function SDL_GetDisplayOrientation(displayIndex: cint): TSDL_DisplayOrientation; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDisplayOrientation' {$ENDIF} {$ENDIF}; {** * Returns the number of available display modes. @@ -626,6 +435,37 @@ function SDL_GetCurrentDisplayMode(displayIndex: cint; mode: PSDL_DisplayMode): function SDL_GetClosestDisplayMode(displayIndex: cint; const mode: PSDL_DisplayMode; closest: PSDL_DisplayMode): PSDL_DisplayMode; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetClosestDisplayMode' {$ENDIF} {$ENDIF}; +{** + * Get the index of the display containing a point + * + * \param point the point to query + * \returns the index of the display containing the point or a negative error + * code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetNumVideoDisplays + *} +function SDL_GetPointDisplayIndex(const point: PSDL_Point): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPointDisplayIndex' {$ENDIF} {$ENDIF}; + +{** + * Get the index of the display primarily containing a rect + * + * \param rect the rect to query + * \returns the index of the display entirely containing the rect or closest + * to the center of the rect on success or a negative error code on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.24.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetNumVideoDisplays + *} +function SDL_GetRectDisplayIndex(const rect: PSDL_Rect): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRectDisplayIndex' {$ENDIF} {$ENDIF}; + {** * Get the display index associated with a window. * @@ -664,6 +504,21 @@ function SDL_SetWindowDisplayMode(window: PSDL_Window; const mode: PSDL_DisplayM function SDL_GetWindowDisplayMode(window: PSDL_Window; mode: PSDL_DisplayMode): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowDisplayMode' {$ENDIF} {$ENDIF}; +{** + * Get the raw ICC profile data for the screen the window is currently on. + * + * Data returned should be freed with SDL_free(). + * + * \param window the window to query + * \param size the size of the ICC profile + * \returns the raw ICC profile data on success or NIL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.18. + *} +function SDL_GetWindowICCProfile(window: PSDL_Window; size: pcsize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowICCProfile' {$ENDIF} {$ENDIF}; + {** * Get the pixel format associated with the window. *} @@ -883,6 +738,27 @@ procedure SDL_GetWindowSize(window: PSDL_Window; w: pcint; h: pcint); cdecl; function SDL_GetWindowBordersSize(window: PSDL_Window; top, left, bottom, right: pcint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowBordersSize' {$ENDIF} {$ENDIF}; + {** + * Get the size of a window in pixels. + * + * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI + * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a + * platform with high-DPI support (Apple calls this "Retina"), and not + * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. + * + * \param window the window from which the drawable size should be queried + * \param w a pointer to variable for storing the width in pixels, may be NIL + * \param h a pointer to variable for storing the height in pixels, may be + * NIL + * + * \since This function is available since SDL 2.26.0. + * + * \sa SDL_CreateWindow + * \sa SDL_GetWindowSize + *} +procedure SDL_GetWindowSizeInPixels(window: PSDL_Window; w, h: pcuint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowSizeInPixels' {$ENDIF} {$ENDIF}; + {** * Set the minimum size of a window's client area. * @@ -976,6 +852,23 @@ procedure SDL_SetWindowBordered(window: PSDL_Window; bordered: TSDL_Bool); cdecl procedure SDL_SetWindowResizable(window: PSDL_Window; resizable: TSDL_Bool); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowResizable' {$ENDIF} {$ENDIF}; +{** + * Set the window to always be above the others. + * + * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This + * will bring the window to the front and keep the window above the rest. + * + * \param window The window of which to change the always on top state + * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to + * disable + * + * \since This function is available since SDL 2.0.16. + * + * \sa SDL_GetWindowFlags + *} +procedure SDL_SetWindowAlwaysOnTop(window: PSDL_Window; on_top: TSDL_Bool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowAlwaysOnTop' {$ENDIF} {$ENDIF}; + {** * Show a window. * @@ -1041,6 +934,19 @@ procedure SDL_RestoreWindow(window: PSDL_Window); cdecl; function SDL_SetWindowFullscreen(window: PSDL_Window; flags: TSDL_WindowFlags): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowFullscreen' {$ENDIF} {$ENDIF}; + {** + * Return whether the window has a surface associated with it. + * + * \returns SDL_TRUE if there is a surface associated with the window, or + * SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.28.0. + * + * \sa SDL_GetWindowSurface + *} +function SDL_HasWindowSurface(window: PSDL_Window): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasWindowSurface' {$ENDIF} {$ENDIF}; + {** * Get the SDL surface associated with the window. * @@ -1082,6 +988,21 @@ function SDL_UpdateWindowSurface(window: PSDL_Window): cint; cdecl; function SDL_UpdateWindowSurfaceRects(window: PSDL_Window; rects: PSDL_Rect; numrects: cint): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UpdateWindowSurfaceRects' {$ENDIF} {$ENDIF}; + {** + * Destroy the surface associated with the window. + * + * \param window the window to update + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.28.0. + * + * \sa SDL_GetWindowSurface + * \sa SDL_HasWindowSurface + *} +function SDL_DestroyWindowSurface(window: PSDL_Window): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyWindowSurface' {$ENDIF} {$ENDIF}; + {** * Set a window's input grab mode. * @@ -1104,6 +1025,94 @@ procedure SDL_SetWindowGrab(window: PSDL_Window; grabbed: TSDL_Bool); cdecl; function SDL_GetWindowGrab(window: PSDL_Window): TSDL_Bool; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowGrab' {$ENDIF} {$ENDIF}; +{** + * Set a window's keyboard grab mode. + * + * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or + * the Meta/Super key. Note that not all system keyboard shortcuts can be + * captured by applications (one example is Ctrl+Alt+Del on Windows). + * + * This is primarily intended for specialized applications such as VNC clients + * or VM frontends. Normal games should not use keyboard grab. + * + * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the + * window is full-screen to ensure the user is not trapped in your + * application. If you have a custom keyboard shortcut to exit fullscreen + * mode, you may suppress this behavior with + * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`. + * + * If the caller enables a grab while another window is currently grabbed, the + * other window loses its grab in favor of the caller's window. + * + * \param window The window for which the keyboard grab mode should be set. + * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release. + * + * \since This function is available since SDL 2.0.16. + * + * \sa SDL_GetWindowKeyboardGrab + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowGrab + *} +procedure SDL_SetWindowKeyboardGrab(window: PSDL_Window; grabbed: TSDL_Bool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowKeyboardGrab' {$ENDIF} {$ENDIF}; + + {** + * Get a window's keyboard grab mode. + * + * Returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * + * SDL_SetWindowKeyboardGrab() + *} + +function SDL_GetWindowKeyboardGrab(window: PSDL_Window): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowKeyboardGrab' {$ENDIF} {$ENDIF}; + + {** + * Set a window's mouse grab mode. + * + * window The window for which the mouse grab mode should be set. + * grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release. + * + * SDL_GetWindowMouseGrab() + *} + +procedure SDL_SetWindowMouseGrab(window: PSDL_Window; grabbed: TSDL_Bool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowMouseGrab' {$ENDIF} {$ENDIF}; + + {** + * Get a window's mouse grab mode. + * + * Returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * + * SDL_SetWindowMouseGrab() + *} + +function SDL_GetWindowMouseGrab(window: PSDL_Window): TSDL_Bool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowMouseGrab' {$ENDIF} {$ENDIF}; + + {** + * Confines the cursor to the specified area of a window. + * + * window The window that will be associated with the barrier. + * rect A rectangle area in window-relative coordinates. If NULL the barrier for the specified window will be destroyed. + * + * SDL_GetWindowMouseRect() + *} + +procedure SDL_SetWindowMouseRect(window: PSDL_Window; rect: PSDL_Rect); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowMouseRect' {$ENDIF} {$ENDIF}; + + {** + * Get the mouse confinement rectangle of a window. + * + * Returns A pointer to the mouse confinement rectangle of a window, or NULL if there isn't one. + * + * SDL_SetWindowMouseRect() + *} + +function SDL_GetWindowMouseRect(window: PSDL_Window): PSDL_Rect; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowMouseRect' {$ENDIF} {$ENDIF}; + {** * \brief Get the window that currently has an input grab enabled. * @@ -1232,12 +1241,37 @@ function SDL_SetWindowGammaRamp(window: PSDL_Window; const red: pcuint16; const function SDL_GetWindowGammaRamp(window: PSDL_Window; red: pcuint16; green: pcuint16; blue: pcuint16): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowGammaRamp' {$ENDIF} {$ENDIF}; - { ATTENTION Conv.: +{** + * \brief Possible return values from the SDL_HitTest callback. + * + * \sa SDL_HitTest + *} +type + PPSDL_HitTestResult = ^PSDL_HitTestResult; + PSDL_HitTestResult = ^TSDL_HitTestResult; + TSDL_HitTestResult = type Integer; - The SDL_HitTestResult-Enum. and the SDL_HitTest func. are shifted before - TSDL_Window decl. because it need this. +const + SDL_HITTEST_NORMAL = TSDL_HitTestResult(0); {**< Region is normal. No special properties. *} + SDL_HITTEST_DRAGGABLE = TSDL_HitTestResult(1); {**< Region can drag entire window. *} + SDL_HITTEST_RESIZE_TOPLEFT = TSDL_HitTestResult(2); + SDL_HITTEST_RESIZE_TOP = TSDL_HitTestResult(3); + SDL_HITTEST_RESIZE_TOPRIGHT = TSDL_HitTestResult(4); + SDL_HITTEST_RESIZE_RIGHT = TSDL_HitTestResult(5); + SDL_HITTEST_RESIZE_BOTTOMRIGHT = TSDL_HitTestResult(6); + SDL_HITTEST_RESIZE_BOTTOM = TSDL_HitTestResult(7); + SDL_HITTEST_RESIZE_BOTTOMLEFT = TSDL_HitTestResult(8); + SDL_HITTEST_RESIZE_LEFT = TSDL_HitTestResult(9); - } + {** + * \brief Callback used for hit-testing. + * + * \sa SDL_SetWindowHitTest + *} +type + PPSDL_HitTest = ^PSDL_HitTest; + PSDL_HitTest = ^TSDL_HitTest; + TSDL_HitTest = function(win: PSDL_Window; const area: PSDL_Point; data: Pointer): TSDL_HitTestResult; cdecl; {** * \brief Provide a callback that decides if a window region has special properties. @@ -1279,6 +1313,19 @@ function SDL_GetWindowGammaRamp(window: PSDL_Window; red: pcuint16; green: pcuin function SDL_SetWindowHitTest(window: PSDL_Window; callback: TSDL_HitTest; callback_data: Pointer): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowHitTest' {$ENDIF} {$ENDIF}; + {** + * Request a window to demand attention from the user. + * + * \param window the window to be flashed + * \param operation the flash operation + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.16. + *} +function SDL_FlashWindow(window: PSDL_Window; operation: TSDL_FlashOperation): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FlashWindow' {$ENDIF} {$ENDIF}; + {** * Destroy a window. *}