Enhance examples (#17)

* enhance examples

* doc enhancement

* mv pool to stack

* missing ; and doc update

fix readme example image link

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.23)
 
-project(pixelarium VERSION 0.0.8)
+project(pixelarium VERSION 0.0.9)
 
 set(CMAKE_VERBOSE_MAKEFILE ON)
 set(CMAKE_CXX_STANDARD 23)

Readme.org

@@ -63,5 +63,28 @@ If you want to specify compiler settings and options which are not defined in a
   cmake --build build
 #+end_src
 
-* TODO Example
+* Usage
 
+All there is to do in order to get an initial window on screen is to create an instance of [[file:lib/app/AppGLFW.hpp][=AppGLFW=]] (or one of its child classes) and start it.
+
+#+begin_src C++
+  unique_ptr<ILog> logger = make_unique<SpdLogger>("logfile.log", "loggername");
+  ImageResourcePool image_pool;
+
+  auto app {DefaultApp(*logger, image_pool)};
+  app.Start();
+#+end_src
+
+This will get the default application on screen which looks like
+[[file:doc/figures/default-app.png]]
+
+
+The [[file:examples/][examples]] directory aims to showcase a few usage examples of this project.
+
+** [[file:examples/simple/][simple]]
+
+This is the most straight-forward usage of Pixelarium. It simply instantiates a [[file:lib/app/DefaultApp.hpp][=DefaultApp=]] and runs it.
+
+** [[file:examples/custom_0/][custom_0]]
+
+This is meant to showcase that [[file:lib/app/DefaultApp.hpp][=DefaultApp=]] ([[file:lib/app/AppGLFW.hpp][=AppGLFW=]] as well) is meant to be customized via inheritance.

doc/Doxyfile.in

@@ -9,6 +9,7 @@ INPUT                  = @PROJECT_SOURCE_DIR@/lib/app \
                          @PROJECT_SOURCE_DIR@/lib/utilities \
                          @PROJECT_SOURCE_DIR@/lib/rendering \
                          @PROJECT_SOURCE_DIR@/lib/resources
+IMAGE_PATH             = @PROJECT_SOURCE_DIR@/doc/figures
 
 DOXYFILE_ENCODING      = UTF-8
 GENERATE_LATEX         = NO

doc/index.md

@@ -52,5 +52,30 @@ If you want to specify compiler settings and options which are not defined in a
     cmake -B build -S .
     cmake --build build
 
+# Usage
+
+The [examples](https://github.com/m-aXimilian/pixelarium/tree/fd400bf545ade029696c21119a50cf4bb67ffbac/examples) directory aims to showcase a few usage examples of this project.
+
+All there is to do in order to get an initial window on screen is to create an instance of [`AppGLFW`](https://github.com/m-aXimilian/pixelarium/blob/fd400bf545ade029696c21119a50cf4bb67ffbac/lib/app/AppGLFW.hpp) (or one of its child classes) and start it.
+
+```cpp
+  unique_ptr<ILog> logger = make_unique<SpdLogger>("logfile.log", "loggername");
+  ImageResourcePool image_pool;
+
+  auto app {DefaultApp(*logger, image_pool)};
+  app.Start();
+```
 
 
+![Default App Screenshot](default-app.png)
+
+
+## simple
+
+This is the most straight-forward usage of Pixelarium. It simply instantiates a [`DefaultApp`](https://github.com/m-aXimilian/pixelarium/blob/fd400bf545ade029696c21119a50cf4bb67ffbac/lib/app/DefaultApp.hpp) and runs it.
+
+
+## custom_0
+
+This is meant to showcase that [`DefaultApp`]((https://github.com/m-aXimilian/pixelarium/blob/fd400bf545ade029696c21119a50cf4bb67ffbac/lib/app/DefaultApp.hpp)) ([`AppGLFW`](https://github.com/m-aXimilian/pixelarium/blob/fd400bf545ade029696c21119a50cf4bb67ffbac/lib/app/AppGLFW.hpp) as well) can be customized via inheritance.
+

doc/versions.md

@@ -2,6 +2,7 @@
 
 | Version | Description                                                                                                 |
 |:-------:|:------------------------------------------------------------------------------------------------------------|
+|   0.0.9 | Improve documentation, add example for `DefaultApp` override semantics                                      |
 |   0.0.8 | Init example projects                                                                                       |
 |   0.0.7 | Refactors image gallery logic from `DefaultApp` into a separate module                                      |
 |   0.0.6 | Added documentation-only option `PIXELARIUM_BUILD_DOCS_ONLY`, libCZI upgrade to main branch CI improvements |

examples/CMakeLists.txt

@@ -1 +1,2 @@
 add_subdirectory(simple)
+add_subdirectory(custom_0)

examples/custom_0/CMakeLists.txt

@@ -0,0 +1,22 @@
+set(SRC
+  ${CMAKE_CURRENT_SOURCE_DIR}/custom_0.cpp)
+
+set(CUSTOM_0_NAME "${PROJECT_NAME}_custom_app")
+
+add_executable(${CUSTOM_0_NAME} ${SRC})
+
+target_link_libraries(${CUSTOM_0_NAME}
+  PRIVATE pixelariumimagelib
+  PRIVATE pixelariumrenderlib
+  PRIVATE pixelariumutilslib
+  PRIVATE pixelariumresourcelib
+  PRIVATE pixelariumapplicationlib)
+
+target_include_directories(${CUSTOM_0_NAME}
+  PRIVATE ${PROJECT_SOURCE_DIR}/src
+  PRIVATE ${PROJECT_SOURCE_DIR}/lib
+  PRIVATE ${PROJECT_SOURCE_DIR}/lib/imaging
+  PRIVATE ${PROJECT_SOURCE_DIR}/lib/app
+  PRIVATE ${spdlog_DIR}/include
+  PRIVATE ${LIBCZI_INCLUDE_DIR}
+  PRIVATE ${CMAKE_CURRENT_BINARY_DIR})

examples/custom_0/custom_0.cpp

@@ -0,0 +1,53 @@
+#include <memory>
+#include <string>
+
+#include "DefaultApp.hpp"
+#include "resources/resource.hpp"
+#include "utilities/ILog.hpp"
+#include "utilities/SpdLogger.hpp"
+
+using namespace pixelarium;
+using namespace std;
+using Log = utils::log::ILog;
+using Pool = resources::ImageResourcePool;
+
+// setup a logger
+#ifdef _WIN32
+unique_ptr<Log> logger{
+    make_unique<utils::log::SpdLogger>(string(getenv("APPDATA")) + "/pixelarium/simple_app.log", "default")};
+#else
+unique_ptr<Log> logger{
+    make_unique<utils::log::SpdLogger>(string(getenv("HOME")) + "/.cache/pixelarium/simple_app.log", "default")};
+#endif
+
+// create a custom app inheriting from the library's default app
+class MyApp : public application::DefaultApp
+{
+   public:
+    MyApp(const Log& log, Pool& pool) : application::DefaultApp(log, pool) {}
+
+    // override some of the defaults member functions
+    void Run() override;
+    void MenuBarOptionsColumn1() override {};
+    void MenuBarOptionsColumn2() override {};
+};
+
+int main()
+{
+    // some initial log message
+    logger->Info(std::format("{}: Starting Application {}", __FUNCTION__, "Pixelarium"));
+
+    // instantiate an image pool for the application
+    resources::ImageResourcePool image_pool;
+
+    // create a custom application, inject its dependencies and start it
+    auto app{MyApp(*logger, image_pool)};
+
+    app.Start();
+}
+
+void MyApp::Run()
+{
+    this->gallery_.RenderGallery();
+    this->gallery_.RenderImages();
+}

examples/simple/CMakeLists.txt

@@ -1,5 +1,5 @@
 set(SRC
-  ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+  ${CMAKE_CURRENT_SOURCE_DIR}/simple.cpp)
 
 set(SIMPLE_NAME "${PROJECT_NAME}_SIMPLE")
 

examples/simple/main.cpp

@@ -1,26 +0,0 @@
-#include <memory>
-
-#include "DefaultApp.hpp"
-#include "resources/resource.hpp"
-#include "utilities/ILog.hpp"
-#include "utilities/SpdLogger.hpp"
-
-int main(int argc, char** argv)
-{
-    using namespace pixelarium;
-    using namespace std;
-    unique_ptr<utils::log::ILog> logger;
-#ifdef _WIN32
-    logger = make_unique<utils::log::SpdLogger>(string(getenv("APPDATA")) + "/pixelarium/logfile.log", "default");
-#else
-    logger = make_unique<utils::log::SpdLogger>(std::string(getenv("HOME")) + "/.cache/pixelarium/log.log", "default");
-#endif
-    logger->Info(std::format("{}: Starting Application {}", __FUNCTION__, "Pixelarium"));
-
-    logger->ChangeLevel(utils::log::LogLevel::kDebug);
-    auto image_pool{std::make_unique<resources::ImageResourcePool>()};
-
-    application::DefaultApp app = application::DefaultApp(*logger, *image_pool);
-
-    app.Start();
-}

examples/simple/simple.cpp

@@ -0,0 +1,34 @@
+#include <memory>
+
+#include "DefaultApp.hpp"
+#include "resources/resource.hpp"
+#include "utilities/ILog.hpp"
+#include "utilities/SpdLogger.hpp"
+
+using namespace pixelarium;
+using namespace std;
+using Log = utils::log::ILog;
+using Pool = resources::ImageResourcePool;
+
+// setup a logger
+#ifdef _WIN32
+unique_ptr<Log> logger{
+    make_unique<utils::log::SpdLogger>(string(getenv("APPDATA")) + "/pixelarium/simple_app.log", "default")};
+#else
+unique_ptr<Log> logger{
+    make_unique<utils::log::SpdLogger>(string(getenv("HOME")) + "/.cache/pixelarium/simple_app.log", "default")};
+#endif
+
+int main()
+{
+    // some initial log message and default log level setting
+    logger->Info(format("{}: Starting Application {}", __FUNCTION__, "Pixelarium"));
+    logger->ChangeLevel(utils::log::LogLevel::kDebug);
+
+    // instantiate an image pool for the application
+    resources::ImageResourcePool image_pool;
+
+    // create an application, inject its dependencies and start it
+    auto app{application::DefaultApp(*logger, image_pool)};
+    app.Start();
+}

lib/app/DefaultApp.cpp

@@ -35,9 +35,9 @@ void DefaultApp::MenuBarOptionsColumn2()
 void DefaultApp::Run()
 {
     if (demop_) ImGui::ShowDemoWindow(&this->demop_);
-    if (image_listp_) this->gallery.RenderGallery();
+    if (image_listp_) this->gallery_.RenderGallery();
 
-    this->gallery.RenderImages();
+    this->gallery_.RenderImages();
 }
 
 void DefaultApp::LoadImage()

lib/app/DefaultApp.hpp

@@ -17,9 +17,9 @@ class DefaultApp : public AppGLFW
 {
    public:
     DefaultApp(const utils::log::ILog& log, pixelarium::resources::ImageResourcePool& pool)
-        : application::AppGLFW(log), pool_(pool), gallery(log, pool)
+        : application::AppGLFW(log), pool_(pool), gallery_(log, pool)
     {
-        gallery.SetLoadFunction([&]() -> void { this->LoadImage(); });
+        gallery_.SetLoadFunction([&]() -> void { this->LoadImage(); });
     }
 
    protected:
@@ -27,14 +27,16 @@ class DefaultApp : public AppGLFW
     void MenuBarOptionsColumn2() override;
     void Run() override;
 
-   private:
+   protected:
+    resources::ImageResourcePool& pool_;
+    application::PixelariumImageGallery gallery_;
+
+   protected:
     void LoadImage();
 
    private:
-    resources::ImageResourcePool& pool_;
     bool image_listp_{true};
     bool demop_{false};
     ImVec2 curr_dim_;
-    application::PixelariumImageGallery gallery;
 };
 }  // namespace pixelarium::application