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
to provide low level access to audio, keyboard, mouse, joystick, and graphics
hardware via OpenGL and Direct3D. It is used by video playback software,
emulators, and popular games including Valve's award winning catalog
and many Humble Bundle games.
hardware. It is used by video playback software, emulators, and popular games
including Valve's award winning catalog and many Humble Bundle games.
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,

View File

@ -2,34 +2,32 @@
This is a list of major changes in SDL's version history.
---------------------------------------------------------------------------
3.2.0:
3.1.0:
---------------------------------------------------------------------------
General:
* 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 preprocessor symbol __MACOSX__ has been renamed SDL_PLATFORM_MACOS
* The preprocessor symbol __IPHONEOS__ has been renamed SDL_PLATFORM_IOS
* 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
* 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
* Added SDL_GetDisplays() to return a list of connected displays
* Added SDL_GetPrimaryDisplay() to get the instance ID of the primary display
* Added SDL_GetWindowParent() to get the parent of popup windows
* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace SDL_CreateRGBSurface*(), and can also be used to create YUV surfaces
* Added SDL_FlipSurface() to flip a surface vertically or horizontally
* 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
* 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
* Added SDL_GetSensors(), SDL_GetSensorInstanceName(), SDL_GetSensorInstanceType(), and SDL_GetSensorInstanceNonPortableType() to directly query the list of available sensors
* Added SDL_GetJoystickCaps() and SDL_GetGamepadCaps() to get the capabilities of controllers
* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro
* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized
* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support
* 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
* 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
* Added SDL_PlayAudioDevice() to start audio playback
* Added SDL_ConvertAudioSamples() to convert audio samples from one format to another
* 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
This is a preview release of the new SDL 3.0 API.
The ABI hasn't been locked down yet, but it's fairly stable and feedback is welcome!
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.
There have been too many changes to list them all, but here are some of the highlights:
* The API has been significantly reworked to be easier to use and more consistent
* The 2D rendering API now has support for more advanced colorspaces and HDR rendering
* The 2D rendering API now has a Vulkan backend
* An example of hardware accelerated video playback using ffmpeg has been added in test/testffmpeg.c
* The shaped window API has been replaced with transparent windows
* Time and date functions have been added in SDL_time.h
* Support for webcam video capture has been added in SDL_camera.h
* Support for handling pens and tablets has been added in SDL_pen.h
* Support for file open and save dialogs has been added in SDL_dialog.h
* Cross-platform functions for working with files and directories are available in SDL_filesystem.h
* A cross-platform abstraction for working with user and game data has been added in SDL_storage.h
* Handling of main() has been moved to a header library and an optional callback-based program flow is available
* 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.
Please let us know about issues and feedback at: https://github.com/libsdl-org/SDL/issues
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!
Finally, a giant thank you to all the people who have contributed code and feedback to the SDL 3.0 improvements!

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
to provide low level access to audio, keyboard, mouse, joystick, and graphics
hardware via OpenGL and Direct3D. It is used by video playback software,
emulators, and popular games including Valve's award winning catalog
and many Humble Bundle games.
hardware. It is used by video playback software, emulators, and popular games
including Valve's award winning catalog and many Humble Bundle games.
SDL officially supports Windows, macOS, Linux, iOS, and Android.
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
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 "include" subdirectory and the programs in the "test" subdirectory.
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/)
- [Android](README-android.md)
- [CMake](README-cmake.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)
- [High DPI Support](README-highdpi.md)
- [main()](README-main-functions.md)
- [Porting information](README-porting.md)
- [PSP](README-psp.md)
- [PS2](README-ps2.md)
- [Raspberry Pi](README-raspberrypi.md)
- [Migrating from SDL 2.0](README-migration.md)
- [Supported Platforms](README-platforms.md)
- [Touch](README-touch.md)
- [Versions](README-versions.md)
- [Windows](README-windows.md)
- [WinRT](README-winrt.md)
- [Visual Studio](README-visualc.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)
- [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
issues, you can join the [SDL Discourse](https://discourse.libsdl.org/),