docs/README-winrt.md
changeset 10171 5b61e12c0a30
parent 10156 80e408941b90
child 10486 5bf595c48fd4
     1.1 --- a/docs/README-winrt.md	Wed May 11 21:11:12 2016 +0200
     1.2 +++ b/docs/README-winrt.md	Sat May 14 23:29:49 2016 -0400
     1.3 @@ -159,7 +159,9 @@
     1.4     the linker, and will copy SDL's .dll files to your app's final output.
     1.5  4. adjust your app's build settings, at minimum, telling it where to find SDL's
     1.6     header files.
     1.7 -5. add a file that contains a WinRT-appropriate main function.
     1.8 +5. add files that contains a WinRT-appropriate main function, along with some
     1.9 +   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
    1.10 +   work properly.
    1.11  6. add SDL-specific app code.
    1.12  7. build and run your app.
    1.13  
    1.14 @@ -267,33 +269,27 @@
    1.15  10. close the dialog, saving settings, by clicking the "OK" button
    1.16  
    1.17  
    1.18 -### 5. Add a WinRT-appropriate main function to the app. ###
    1.19 +### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
    1.20  
    1.21 -C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
    1.22 -the app starts launching. The parameters of WinRT main functions are different 
    1.23 -than those found on other platforms, Win32 included.  SDL/WinRT provides a 
    1.24 -platform-appropriate main function that will perform these actions, setup key 
    1.25 -portions of the app, then invoke a classic, C/C++-style main function (that take 
    1.26 -in "argc" and "argv" parameters).  The code for this file is contained inside 
    1.27 -SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
    1.28 -You'll need to add this file, or a copy of it, to your app's project, and make 
    1.29 -sure it gets compiled using a Microsoft-specific set of C++ extensions called 
    1.30 -C++/CX.
    1.31 +A few files should be included directly in your app's MSVC project, specifically:
    1.32 +1. a WinRT-appropriate main function (which is different than main() functions on
    1.33 +   other platforms)
    1.34 +2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
    1.35 +   (if and when the app needs to do so).  *If this cursor resource is not
    1.36 +   included, mouse-position reporting may fail if and when the cursor is
    1.37 +   hidden, due to possible bugs/design-oddities in Windows itself.*
    1.38  
    1.39 -**NOTE: C++/CX compilation is currently required in at least one file of your 
    1.40 -app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
    1.41 -Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
    1.42 -
    1.43 -To include `SDL_winrt_main_NonXAML.cpp`:
    1.44 +To include these files:
    1.45  
    1.46  1. right-click on your project (again, in Visual C++'s Solution Explorer), 
    1.47     navigate to "Add", then choose "Existing Item...".
    1.48 -2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
    1.49 -   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
    1.50 -   closes, either by double-clicking on the file, or single-clicking on it and 
    1.51 -   then clicking Add.
    1.52 -3. right-click on the file (as listed in your project), then click on 
    1.53 -   "Properties...".
    1.54 +2. navigate to the directory containing SDL's source code, then into its
    1.55 +   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
    1.56 +   - `SDL_winrt_main_NonXAML.cpp`
    1.57 +   - `SDL2-WinRTResources.rc`
    1.58 +   - `SDL2-WinRTResource_BlankCursor.cur`
    1.59 +3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
    1.60 +   project), then click on "Properties...".
    1.61  4. in the drop-down box next to "Configuration", choose, "All Configurations"
    1.62  5. in the drop-down box next to "Platform", choose, "All Platforms"
    1.63  6. in the left-hand list, click on "C/C++"
    1.64 @@ -301,6 +297,11 @@
    1.65  8. click the OK button.  This will close the dialog.
    1.66  
    1.67  
    1.68 +**NOTE: C++/CX compilation is currently required in at least one file of your 
    1.69 +app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
    1.70 +Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
    1.71 +
    1.72 +
    1.73  ### 6. Add app code and assets ###
    1.74  
    1.75  At this point, you can add in SDL-specific source code.  Be sure to include a 
    1.76 @@ -465,3 +466,13 @@
    1.77  
    1.78      /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
    1.79  
    1.80 +
    1.81 +#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
    1.82 +
    1.83 +This may be caused by a bug in Windows itself, whereby hiding the mouse
    1.84 +cursor can cause mouse-position reporting to fail.
    1.85 +
    1.86 +SDL provides a workaround for this, but it requires that an app links to a
    1.87 +set of Win32-style cursor image-resource files.  A copy of suitable resource
    1.88 +files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
    1.89 +project file should be sufficient to get the app to use them.