From bda50f6f678518021fbccb87be64ad9ad3ee2711 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 2 Oct 2015 13:56:01 -0700 Subject: [PATCH] rename 'prepare' methods to the better 'preload plugins' terminology --- .../docs/api_reference/emscripten.h.rst | 42 +++++++++---------- src/library_browser.js | 4 +- system/include/emscripten/emscripten.h | 10 +++-- tests/sdl2_image_prepare.c | 2 +- tests/sdl_image_prepare.c | 2 +- tests/sdl_image_prepare_data.c | 4 +- 6 files changed, 32 insertions(+), 32 deletions(-) diff --git a/site/source/docs/api_reference/emscripten.h.rst b/site/source/docs/api_reference/emscripten.h.rst index c9c9c0279..e1458f827 100644 --- a/site/source/docs/api_reference/emscripten.h.rst +++ b/site/source/docs/api_reference/emscripten.h.rst @@ -423,13 +423,13 @@ Typedefs typedef void (*em_async_wget2_data_onprogress_func)(void*, int, int) -.. c:type:: em_async_prepare_data_onload_func +.. c:type:: em_run_preload_plugins_data_onload_func - Function pointer type for the ``onload`` callback of :c:func:`emscripten_async_prepare_data` (specific values of the parameters documented in that method). + Function pointer type for the ``onload`` callback of :c:func:`emscripten_run_preload_plugins_data` (specific values of the parameters documented in that method). Defined as: :: - typedef void (*em_async_prepare_data_onload_func)(void*, const char*) + typedef void (*em_run_preload_plugins_data_onload_func)(void*, const char*) @@ -440,7 +440,7 @@ Functions Load file from url in *synchronously*. For the asynchronous version, see the :c:func:`emscripten_async_wget`. - In addition to fetching the URL from the network, the contents are prepared so that the data is usable in ``IMG_Load`` and so forth (we synchronously do the work to make the browser decode the image or audio etc.). + In addition to fetching the URL from the network, preload plugins are executed so that the data is usable in ``IMG_Load`` and so forth (we synchronously do the work to make the browser decode the image or audio etc.). This function is blocking; it won't return until all operations are finished. You can then open and read the file if it succeeded. @@ -454,7 +454,7 @@ Functions Loads a file from a URL asynchronously. - In addition to fetching the URL from the network, the contents are prepared so that the data is usable in ``IMG_Load`` and so forth (we asynchronously do the work to make the browser decode the image or audio etc.). + In addition to fetching the URL from the network, preload plugins are executed so that the data is usable in ``IMG_Load`` and so forth (we asynchronously do the work to make the browser decode the image or audio etc.). When the file is ready the ``onload`` callback will be called. If any error occurs ``onerror`` will be called. The callbacks are called with the file as their argument. @@ -476,7 +476,7 @@ Functions This is the "data" version of :c:func:`emscripten_async_wget`. - Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot do the 'prepare' stage to set things up for ``IMG_Load`` and so forth (``IMG_Load`` etc. work on files). + Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot run preload plugins to set things up for ``IMG_Load`` and so forth (``IMG_Load`` etc. work on files). When the file is ready then the ``onload`` callback will be called. If any error occurred ``onerror`` will be called. @@ -500,7 +500,7 @@ Functions This is an **experimental** "more feature-complete" version of :c:func:`emscripten_async_wget`. - In addition to fetching the URL from the network, the contents are prepared so that the data is usable in ``IMG_Load`` and so forth (we asynchronously do the work to make the browser decode the image, audio, etc.). + In addition to fetching the URL from the network, preload plugins are executed so that the data is usable in ``IMG_Load`` and so forth (we asynchronously do the work to make the browser decode the image, audio, etc.). When the file is ready the ``onload`` callback will be called with the object pointers given in ``arg`` and ``file``. During the download the ``onprogress`` callback is called. @@ -537,10 +537,8 @@ Functions This is the "data" version of :c:func:`emscripten_async_wget2`. It is an **experimental** "more feature complete" version of :c:func:`emscripten_async_wget_data`. - Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot do the 'prepare' stage to set things up for ``IMG_Load`` and so forth (``IMG_Load`` etc. work on files). + Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot run preload plugins to set things up for ``IMG_Load`` and so forth (``IMG_Load`` etc. work on files). - In addition to fetching the URL from the network, the contents are prepared so that the data is usable in ``IMG_Load`` and so forth (we asynchronously do the work to make the browser decode the image or audio etc.). - When the file is ready the ``onload`` callback will be called with the object pointers given in ``arg``, a pointer to the buffer in memory, and an unsigned integer containing the size of the buffer. During the download the ``onprogress`` callback is called with progress information. If an error occurs, ``onerror`` will be called with the HTTP status code and a string containing the status description. :param url: The URL of the file to load. @@ -580,19 +578,19 @@ Functions :param int handle: A handle to request to be aborted. -.. c:function:: void emscripten_async_prepare_data(char* data, int size, const char *suffix, void *arg, em_async_prepare_data_onload_func onload, em_arg_callback_func onerror) +.. c:function:: void emscripten_run_preload_plugins_data(char* data, int size, const char *suffix, void *arg, em_run_preload_plugins_data_onload_func onload, em_arg_callback_func onerror) - Prepares a buffer of data asynchronously. This is a "data" version of :c:func:`emscripten_async_prepare`, which receives raw data as input instead of a filename (this can prevent the need to write data to a file first). + Runs preload plugins on a buffer of data asynchronously. This is a "data" version of :c:func:`emscripten_run_preload_plugins`, which receives raw data as input instead of a filename (this can prevent the need to write data to a file first). When file is loaded then the ``onload`` callback will be called. If any error occurs ``onerror`` will be called. ``onload`` also receives a second parameter, which is a 'fake' filename which you can pass into ``IMG_Load`` (it is not an actual file, but it identifies this image for ``IMG_Load`` to be able to process it). Note that the user of this API is responsible for ``free()`` ing the memory allocated for the fake filename. - :param char* data: The buffer of data to prepare. + :param char* data: The buffer of data to process. :param suffix: The file suffix, e.g. 'png' or 'jpg'. :type suffix: const char* :param void* arg: User-defined data that is passed to the callbacks, untouched by the API itself. This may be used by a callback to identify the associated call. - :param em_async_prepare_data_onload_func onload: Callback on successful preparation of the file. The callback function parameter values are: + :param em_run_preload_plugins_data_onload_func onload: Callback on successful processing of the data. The callback function parameter values are: - *(void*)* : Equal to ``arg`` (user defined data). - *(const char*)* : A 'fake' filename which you can pass into ``IMG_Load``. See above for more information. @@ -682,23 +680,21 @@ Emscripten Asynchronous IndexedDB API -.. c:function:: int emscripten_async_prepare(const char* file, em_str_callback_func onload, em_str_callback_func onerror) +.. c:function:: int emscripten_run_preload_plugins(const char* file, em_str_callback_func onload, em_str_callback_func onerror) - Prepares a file asynchronously. + Runs preload plugins on a file asynchronously. It works on file data already present and performs any required asynchronous operations available as preload plugins, such as decoding images for use in ``IMG_Load``, or decoding audio for use in ``Mix_LoadWAV``. - This does just the preparation part of :c:func:`emscripten_async_wget`. That is, it works on file data already present and performs any required asynchronous operations (for example, decoding images for use in ``IMG_Load``, decoding audio for use in ``Mix_LoadWAV``, etc.). - - Once the operations are complete (the file is prepared), the ``onload`` callback will be called. If any error occurs ``onerror`` will be called. The callbacks are called with the file as their argument. + Once the operations are complete, the ``onload`` callback will be called. If any error occurs ``onerror`` will be called. The callbacks are called with the file as their argument. - :param file: The name of the file to prepare. + :param file: The name of the file to process. :type file: const char* - :param em_str_callback_func onload: Callback on successful preparation of the file. The callback function parameter value is: + :param em_str_callback_func onload: Callback on successful processing of the file. The callback function parameter value is: - - *(const char*)* : The name of the ``file`` that was prepared. + - *(const char*)* : The name of the ``file`` that was processed. :param em_str_callback_func onerror: Callback in the event of failure. The callback function parameter value is: - - *(const char*)* : The name of the ``file`` for which the prepare failed. + - *(const char*)* : The name of the ``file`` for which the operation failed. :return: 0 if successful, -1 if the file does not exist :rtype: int diff --git a/src/library_browser.js b/src/library_browser.js index 3e3bc1dd4..1cbe12d27 100644 --- a/src/library_browser.js +++ b/src/library_browser.js @@ -981,7 +981,7 @@ mergeInto(LibraryManager.library, { } }, - emscripten_async_prepare: function(file, onload, onerror) { + emscripten_run_preload_plugins: function(file, onload, onerror) { Module['noExitRuntime'] = true; var _file = Pointer_stringify(file); @@ -1002,7 +1002,7 @@ mergeInto(LibraryManager.library, { return 0; }, - emscripten_async_prepare_data: function(data, size, suffix, arg, onload, onerror) { + emscripten_run_preload_plugins_data: function(data, size, suffix, arg, onload, onerror) { Module['noExitRuntime'] = true; var _suffix = Pointer_stringify(suffix); diff --git a/system/include/emscripten/emscripten.h b/system/include/emscripten/emscripten.h index 95c2432da..56aa0e48e 100644 --- a/system/include/emscripten/emscripten.h +++ b/system/include/emscripten/emscripten.h @@ -203,10 +203,14 @@ void emscripten_idb_free_blob(int blob); // other async utilities -int emscripten_async_prepare(const char* file, em_str_callback_func onload, em_str_callback_func onerror); +int emscripten_run_preload_plugins(const char* file, em_str_callback_func onload, em_str_callback_func onerror); -typedef void (*em_async_prepare_data_onload_func)(void*, const char*); -void emscripten_async_prepare_data(char* data, int size, const char *suffix, void *arg, em_async_prepare_data_onload_func onload, em_arg_callback_func onerror); +typedef void (*em_run_preload_plugins_data_onload_func)(void*, const char*); +void emscripten_run_preload_plugins_data(char* data, int size, const char *suffix, void *arg, em_run_preload_plugins_data_onload_func onload, em_arg_callback_func onerror); + +// show an error on some renamed methods +#define emscripten_async_prepare(...) _Pragma("GCC error(\"emscripten_async_prepare has been replaced by emscripten_run_preload_plugins\")") +#define emscripten_async_prepare_data(...) _Pragma("GCC error(\"emscripten_async_prepare_data has been replaced by emscripten_run_preload_plugins_data\")") // worker APIs diff --git a/tests/sdl2_image_prepare.c b/tests/sdl2_image_prepare.c index 697b1c84e..7b92db603 100644 --- a/tests/sdl2_image_prepare.c +++ b/tests/sdl2_image_prepare.c @@ -48,7 +48,7 @@ int main() { printf("prepare..\n"); - assert(emscripten_async_prepare("screenshot.jpg", ready, NULL) == 0); + assert(emscripten_run_preload_plugins("screenshot.jpg", ready, NULL) == 0); return 0; } diff --git a/tests/sdl_image_prepare.c b/tests/sdl_image_prepare.c index 1c4d72187..20a01b48f 100644 --- a/tests/sdl_image_prepare.c +++ b/tests/sdl_image_prepare.c @@ -42,7 +42,7 @@ int main() { printf("prepare..\n"); - assert(emscripten_async_prepare("screenshot.jpg", ready, NULL) == 0); + assert(emscripten_run_preload_plugins("screenshot.jpg", ready, NULL) == 0); return 0; } diff --git a/tests/sdl_image_prepare_data.c b/tests/sdl_image_prepare_data.c index 043ace478..f12d2e087 100644 --- a/tests/sdl_image_prepare_data.c +++ b/tests/sdl_image_prepare_data.c @@ -63,8 +63,8 @@ int main() { fread(buffer, SIZE, 1, f); fclose(f); - emscripten_async_prepare_data(buffer, SIZE, "jpg", (void*)25, ready, NULL); - emscripten_async_prepare_data(buffer, SIZE, "jpg", (void*)33, ready, NULL); // twice to see different filenames + emscripten_run_preload_plugins_data(buffer, SIZE, "jpg", (void*)25, ready, NULL); + emscripten_run_preload_plugins_data(buffer, SIZE, "jpg", (void*)33, ready, NULL); // twice to see different filenames return 0; }