Repository files navigation

SDL bindings forTypeScript.

Currently working viadeno on Windows, Linux, and mac OS usingFFI (Foreign Function Interface).

• Resembling the C API as much as possible. If someone reads a SDL tutorial (for exampleLazyFoo) then they should be able to easily translate the tutorial to theequivalent in this library.

• Provide utiltiy functions which wrap SDL features into idomatic JavaScript (i.e.Events.asyncIterator).

• Creating a higher level API or Game Framework. This library's only purpose is to expose the SDL API to TypeScript.

This library's version number will match the SDL major and minor version against which it is currently tested. The patchnumber will be specifici to this library. I.E.

sudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-ttf-2.0-0

sudo dnf install SDL2 SDL2_image SDL2_ttf

pacman -S mingw-w64-ucrt-x86_64-SDL2 mingw-w64-ucrt-x86_64-SDL2_image mingw-w64-ucrt-x86_64-SDL2_ttf

You'll need to ensure then that the sysroot (in this case ucrt) is in your path. Assuming the default install locationfor msys2 thenC:\msys64\ucrt64\bin.

brew install sdl2 sdl2_image sdl2_ttf

Located in the directoryexamples/getting-started are a minimal set of files needed to geta project up and running. Copy these files onto your computer and start the project withdeno task start. You shouldsee a window withSDL_ts as the title.

UnlesslibraryPath is specified in theInit functions,SDL_ts will attempt to "find" the SDL shared libraries bydetermining the prefix and file extension appropriate for the operating system and looking in a set of different placesalso based on the operating system. The places where the shared libraries are searched for can be influenced by theenvironment variableSDL_TS_LIBRARY_PATH.

TheInit functions (i.e.SDL_Init) have in theiroptions object alibraryPath property. This property should bea path to the shared library andSDL_ts will make no attempt to guess where the library should be loaded from. Thismeans it's up to the caller of theInit function to account for changes in the name of the library between thedifferent platforms. For example the shared library on Linux is calledlibSDL2.so and Windows it is calledSDL2.dll.There is alib prefix on Linux and on Windows the file extension is.dll instead of.so.

The environmnet variableSDL_TS_LIBRARY_PATH can be used to instruct SDL_ts where the SDL shared libraries should beloaded from. Seedeno.json. All example projects will load the SDL shared libraries from the.libdirectory if it exists.

Per defaultSDL.Init (orIMG.Init orTTF.Init) will load all known functions from the SDL assemblies. This can beproblematic when attempting to run your script on an older version of the SDL assemblies than the version against whichthis library is developed. The Init functions accept an options parameter in which the functions to load can bespecified:

SDL.Init(SDL.InitFlags.VIDEO,{functions:[SDL.Init,SDL.PollEvent,SDL.Quit,// And so on],});

• AllocatableStruct: is aStruct that can be allocated from JavaScript and will be backed by aUint8Array. Theconstructor allows all properties to be set in a few ways.

• OpaqueStruct: is aStruct where no properties are known to JavaScript (C code would also know about the fields)and can only be created by the native side. TheStruct can only be passed back to the native side and usally to afunction that will return information related to theStruct. The best example of this concept isSDL.Window.

• Pointer<T>: represents a pointer to something and is explicitly typed asunknown by SDL_ts.Pointer<T> can onlybe returned from functions and will never be created by the JavaScript side. The concept of pointers can't completelybe hidden when interfacing with SDL but SDL_ts attempts to constrain pointers to a type level concept. SDL_ts willtake care of passing pointers to the native side as part of the marshalling process. SeePointerLike<T>.

• PointerLike<T>: is used only as an input to functions and is used to represent anything to which a pointer can becreated for. This includesPointer<T>,TypedArray(s),Struct(s) andStructArray(s).

• Struct: the JavaScript representation of structs from the native side.Struct(s) are special classes because theirdata is either aPointer<T> or aUint8Array. If theStruct data is aPointer<T> theStruct it was allocatedon the native side and is read only (seeOpaqueStruct). If theStruct data is an instance ofUint8Array it wasallocated on the JavaScript side and can be written to as well as read from (seeAllocatableStruct).

• StructArray: Use theStructArray class to allocate an array onStruct(s). AllStruct(s) in the the array willbe backed by a sharedUint8Array allowing the entire array to be passed to the native side. Normal JavaScript arraysare not guarenteed to be laid out contiguously in memory. TheStruct type passed to the constructor of the arraymust be anAllocatableStruct. AllStruct(s) passed into the the constructor will have their data copied into thesharedUint8Array.

Deno images taken fromhttps://deno.land/artwork.

Thanks to:

• Samip Poudel for the Jurassic deno image.
• Andy Baird for initial MacOS Support.
• Yiheng Wu for struct handling and other bug fixes.