Merged default into iOS-improvements

--HG--
branch : iOS-improvements

include/SDL_config.h.cmake

@@ -264,7 +264,8 @@
 #cmakedefine SDL_VIDEO_DRIVER_WINDOWS @SDL_VIDEO_DRIVER_WINDOWS@
 #cmakedefine SDL_VIDEO_DRIVER_WAYLAND @SDL_VIDEO_DRIVER_WAYLAND@
 #cmakedefine SDL_VIDEO_DRIVER_RPI @SDL_VIDEO_DRIVER_RPI@
-#cmakedefine SDL_VIDEO_DRIVER_MX6 @SDL_VIDEO_DRIVER_MX6@
+#cmakedefine SDL_VIDEO_DRIVER_VIVANTE @SDL_VIDEO_DRIVER_VIVANTE@
+#cmakedefine SDL_VIDEO_DRIVER_VIVANTE_VDK @SDL_VIDEO_DRIVER_VIVANTE_VDK@
 
 #if 0
 /* !!! FIXME: in configure script version, missing here: */

include/SDL_config.h.in

@@ -308,7 +308,8 @@
 #undef SDL_VIDEO_DRIVER_X11_CONST_PARAM_XEXTADDDISPLAY
 #undef SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM
 #undef SDL_VIDEO_DRIVER_NACL
-#undef SDL_VIDEO_DRIVER_MX6
+#undef SDL_VIDEO_DRIVER_VIVANTE
+#undef SDL_VIDEO_DRIVER_VIVANTE_VDK
 
 #undef SDL_VIDEO_RENDER_D3D
 #undef SDL_VIDEO_RENDER_D3D11

include/SDL_haptic.h

@@ -492,7 +492,7 @@ typedef struct SDL_HapticConstant
  *  over time.  The type determines the shape of the wave and the parameters
  *  determine the dimensions of the wave.
  *
- *  Phase is given by hundredth of a cycle meaning that giving the phase a value
+ *  Phase is given by hundredth of a degree meaning that giving the phase a value
  *  of 9000 will displace it 25% of its period.  Here are sample values:
  *   -     0: No phase displacement.
  *   -  9000: Displaced 25% of its period.
@@ -553,9 +553,9 @@ typedef struct SDL_HapticPeriodic
 
     /* Periodic */
     Uint16 period;      /**< Period of the wave. */
-    Sint16 magnitude;   /**< Peak value. */
+    Sint16 magnitude;   /**< Peak value; if negative, equivalent to 180 degrees extra phase shift. */
     Sint16 offset;      /**< Mean value of the wave. */
-    Uint16 phase;       /**< Horizontal shift given by hundredth of a cycle. */
+    Uint16 phase;       /**< Horizontal shift given by hundredth of a degree. */
 
     /* Envelope */
     Uint16 attack_length;   /**< Duration of the attack. */

include/SDL_hints.h

@@ -440,11 +440,54 @@ extern "C" {
  */
 #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
 
-/** \brief If set to "1", back button press events on Windows Phone 8+ will be marked as handled.
+/** \brief Allows back-button-press events on Windows Phone to be marked as handled
  *
- *  TODO, WinRT: document SDL_HINT_WINRT_HANDLE_BACK_BUTTON need and use
- *  For now, more details on why this is needed can be found at the
- *  beginning of the following web page:
+ *  Windows Phone devices typically feature a Back button.  When pressed,
+ *  the OS will emit back-button-press events, which apps are expected to
+ *  handle in an appropriate manner.  If apps do not explicitly mark these
+ *  events as 'Handled', then the OS will invoke its default behavior for
+ *  unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to
+ *  terminate the app (and attempt to switch to the previous app, or to the
+ *  device's home screen).
+ *
+ *  Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL
+ *  to mark back-button-press events as Handled, if and when one is sent to
+ *  the app.
+ *
+ *  Internally, Windows Phone sends back button events as parameters to
+ *  special back-button-press callback functions.  Apps that need to respond
+ *  to back-button-press events are expected to register one or more
+ *  callback functions for such, shortly after being launched (during the
+ *  app's initialization phase).  After the back button is pressed, the OS
+ *  will invoke these callbacks.  If the app's callback(s) do not explicitly
+ *  mark the event as handled by the time they return, or if the app never
+ *  registers one of these callback, the OS will consider the event
+ *  un-handled, and it will apply its default back button behavior (terminate
+ *  the app).
+ *
+ *  SDL registers its own back-button-press callback with the Windows Phone
+ *  OS.  This callback will emit a pair of SDL key-press events (SDL_KEYDOWN
+ *  and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which
+ *  it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON.
+ *  If the hint's value is set to "1", the back button event's Handled
+ *  property will get set to 'true'.  If the hint's value is set to something
+ *  else, or if it is unset, SDL will leave the event's Handled property
+ *  alone.  (By default, the OS sets this property to 'false', to note.)
+ *
+ *  SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a
+ *  back button is pressed, or can set it in direct-response to a back button
+ *  being pressed.
+ *
+ *  In order to get notified when a back button is pressed, SDL apps should
+ *  register a callback function with SDL_AddEventWatch(), and have it listen
+ *  for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK.
+ *  (Alternatively, SDL_KEYUP events can be listened-for.  Listening for
+ *  either event type is suitable.)  Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON
+ *  set by such a callback, will be applied to the OS' current
+ *  back-button-press event.
+ *
+ *  More details on back button behavior in Windows Phone apps can be found
+ *  at the following page, on Microsoft's developer site:
  *  http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx
  */
 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"

include/SDL_render.h

@@ -552,7 +552,7 @@ extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
                                                    SDL_Rect * rect);
 
 /**
- *  \brief Get wether clipping is enabled on the given renderer
+ *  \brief Get whether clipping is enabled on the given renderer.
  *
  *  \param renderer The renderer from which clip state should be queried.
  *

include/SDL_syswm.h

@@ -152,6 +152,10 @@ struct SDL_SysWMmsg
 #if defined(SDL_VIDEO_DRIVER_COCOA)
         struct
         {
+            /* Latest version of Xcode clang complains about empty structs in C v. C++:
+                 error: empty struct has size 0 in C, size 1 in C++
+             */
+            int dummy;
             /* No Cocoa window events yet */
         } cocoa;
 #endif