Tweaking documentation for the SDL 3.0 preview release

This commit is contained in:
Sam Lantinga 2024-03-24 06:13:19 -07:00
parent 9e460ce6a6
commit a20eec1415
5 changed files with 55 additions and 77 deletions

View File

@ -5,9 +5,8 @@ https://www.libsdl.org/
Simple DirectMedia Layer is a cross-platform development library designed Simple DirectMedia Layer is a cross-platform development library designed
to provide low level access to audio, keyboard, mouse, joystick, and graphics to provide low level access to audio, keyboard, mouse, joystick, and graphics
hardware via OpenGL and Direct3D. It is used by video playback software, hardware. It is used by video playback software, emulators, and popular games
emulators, and popular games including Valve's award winning catalog including Valve's award winning catalog and many Humble Bundle games.
and many Humble Bundle games.
More extensive documentation is available in the docs directory, starting More extensive documentation is available in the docs directory, starting
with [README.md](docs/README.md). If you are migrating to SDL 3.0 from SDL 2.0, with [README.md](docs/README.md). If you are migrating to SDL 3.0 from SDL 2.0,

View File

@ -2,34 +2,32 @@
This is a list of major changes in SDL's version history. This is a list of major changes in SDL's version history.
--------------------------------------------------------------------------- ---------------------------------------------------------------------------
3.2.0: 3.1.0:
--------------------------------------------------------------------------- ---------------------------------------------------------------------------
General: This is a preview release of the new SDL 3.0 API.
* SDL headers should now be included as `#include <SDL3/SDL.h>`
* Many functions and symbols have changed since SDL 2.0, see the [migration guide](docs/README-migration.md) for details The ABI hasn't been locked down yet, but it's fairly stable and feedback is welcome!
* The preprocessor symbol __MACOSX__ has been renamed SDL_PLATFORM_MACOS
* The preprocessor symbol __IPHONEOS__ has been renamed SDL_PLATFORM_IOS Check out [migration guide](docs/README-migration.md) for details on API changes since SDL 2.0, and tips on transitioning your code from SDL2 code to SDL3.
* SDL_stdinc.h no longer includes stdio.h, stdlib.h, etc., it only provides the SDL C runtime functionality
* SDL_intrin.h now includes the intrinsics headers that were in SDL_cpuinfo.h There have been too many changes to list them all, but here are some of the highlights:
* Added SDL_GetSystemTheme() to return whether the system is using a dark or light color theme, and SDL_EVENT_SYSTEM_THEME_CHANGED is sent when this changes * The API has been significantly reworked to be easier to use and more consistent
* Added SDL_GetDisplays() to return a list of connected displays * The 2D rendering API now has support for more advanced colorspaces and HDR rendering
* Added SDL_GetPrimaryDisplay() to get the instance ID of the primary display * The 2D rendering API now has a Vulkan backend
* Added SDL_GetWindowParent() to get the parent of popup windows * An example of hardware accelerated video playback using ffmpeg has been added in test/testffmpeg.c
* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace SDL_CreateRGBSurface*(), and can also be used to create YUV surfaces * The shaped window API has been replaced with transparent windows
* Added SDL_FlipSurface() to flip a surface vertically or horizontally * Time and date functions have been added in SDL_time.h
* Added SDL_GetJoysticks(), SDL_GetJoystickInstanceName(), SDL_GetJoystickInstancePath(), SDL_GetJoystickInstancePlayerIndex(), SDL_GetJoystickInstanceGUID(), SDL_GetJoystickInstanceVendor(), SDL_GetJoystickInstanceProduct(), SDL_GetJoystickInstanceProductVersion(), and SDL_GetJoystickInstanceType() to directly query the list of available joysticks * Support for webcam video capture has been added in SDL_camera.h
* Added SDL_GetGamepads(), SDL_GetGamepadInstanceName(), SDL_GetGamepadInstancePath(), SDL_GetGamepadInstancePlayerIndex(), SDL_GetGamepadInstanceGUID(), SDL_GetGamepadInstanceVendor(), SDL_GetGamepadInstanceProduct(), SDL_GetGamepadInstanceProductVersion(), and SDL_GetGamepadInstanceType() to directly query the list of available gamepads * Support for handling pens and tablets has been added in SDL_pen.h
* Added SDL_GetSensors(), SDL_GetSensorInstanceName(), SDL_GetSensorInstanceType(), and SDL_GetSensorInstanceNonPortableType() to directly query the list of available sensors * Support for file open and save dialogs has been added in SDL_dialog.h
* Added SDL_GetJoystickCaps() and SDL_GetGamepadCaps() to get the capabilities of controllers * Cross-platform functions for working with files and directories are available in SDL_filesystem.h
* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro * A cross-platform abstraction for working with user and game data has been added in SDL_storage.h
* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized * Handling of main() has been moved to a header library and an optional callback-based program flow is available
* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support * Support for simple object properties has been added in SDL_properties.h. These properties are available on many SDL objects, and can be used for more advanced functionality.
* The timestamp member of the SDL_Event structure is now in nanoseconds, filled in with the time the event was generated, or the time it was queued if that's not available
* Added SDL_modf() and SDL_modff() to separate the whole and fractional portions of a floating point number Please let us know about issues and feedback at: https://github.com/libsdl-org/SDL/issues
* Added SDL_aligned_alloc() and SDL_aligned_free() to allocate and free memory with a given alignment
* Added SDL_GetRenderVSync() to get vsync of the given renderer The development team is focused on code, moving towards the final release, and we would love volunteers to help improve the documentation. Please send e-mail to slouken@libsdl.org if you'd like to help out!
* Added SDL_PlayAudioDevice() to start audio playback
* Added SDL_ConvertAudioSamples() to convert audio samples from one format to another Finally, a giant thank you to all the people who have contributed code and feedback to the SDL 3.0 improvements!
* Added the hint SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY to control re-creation of Android SDL activity.
* Added the environment variable SDL_LOGGING to control default log output

View File

@ -1,19 +0,0 @@
git
=========
The latest development version of SDL is available via git.
Git allows you to get up-to-the-minute fixes and enhancements;
as a developer works on a source tree, you can use "git" to mirror that
source tree instead of waiting for an official release. Please look
at the Git website ( https://git-scm.com/ ) for more
information on using git, where you can also download software for
macOS, Windows, and Unix systems.
git clone https://github.com/libsdl-org/SDL
If you are building SDL via configure, you will need to run autogen.sh
before running configure.
There is a web interface to the Git repository at:
http://github.com/libsdl-org/SDL/

View File

@ -1,7 +0,0 @@
Mercurial
======
We are no longer hosted in Mercurial. Please see README-git.md for details.
Thanks!

View File

@ -4,9 +4,8 @@ https://www.libsdl.org/
Simple DirectMedia Layer is a cross-platform development library designed Simple DirectMedia Layer is a cross-platform development library designed
to provide low level access to audio, keyboard, mouse, joystick, and graphics to provide low level access to audio, keyboard, mouse, joystick, and graphics
hardware via OpenGL and Direct3D. It is used by video playback software, hardware. It is used by video playback software, emulators, and popular games
emulators, and popular games including Valve's award winning catalog including Valve's award winning catalog and many Humble Bundle games.
and many Humble Bundle games.
SDL officially supports Windows, macOS, Linux, iOS, and Android. SDL officially supports Windows, macOS, Linux, iOS, and Android.
Support for other platforms may be found in the source code. Support for other platforms may be found in the source code.
@ -17,32 +16,40 @@ available for several other languages, including C# and Python.
This library is distributed under the zlib license, which can be found This library is distributed under the zlib license, which can be found
in the file "LICENSE.txt". in the file "LICENSE.txt".
Information on building SDL with CMake is available in [README-cmake.md](README-cmake.md)
The best way to learn how to use SDL is to check out the header files in The best way to learn how to use SDL is to check out the header files in
the "include" subdirectory and the programs in the "test" subdirectory. the "include" subdirectory and the programs in the "test" subdirectory.
The header files and test programs are well commented and always up to date. The header files and test programs are well commented and always up to date.
Information on reporting bugs and contributing is available in [README-contributing.md](README-contributing.md)
More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/) More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/)
- [Android](README-android.md) - [High DPI Support](README-highdpi.md)
- [CMake](README-cmake.md) - [main()](README-main-functions.md)
- [DynAPI](README-dynapi.md)
- [Emscripten](README-emscripten.md)
- [GDK](README-gdk.md)
- [Git](README-git.md)
- [iOS](README-ios.md)
- [Linux](README-linux.md)
- [macOS](README-macos.md)
- [Supported Platforms](README-platforms.md)
- [Porting information](README-porting.md) - [Porting information](README-porting.md)
- [PSP](README-psp.md) - [Migrating from SDL 2.0](README-migration.md)
- [PS2](README-ps2.md) - [Supported Platforms](README-platforms.md)
- [Raspberry Pi](README-raspberrypi.md)
- [Touch](README-touch.md) - [Touch](README-touch.md)
- [Versions](README-versions.md) - [Versions](README-versions.md)
- [Windows](README-windows.md) - [Visual Studio](README-visualc.md)
- [WinRT](README-winrt.md)
- [Android](README-android.md)
- [Emscripten](README-emscripten.md)
- [iOS](README-ios.md)
- [KMSDRM support on BSD](README-kmsbsd.md)
- [Linux](README-linux.md)
- [macOS](README-macos.md)
- [Nintendo 3DS](README-n3ds.md)
- [PS2](README-ps2.md)
- [PSP](README-psp.md)
- [PSVita](README-vita.md) - [PSVita](README-vita.md)
- [Nokia N-Gage](README-ngage.md) - [Raspberry Pi](README-raspberrypi.md)
- [RISC OS](README-riscos.md)
- [Windows GDK](README-gdk.md)
- [Windows UWP](README-winrt.md)
- [Windows](README-windows.md)
If you need help with the library, or just want to discuss SDL related If you need help with the library, or just want to discuss SDL related
issues, you can join the [SDL Discourse](https://discourse.libsdl.org/), issues, you can join the [SDL Discourse](https://discourse.libsdl.org/),