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