docs/README-nacl.md
author Sam Lantinga
Sun, 05 Apr 2020 08:58:47 -0700
changeset 13689 c3055b205671
parent 10486 5bf595c48fd4
permissions -rw-r--r--
Fixed bug 5015 - SDL_RenderReadPixels on DirectX 11.1 backend seems to be broken

Konrad

It appears that I cannot use SDL_RenderReadPixels on a bound framebuffer (SDL_Texture set as render target) as it simply results in gibberish data. However, drawing that framebuffer into the default target (window surface) does render it correctly. Other backends (OpenGL, software, Direct3D) do work fine.

It looks to me like D3D11_RenderReadPixels just gets the general backbuffer and not the current render target and its backbuffer.

Here is the patch which actually fetches the current render target and its underlying ID3D11Resource which is ID3D11Texture2D.
slouken@10486
     1
Native Client
slouken@10486
     2
================================================================================
slouken@10486
     3
slouken@10486
     4
Requirements: 
slouken@10486
     5
slouken@10486
     6
* Native Client SDK (https://developer.chrome.com/native-client), 
slouken@10486
     7
  (tested with Pepper version 33 or higher).
slouken@10486
     8
slouken@10486
     9
The SDL backend for Chrome's Native Client has been tested only with the PNaCl
slouken@10486
    10
toolchain, which generates binaries designed to run on ARM and x86_32/64 
slouken@10486
    11
platforms. This does not mean it won't work with the other toolchains!
slouken@10486
    12
slouken@10486
    13
================================================================================
slouken@10486
    14
Building SDL for NaCl
slouken@10486
    15
================================================================================
slouken@10486
    16
slouken@10486
    17
Set up the right environment variables (see naclbuild.sh), then configure SDL with:
slouken@10486
    18
slouken@10486
    19
    configure --host=pnacl --prefix some/install/destination
slouken@10486
    20
    
slouken@10486
    21
Then "make". 
slouken@10486
    22
slouken@10486
    23
As an example of how to create a deployable app a Makefile project is provided 
slouken@10486
    24
in test/nacl/Makefile, which includes some monkey patching of the common.mk file 
slouken@10486
    25
provided by NaCl, without which linking properly to SDL won't work (the search 
slouken@10486
    26
path can't be modified externally, so the linker won't find SDL's binaries unless 
slouken@10486
    27
you dump them into the SDK path, which is inconvenient).
slouken@10486
    28
Also provided in test/nacl is the required support file, such as index.html, 
slouken@10486
    29
manifest.json, etc.
slouken@10486
    30
SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
slouken@10486
    31
This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
slouken@10486
    32
hiding the asynchronous nature of the browser behind the scenes...which is not the
slouken@10486
    33
same as making it disappear!
slouken@10486
    34
slouken@10486
    35
slouken@10486
    36
================================================================================
slouken@10486
    37
Running tests
slouken@10486
    38
================================================================================
slouken@10486
    39
slouken@10486
    40
Due to the nature of NaCl programs, building and running SDL tests is not as
slouken@10486
    41
straightforward as one would hope. The script naclbuild.sh in build-scripts 
slouken@10486
    42
automates the process and should serve as a guide for users of SDL trying to build 
slouken@10486
    43
their own applications.
slouken@10486
    44
slouken@10486
    45
Basic usage:
slouken@10486
    46
    
slouken@10486
    47
    ./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
slouken@10486
    48
    
slouken@10486
    49
This will build testgles2.c by default.
slouken@10486
    50
slouken@10486
    51
If you want to build a different test, for example testrendercopyex.c:
slouken@10486
    52
    
slouken@10486
    53
    SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
slouken@10486
    54
    
slouken@10486
    55
Once the build finishes, you have to serve the contents with a web server (the
slouken@10486
    56
script will give you instructions on how to do that with Python).
slouken@10486
    57
slouken@10486
    58
================================================================================
slouken@10486
    59
RWops and nacl_io
slouken@10486
    60
================================================================================
slouken@10486
    61
slouken@10486
    62
SDL_RWops work transparently with nacl_io. Two functions control the mount points:
slouken@10486
    63
    
slouken@10486
    64
    int mount(const char* source, const char* target, 
slouken@10486
    65
                      const char* filesystemtype, 
slouken@10486
    66
                      unsigned long mountflags, const void *data);
slouken@10486
    67
    int umount(const char *target);
slouken@10486
    68
    
slouken@10486
    69
    For convenience, SDL will by default mount an httpfs tree at / before calling 
slouken@10486
    70
the app's main function. Such setting can be overridden by calling:
slouken@10486
    71
    
slouken@10486
    72
    umount("/");
slouken@10486
    73
slouken@10486
    74
And then mounting a different filesystem at /
slouken@10486
    75
slouken@10486
    76
It's important to consider that the asynchronous nature of file operations on a
slouken@10486
    77
browser is hidden from the application, effectively providing the developer with
slouken@10486
    78
a set of blocking file operations just like you get in a regular desktop 
slouken@10486
    79
environment, which eases the job of porting to Native Client, but also introduces 
slouken@10486
    80
a set of challenges of its own, in particular when big file sizes and slow 
slouken@10486
    81
connections are involved.
slouken@10486
    82
slouken@10486
    83
For more information on how nacl_io and mount points work, see:
slouken@10486
    84
    
slouken@10486
    85
    https://developer.chrome.com/native-client/devguide/coding/nacl_io
slouken@10486
    86
    https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
slouken@10486
    87
slouken@10486
    88
To be able to save into the directory "/save/" (like backup of game) :
slouken@10486
    89
slouken@10486
    90
    mount("", "/save", "html5fs", 0, "type=PERSISTENT");
slouken@10486
    91
slouken@10486
    92
And add to manifest.json :
slouken@10486
    93
slouken@10486
    94
    "permissions": [
slouken@10486
    95
        "unlimitedStorage"
slouken@10486
    96
    ]
slouken@10486
    97
slouken@10486
    98
================================================================================
slouken@10486
    99
TODO - Known Issues
slouken@10486
   100
================================================================================
slouken@10486
   101
* Testing of all systems with a real application (something other than SDL's tests)
slouken@10486
   102
* Key events don't seem to work properly
slouken@10486
   103