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