Tweaking documentation for the SDL 3.0 preview release

README.md

@@ -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,

WhatsNew.txt

@@ -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 [email protected] 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!

docs/README-git.md

@@ -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/
-

docs/README-hg.md

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

docs/README.md

@@ -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/)
 
+- [High DPI Support](README-highdpi.md)
+- [main()](README-main-functions.md)
+- [Porting information](README-porting.md)
+- [Migrating from SDL 2.0](README-migration.md)
+- [Supported Platforms](README-platforms.md)
+- [Touch](README-touch.md)
+- [Versions](README-versions.md)
+- [Visual Studio](README-visualc.md)
+
 - [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)
+- [KMSDRM support on BSD](README-kmsbsd.md)
 - [Linux](README-linux.md)
 - [macOS](README-macos.md)
-- [Supported Platforms](README-platforms.md)
-- [Porting information](README-porting.md)
-- [PSP](README-psp.md)
+- [Nintendo 3DS](README-n3ds.md)
 - [PS2](README-ps2.md)
+- [PSP](README-psp.md)
+- [PSVita](README-vita.md)
 - [Raspberry Pi](README-raspberrypi.md)
-- [Touch](README-touch.md)
-- [Versions](README-versions.md)
+- [RISC OS](README-riscos.md)
+- [Windows GDK](README-gdk.md)
+- [Windows UWP](README-winrt.md)
 - [Windows](README-windows.md)
-- [WinRT](README-winrt.md)
-- [PSVita](README-vita.md)
-- [Nokia N-Gage](README-ngage.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/),