feat: add basic examples

.gitattributes

@@ -24,5 +24,4 @@
 *.lib binary
 
 # vendored code
-extensions/pl_gltf_extension.c linguist-vendored
-dependencies/*                 linguist-vendored
+dependencies/* linguist-vendored

.github/workflows/build.yml

@@ -44,10 +44,17 @@ jobs:
         cd $GITHUB_WORKSPACE
         cd scripts
         python gen_build.py
+        python gen_examples.py
         cd ../src
         call build.bat
-        if not exist ../out/pilot_light.exe exit 1
+        cd ../examples
+        call build.bat
         if not exist ../out/app.dll exit 1
+        if not exist ../out/example_0.dll exit 1
+        if not exist ../out/example_1.dll exit 1
+        if not exist ../out/example_2.dll exit 1
+        if not exist ../out/example_3.dll exit 1
+        if not exist ../out/pilot_light.exe exit 1
         if not exist ../out/pl_graphics_ext.dll exit 1
         if not exist ../out/pl_image_ext.dll exit 1
         if not exist ../out/pl_stats_ext.dll exit 1
@@ -93,15 +100,23 @@ jobs:
         cd $GITHUB_WORKSPACE
         cd scripts
         python3 gen_build.py
+        python3 gen_examples.py
         cd ../src
         chmod +x build.sh
         ./build.sh
+        cd ../examples
+        chmod +x build.sh
+        ./build.sh
         cd ..
         cd out
         chmod +x pilot_light
         cd ..
         test -f ./out/pilot_light || exit 1
         test -f ./out/app.dylib || exit 1
+        test -f ./out/example_0.dylib || exit 1
+        test -f ./out/example_1.dylib || exit 1
+        test -f ./out/example_2.dylib || exit 1
+        test -f ./out/example_3.dylib || exit 1
         test -f ./out/pl_stats_ext.dylib || exit 1
         test -f ./out/pl_image_ext.dylib || exit 1
         test -f ./out/pl_debug_ext.dylib || exit 1
@@ -160,15 +175,23 @@ jobs:
         cd $GITHUB_WORKSPACE
         cd scripts
         python3 gen_build.py
+        python3 gen_examples.py
         cd ../src
         chmod +x build.sh
         ./build.sh
+        cd ../examples
+        chmod +x build.sh
+        ./build.sh
         cd ..
         cd out
         chmod +x pilot_light
         cd ..
         test -f ./out/pilot_light || exit 1
         test -f ./out/app.so || exit 1
+        test -f ./out/example_0.so || exit 1
+        test -f ./out/example_1.so || exit 1
+        test -f ./out/example_2.so || exit 1
+        test -f ./out/example_3.so || exit 1
         test -f ./out/pl_graphics_ext.so || exit 1
         test -f ./out/pl_image_ext.so || exit 1
         test -f ./out/pl_stats_ext.so || exit 1

.gitignore

@@ -8,11 +8,14 @@ out/
 
 # debug files
 src/*.pdb
+examples/*.pdb
 tests/*.pdb
 
 # build scripts
 src/*.bat
 src/*.sh
+examples/*.bat
+examples/*.sh
 tests/*.bat
 tests/*.sh
 

examples/README.md

@@ -0,0 +1,51 @@
+## Examples
+The following examples have been provided to help newcomers become acclimated to using **Pilot Light**. The examples can be found in the **examples** directory.
+
+To run the examples, first follow the build instructions [here](https://github.com/PilotLightTech/pilotlight/wiki/Building).
+
+Next:
+
+### Windows
+Example for running example 0:
+```bash
+cd pilotlight/scripts
+python gen_examples.py
+cd ../examples
+build.bat
+
+cd ../out
+pilot_light.exe -a example_0
+```
+### MacOS & Linux
+Example for running example 0:
+```bash
+cd pilotlight/scripts
+python3 gen_examples.py
+cd ../examples
+chmod +x build.sh
+./build.sh
+
+cd ../out
+pilot_light -a example_0 
+```
+
+## Example 0 - Minimal App (example_0.c)
+Demonstrates the bare minimumal app. This app loads, runs 50 iterations of the update function (printing to console), then exits.
+
+## Example 1 - API Loading (example_1.c)
+Demonstrates:
+* loading APIs
+* hot reloading
+
+## Example 2 - UI Library (example_2.c)
+Demonstrates:
+* loading APIs
+* hot reloading
+* loading extensions
+* UI library
+
+## Example 3 - 3D Debug Drawing (example_3.c)
+* loading APIs
+* hot reloading
+* loading extensions
+* 3D debug drawing extension

examples/example_0.c

@@ -0,0 +1,86 @@
+/*
+   example_0.c
+     - demonstrates minimal app
+*/
+
+/*
+Index of this file:
+// [SECTION] includes
+// [SECTION] pl_app_load
+// [SECTION] pl_app_shutdown
+// [SECTION] pl_app_resize
+// [SECTION] pl_app_update
+*/
+
+//-----------------------------------------------------------------------------
+// [SECTION] includes
+//-----------------------------------------------------------------------------
+
+#include <stdio.h>
+#include "pilotlight.h"
+#include "pl_ui.h"
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_load
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void*
+pl_app_load(plApiRegistryI* ptApiRegistry, void* pAppData)
+{
+
+    // NOTE: on first load, "pAppData" will be NULL
+
+    // retrieve the data registry API, this is the API used for sharing data
+    // between extensions & the runtime
+    const plDataRegistryI* ptDataRegistry = ptApiRegistry->first(PL_API_DATA_REGISTRY);
+
+    // retrieve the UI context (provided by the runtime) and
+    // set it (required to use plIO for "talking" with runtime)
+    plUiContext* ptUIContext = ptDataRegistry->get_data("context");
+    pl_set_context(ptUIContext);
+
+    // return optional application memory
+    return NULL;
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_shutdown
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_shutdown(void* pAppData)
+{
+    printf("shutting down\n");
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_resize
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_resize(void* pAppData)
+{
+    // NOTE: this function is not used here since this example doesn't have a window
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_update
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_update(void* pAppData)
+{
+
+    pl_new_frame(); // must be called once at the beginning of a frame
+
+    static int iIteration = 0;
+
+    printf("iteration: %d\n", iIteration++);
+
+    // shutdown main event loop after 50 iterations
+    if(iIteration == 50)
+    {
+        plIO* ptIO = pl_get_io();
+        ptIO->bRunning = false;
+    }
+}

examples/example_1.c

@@ -0,0 +1,140 @@
+/*
+   example_1.c
+     - demonstrates loading APIs
+     - demonstrates hot reloading
+*/
+
+/*
+Index of this file:
+// [SECTION] includes
+// [SECTION] structs
+// [SECTION] apis
+// [SECTION] pl_app_load
+// [SECTION] pl_app_shutdown
+// [SECTION] pl_app_resize
+// [SECTION] pl_app_update
+*/
+
+//-----------------------------------------------------------------------------
+// [SECTION] includes
+//-----------------------------------------------------------------------------
+
+#include <stdio.h>
+#include <string.h> // memset
+#include "pilotlight.h"
+#include "pl_ui.h"
+#include "pl_os.h" // window api
+
+//-----------------------------------------------------------------------------
+// [SECTION] structs
+//-----------------------------------------------------------------------------
+
+typedef struct _plAppData
+{
+    plWindow* ptWindow;
+} plAppData;
+
+//-----------------------------------------------------------------------------
+// [SECTION] apis
+//-----------------------------------------------------------------------------
+
+const plWindowI* gptWindows = NULL;
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_load
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void*
+pl_app_load(plApiRegistryI* ptApiRegistry, plAppData* ptAppData)
+{
+    // NOTE: on first load, "pAppData" will be NULL but on reloads
+    //       it will be the value returned from this function
+
+    // retrieve the data registry API, this is the API used for sharing data
+    // between extensions & the runtime
+    const plDataRegistryI* ptDataRegistry = ptApiRegistry->first(PL_API_DATA_REGISTRY);
+
+    // retrieve the UI context (provided by the runtime) and
+    // set it (required to use plIO for "talking" with runtime & keyboard/mouse input)
+    plUiContext* ptUIContext = ptDataRegistry->get_data("context");
+    pl_set_context(ptUIContext);
+
+    // if "ptAppData" is a valid pointer, then this function is being called
+    // during a hot reload.
+    if(ptAppData)
+    {
+        printf("Hot reload!\n");
+
+        // re-retrieve the windows API since we are now in
+        // a different dll/so
+        gptWindows = ptApiRegistry->first(PL_API_WINDOW);
+
+        // return the same memory again
+        return ptAppData;
+    }
+
+    // this path is taken only during first load, so we
+    // allocate app memory here
+    ptAppData = malloc(sizeof(plAppData));
+    memset(ptAppData, 0, sizeof(plAppData));
+
+    // load required apis (NULL if not available)
+    gptWindows = ptApiRegistry->first(PL_API_WINDOW);
+
+    // use window API to create a window
+    const plWindowDesc tWindowDesc = {
+        .pcName  = "Example 1",
+        .iXPos   = 200,
+        .iYPos   = 200,
+        .uWidth  = 600,
+        .uHeight = 600,
+    };
+    ptAppData->ptWindow = gptWindows->create_window(&tWindowDesc);
+
+    // return app memory
+    return ptAppData;
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_shutdown
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_shutdown(plAppData* ptAppData)
+{
+    // perform any cleanup here
+    gptWindows->destroy_window(ptAppData->ptWindow);
+
+    // free app memory
+    free(ptAppData);
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_resize
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_resize(plAppData* ptAppData)
+{
+    // perform any operations required during a window resize
+    plIO* ptIO = pl_get_io();
+    printf("resize to %d, %d\n", (int)ptIO->afMainViewportSize[0], (int)ptIO->afMainViewportSize[1]);
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] pl_app_update
+//-----------------------------------------------------------------------------
+
+PL_EXPORT void
+pl_app_update(plAppData* ptAppData)
+{
+
+    pl_new_frame(); // must be called once at the beginning of a frame
+
+    // check for key press
+    if(pl_is_key_pressed(PL_KEY_P, true))
+    {
+        printf("P key pressed!\n");
+    }
+
+}