From f644d650b9ba13442966c2c0238abd3fd5e5941f Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot Date: Sun, 5 Jan 2025 19:11:53 +0000 Subject: [PATCH] Sync SDL3 header -> wiki --- SDL3/CategoryFilesystem.md | 23 ++++++++++++++++++++++- SDL3/CategoryIOStream.md | 2 +- SDL3/CategoryMetal.md | 4 ++++ SDL3/CategoryStdinc.md | 26 +++++++++++++++++++++----- SDL3/CategorySystem.md | 8 +++++++- SDL3/SDL_PenAxisEvent.md | 1 + SDL3/SDL_PenButtonEvent.md | 1 + SDL3/SDL_PenMotionEvent.md | 1 + SDL3/SDL_PenProximityEvent.md | 1 + SDL3/SDL_PenTouchEvent.md | 1 + 10 files changed, 60 insertions(+), 8 deletions(-) diff --git a/SDL3/CategoryFilesystem.md b/SDL3/CategoryFilesystem.md index c0d604f8d..967f7570e 100644 --- a/SDL3/CategoryFilesystem.md +++ b/SDL3/CategoryFilesystem.md @@ -1,6 +1,27 @@ # CategoryFilesystem -SDL Filesystem API. +SDL offers an API for examining and manipulating the system's filesystem. +This covers most things one would need to do with directories, except for +actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) +and [CategoryAsyncIO](CategoryAsyncIO) instead). + +There are functions to answer necessary path questions: + +- Where is my app's data? [SDL_GetBasePath](SDL_GetBasePath)(). +- Where can I safely write files? [SDL_GetPrefPath](SDL_GetPrefPath)(). +- Where are paths like Downloads, Desktop, Music? + [SDL_GetUserFolder](SDL_GetUserFolder)(). +- What is this thing at this location? + [SDL_GetPathInfo](SDL_GetPathInfo)(). +- What items live in this folder? + [SDL_EnumerateDirectory](SDL_EnumerateDirectory)(). +- What items live in this folder by wildcard? + [SDL_GlobDirectory](SDL_GlobDirectory)(). +- What is my current working directory? + [SDL_GetCurrentDirectory](SDL_GetCurrentDirectory)(). + +SDL also offers functions to manipulate the directory tree: renaming, +removing, copying files. diff --git a/SDL3/CategoryIOStream.md b/SDL3/CategoryIOStream.md index d43e80425..b7dfe4562 100644 --- a/SDL3/CategoryIOStream.md +++ b/SDL3/CategoryIOStream.md @@ -1,7 +1,7 @@ # CategoryIOStream SDL provides an abstract interface for reading and writing data streams. It -offers implementations for files, memory, etc, and the app can provideo +offers implementations for files, memory, etc, and the app can provide their own implementations, too. [SDL_IOStream](SDL_IOStream) is not related to the standard C++ iostream diff --git a/SDL3/CategoryMetal.md b/SDL3/CategoryMetal.md index b6fed0d65..f287b9f61 100644 --- a/SDL3/CategoryMetal.md +++ b/SDL3/CategoryMetal.md @@ -2,6 +2,10 @@ Functions to creating Metal layers and views on SDL windows. +This provides some platform-specific glue for Apple platforms. Most macOS +and iOS apps can use SDL without these functions, but this API they can be +useful for specific OS-level integration tasks. + ## Functions diff --git a/SDL3/CategoryStdinc.md b/SDL3/CategoryStdinc.md index 0f0457a72..a49995b1f 100644 --- a/SDL3/CategoryStdinc.md +++ b/SDL3/CategoryStdinc.md @@ -1,10 +1,26 @@ # CategoryStdinc -This is a general header that includes C language support. It implements a -subset of the C runtime APIs, but with an `SDL_` prefix. For most common -use cases, these should behave the same way as their C runtime equivalents, -but they may differ in how or whether they handle certain edge cases. When -in doubt, consult the documentation for details. +SDL provides its own implementation of some of the most important C runtime +functions. + +Using these functions allows an app to have access to common C +functionality without depending on a specific C runtime (or a C runtime at +all). More importantly, the SDL implementations work identically across +platforms, so apps can avoid surprises like snprintf() behaving differently +between Windows and Linux builds, or itoa() only existing on some +platforms. + +For many of the most common functions, like [SDL_memcpy](SDL_memcpy), SDL +might just call through to the usual C runtime behind the scenes, if it +makes sense to do so (if it's faster and always available/reliable on a +given platform), reducing library size and offering the most optimized +option. + +SDL also offers other C-runtime-adjacent functionality in this header that +either isn't, strictly speaking, part of any C runtime standards, like +[SDL_crc32](SDL_crc32)() and [SDL_reinterpret_cast](SDL_reinterpret_cast), +etc. It also offers a few better options, like +[SDL_strlcpy](SDL_strlcpy)(), which functions as a safer form of strcpy(). diff --git a/SDL3/CategorySystem.md b/SDL3/CategorySystem.md index 13f2a6ab2..4d8790323 100644 --- a/SDL3/CategorySystem.md +++ b/SDL3/CategorySystem.md @@ -1,6 +1,12 @@ # CategorySystem -Platform-specific SDL API functions. +Platform-specific SDL API functions. These are functions that deal with +needs of specific operating systems, that didn't make sense to offer as +platform-independent, generic APIs. + +Most apps can make do without these functions, but they can be useful for +integrating with other parts of a specific system, adding platform-specific +polish to an app, or solving problems that only affect one target. diff --git a/SDL3/SDL_PenAxisEvent.md b/SDL3/SDL_PenAxisEvent.md index ef97414d8..2c67abd09 100644 --- a/SDL3/SDL_PenAxisEvent.md +++ b/SDL3/SDL_PenAxisEvent.md @@ -37,3 +37,4 @@ This struct is available since SDL 3.1.3. ---- [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen) + diff --git a/SDL3/SDL_PenButtonEvent.md b/SDL3/SDL_PenButtonEvent.md index 6611f47a6..d20f27aa7 100644 --- a/SDL3/SDL_PenButtonEvent.md +++ b/SDL3/SDL_PenButtonEvent.md @@ -38,3 +38,4 @@ This struct is available since SDL 3.1.3. ---- [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen) + diff --git a/SDL3/SDL_PenMotionEvent.md b/SDL3/SDL_PenMotionEvent.md index a06364ab4..197a413f2 100644 --- a/SDL3/SDL_PenMotionEvent.md +++ b/SDL3/SDL_PenMotionEvent.md @@ -39,3 +39,4 @@ This struct is available since SDL 3.1.3. ---- [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen) + diff --git a/SDL3/SDL_PenProximityEvent.md b/SDL3/SDL_PenProximityEvent.md index 9adb504d1..78bf654b8 100644 --- a/SDL3/SDL_PenProximityEvent.md +++ b/SDL3/SDL_PenProximityEvent.md @@ -41,3 +41,4 @@ This struct is available since SDL 3.1.3. ---- [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen) + diff --git a/SDL3/SDL_PenTouchEvent.md b/SDL3/SDL_PenTouchEvent.md index 9b9d5d847..1b0800797 100644 --- a/SDL3/SDL_PenTouchEvent.md +++ b/SDL3/SDL_PenTouchEvent.md @@ -37,3 +37,4 @@ This struct is available since SDL 3.1.3. ---- [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryEvents](CategoryEvents), [CategoryPen](CategoryPen) +