encounter
/
SDL
mirror of https://github.com/encounter/SDL.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated some header comments and iOS documentation to better clarify high-dpi / retina support and screen-coordinate sizes versus pixel sizes.

This commit is contained in:
Alex Szpakowski 2015-12-31 21:16:43 -04:00
parent b0d8dfcd8a
commit 4aae0290ea
4 changed files with 80 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
WhatsNew.txt
View File

@ -71,13 +71,13 @@ Linux:
iOS: iOS:
* Added support for iOS 8 * Added support for iOS 8
* The SDL_WINDOW_ALLOW_HIGHDPI window flag now enables high-dpi support, and SDL_GL_GetDrawableSize() or SDL_GetRendererOutputSize() gets the window resolution in pixels
* SDL_GetWindowSize() and display mode sizes are in the "DPI-independent points" / "screen coordinates" coordinate space rather than pixels (matches OS X behavior)
* Added native resolution support for the iPhone 6 Plus
* Added support for MFi game controllers * Added support for MFi game controllers
* Added support for the hint SDL_HINT_ACCELEROMETER_AS_JOYSTICK * Added support for the hint SDL_HINT_ACCELEROMETER_AS_JOYSTICK
* Added sRGB OpenGL ES context support on iOS 7+ * Added sRGB OpenGL ES context support on iOS 7+
* Added native resolution support for the iPhone 6 Plus
* Added support for SDL_DisableScreenSaver(), SDL_EnableScreenSaver() and the hint SDL_HINT_VIDEO_ALLOW_SCREENSAVER * Added support for SDL_DisableScreenSaver(), SDL_EnableScreenSaver() and the hint SDL_HINT_VIDEO_ALLOW_SCREENSAVER
* The SDL_WINDOW_ALLOW_HIGHDPI window flag now enables high-dpi support, and SDL_GL_GetDrawableSize() or SDL_GetRendererOutputSize() gets the window resolution in pixels
* SDL_GetWindowSize() and display mode sizes are in the "DPI-independent points" coordinate space rather than pixels (matches OS X behavior)
* SDL_SysWMinfo now contains the OpenGL ES framebuffer and color renderbuffer objects used by the window's active GLES view * SDL_SysWMinfo now contains the OpenGL ES framebuffer and color renderbuffer objects used by the window's active GLES view
* Fixed various rotation and orientation issues * Fixed various rotation and orientation issues
* Fixed memory leaks * Fixed memory leaks

42
docs/README-ios.md
View File

@ -47,17 +47,45 @@ Using the Simple DirectMedia Layer for iOS
FIXME: This needs to be updated for the latest methods FIXME: This needs to be updated for the latest methods
Here is the easiest method: Here is the easiest method:
1. Build the SDL libraries (libSDL.a and libSDLSimulator.a) and the iPhone SDL Application template. 1. Build the SDL library (libSDL2.a) and the iPhone SDL Application template.
2. Install the iPhone SDL Application template by copying it to one of XCode's template directories. I recommend creating a directory called "SDL" in "/Developer/Platforms/iOS.platform/Developer/Library/XCode/Project Templates/" and placing it there. 2. Install the iPhone SDL Application template by copying it to one of Xcode's template directories. I recommend creating a directory called "SDL" in "/Developer/Platforms/iOS.platform/Developer/Library/Xcode/Project Templates/" and placing it there.
3. Start a new project using the template. The project should be immediately ready for use with SDL. 3. Start a new project using the template. The project should be immediately ready for use with SDL.
Here is a more manual method: Here is a more manual method:
1. Create a new iPhone view based application. 1. Create a new iOS view based application.
2. Build the SDL static libraries (libSDL.a and libSDLSimulator.a) for iPhone and include them in your project. XCode will ignore the library that is not currently of the correct architecture, hence your app will work both on iPhone and in the iPhone Simulator. 2. Build the SDL static library (libSDL2.a) for iOS and include them in your project. Xcode will ignore the library that is not currently of the correct architecture, hence your app will work both on iOS and in the iOS Simulator.
3. Include the SDL header files in your project. 3. Include the SDL header files in your project.
4. Remove the ApplicationDelegate.h and ApplicationDelegate.m files -- SDL for iPhone provides its own UIApplicationDelegate. Remove MainWindow.xib -- SDL for iPhone produces its user interface programmatically. 4. Remove the ApplicationDelegate.h and ApplicationDelegate.m files -- SDL for iOS provides its own UIApplicationDelegate. Remove MainWindow.xib -- SDL for iOS produces its user interface programmatically.
5. Delete the contents of main.m and program your app as a regular SDL program instead. You may replace main.m with your own main.c, but you must tell XCode not to use the project prefix file, as it includes Objective-C code. 5. Delete the contents of main.m and program your app as a regular SDL program instead. You may replace main.m with your own main.c, but you must tell Xcode not to use the project prefix file, as it includes Objective-C code.
==============================================================================
Notes -- Retina / High-DPI and window sizes
==============================================================================
Window and display mode sizes in SDL are in "screen coordinates" (or "points",
in Apple's terminology) rather than in pixels. On iOS this means that a window
created on an iPhone 6 will have a size in screen cooordinates of 375 x 667,
rather than a size in pixels of 750 x 1334. All iOS apps are expected to
size their content based on screen coordinates / points rather than pixels,
as this allows different iOS devices to have different pixel densities
(Retina versus non-Retina screens, etc.) without apps caring too much.
By default SDL will not use the full pixel density of the screen on
Retina/high-dpi capable devices. Use the SDL_WINDOW_ALLOW_HIGHDPI flag when
creating your window to enable high-dpi support.
When high-dpi support is enabled, SDL_GetWindowSize and display mode sizes
will still be in "screen coordinates" rather than pixels, but the window will
have a much greater pixel density when the device supports it, and the
SDL_GL_GetDrawableSize or SDL_GetRendererOutputSize functions (depending on
whether raw OpenGL or the SDL_Render API is used) can be queried to determine
the size in pixels of the drawable screen framebuffer.
Some OpenGL ES functions such as glViewport expect sizes in pixels rather than
sizes in screen coordinates. When doing 2D rendering with OpenGL ES, an
orthographic projection matrix using the size in screen coordinates
(SDL_GetWindowSize) can be used in order to display content at the same scale
no matter whether a Retina device is used or not.
============================================================================== ==============================================================================
Notes -- Application events Notes -- Application events
@ -203,7 +231,7 @@ Loading Shared Objects:
Game Center Game Center
============================================================================== ==============================================================================
Game Center integration requires that you break up your main loop in order to yield control back to the system. In other words, instead of running an endless main loop, you run each frame in a callback function, using: Game Center integration might require that you break up your main loop in order to yield control back to the system. In other words, instead of running an endless main loop, you run each frame in a callback function, using:
int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam); int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);

2
include/SDL_render.h
View File

@ -215,7 +215,7 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer,
SDL_RendererInfo * info); SDL_RendererInfo * info);
/** /**
* \brief Get the output size of a rendering context. * \brief Get the output size in pixels of a rendering context.
*/ */
extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer,
int *w, int *h); int *w, int *h);

59
include/SDL_video.h
View File

@ -53,8 +53,8 @@ extern "C" {
typedef struct typedef struct
{ {
Uint32 format; /**< pixel format */ Uint32 format; /**< pixel format */
int w; /**< width */ int w; /**< width, in screen coordinates */
int h; /**< height */ int h; /**< height, in screen coordinates */
int refresh_rate; /**< refresh rate (or zero for unspecified) */ int refresh_rate; /**< refresh rate (or zero for unspecified) */
void *driverdata; /**< driver-specific data, initialize to 0 */ void *driverdata; /**< driver-specific data, initialize to 0 */
} SDL_DisplayMode; } SDL_DisplayMode;
@ -143,7 +143,9 @@ typedef enum
SDL_WINDOWEVENT_MOVED, /**< Window has been moved to data1, data2 SDL_WINDOWEVENT_MOVED, /**< Window has been moved to data1, data2
*/ */
SDL_WINDOWEVENT_RESIZED, /**< Window has been resized to data1xdata2 */ SDL_WINDOWEVENT_RESIZED, /**< Window has been resized to data1xdata2 */
SDL_WINDOWEVENT_SIZE_CHANGED, /**< The window size has changed, either as a result of an API call or through the system or user changing the window size. */ SDL_WINDOWEVENT_SIZE_CHANGED, /**< The window size has changed, either as
a result of an API call or through the
system or user changing the window size. */
SDL_WINDOWEVENT_MINIMIZED, /**< Window has been minimized */ SDL_WINDOWEVENT_MINIMIZED, /**< Window has been minimized */
SDL_WINDOWEVENT_MAXIMIZED, /**< Window has been maximized */ SDL_WINDOWEVENT_MAXIMIZED, /**< Window has been maximized */
SDL_WINDOWEVENT_RESTORED, /**< Window has been restored to normal size SDL_WINDOWEVENT_RESTORED, /**< Window has been restored to normal size
@ -412,8 +414,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* ::SDL_WINDOWPOS_UNDEFINED. * ::SDL_WINDOWPOS_UNDEFINED.
* \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED. * ::SDL_WINDOWPOS_UNDEFINED.
* \param w The width of the window. * \param w The width of the window, in screen coordinates.
* \param h The height of the window. * \param h The height of the window, in screen coordinates.
* \param flags The flags for the window, a mask of any of the following: * \param flags The flags for the window, a mask of any of the following:
* ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL, * ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS, * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS,
@ -423,6 +425,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* *
* \return The id of the window created, or zero if window creation failed. * \return The id of the window created, or zero if window creation failed.
* *
* If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size
* in pixels may differ from its size in screen coordinates on platforms with
* high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize to query the
* size of the client area in screen coordinates, and SDL_GL_GetDrawableSize or
* SDL_GetRendererOutputSize to query the drawable size in pixels.
*
* \sa SDL_DestroyWindow() * \sa SDL_DestroyWindow()
*/ */
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
@ -513,10 +521,10 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
* \brief Set the position of a window. * \brief Set the position of a window.
* *
* \param window The window to reposition. * \param window The window to reposition.
* \param x The x coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or * \param x The x coordinate of the window in screen coordinates, or
::SDL_WINDOWPOS_UNDEFINED. * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
* \param y The y coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or * \param y The y coordinate of the window in screen coordinates, or
::SDL_WINDOWPOS_UNDEFINED. * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
* *
* \note The window coordinate origin is the upper left of the display. * \note The window coordinate origin is the upper left of the display.
* *
@ -529,8 +537,10 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
* \brief Get the position of a window. * \brief Get the position of a window.
* *
* \param window The window to query. * \param window The window to query.
* \param x Pointer to variable for storing the x position, may be NULL * \param x Pointer to variable for storing the x position, in screen
* \param y Pointer to variable for storing the y position, may be NULL * coordinates. May be NULL.
* \param y Pointer to variable for storing the y position, in screen
* coordinates. May be NULL.
* *
* \sa SDL_SetWindowPosition() * \sa SDL_SetWindowPosition()
*/ */
@ -541,12 +551,17 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
* \brief Set the size of a window's client area. * \brief Set the size of a window's client area.
* *
* \param window The window to resize. * \param window The window to resize.
* \param w The width of the window, must be >0 * \param w The width of the window, in screen coordinates. Must be >0.
* \param h The height of the window, must be >0 * \param h The height of the window, in screen coordinates. Must be >0.
* *
* \note You can't change the size of a fullscreen window, it automatically * \note You can't change the size of a fullscreen window, it automatically
* matches the size of the display mode. * matches the size of the display mode.
* *
* The window size in screen coordinates may differ from the size in pixels, if
* the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
* high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize or
* SDL_GetRendererOutputSize to get the real client area size in pixels.
*
* \sa SDL_GetWindowSize() * \sa SDL_GetWindowSize()
*/ */
extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
@ -556,8 +571,15 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
* \brief Get the size of a window's client area. * \brief Get the size of a window's client area.
* *
* \param window The window to query. * \param window The window to query.
* \param w Pointer to variable for storing the width, may be NULL * \param w Pointer to variable for storing the width, in screen
* \param h Pointer to variable for storing the height, may be NULL * coordinates. May be NULL.
* \param h Pointer to variable for storing the height, in screen
* coordinates. May be NULL.
*
* The window size in screen coordinates may differ from the size in pixels, if
* the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
* high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize or
* SDL_GetRendererOutputSize to get the real client area size in pixels.
* *
* \sa SDL_SetWindowSize() * \sa SDL_SetWindowSize()
*/ */
@ -1009,11 +1031,12 @@ extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void);
extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
/** /**
* \brief Get the size of a window's underlying drawable (for use with glViewport). * \brief Get the size of a window's underlying drawable in pixels (for use
* with glViewport).
* *
* \param window Window from which the drawable size should be queried * \param window Window from which the drawable size should be queried
* \param w Pointer to variable for storing the width, may be NULL * \param w Pointer to variable for storing the width in pixels, may be NULL
* \param h Pointer to variable for storing the height, may be NULL * \param h Pointer to variable for storing the height in pixels, may be NULL
* *
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
* drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a