diff --git a/CMakeLists.txt b/CMakeLists.txt index 11a9764..5047fc3 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/Readme.org b/Readme.org index 62d4105..70033d1 100644 --- a/Readme.org +++ b/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 logger = make_unique("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. diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index cdbae05..26db1ba 100644 --- a/doc/Doxyfile.in +++ b/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 diff --git a/doc/figures/default-app.png b/doc/figures/default-app.png new file mode 100644 index 0000000..a414044 Binary files /dev/null and b/doc/figures/default-app.png differ diff --git a/doc/index.md b/doc/index.md index 0ae9f1c..6fce9d9 100644 --- a/doc/index.md +++ b/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 logger = make_unique("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. + diff --git a/doc/versions.md b/doc/versions.md index 14477f5..b9954ce 100644 --- a/doc/versions.md +++ b/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 | diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index c01ac80..a6fb3fa 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -1 +1,2 @@ add_subdirectory(simple) +add_subdirectory(custom_0) diff --git a/examples/custom_0/CMakeLists.txt b/examples/custom_0/CMakeLists.txt new file mode 100644 index 0000000..2bd3ed3 --- /dev/null +++ b/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}) diff --git a/examples/custom_0/custom_0.cpp b/examples/custom_0/custom_0.cpp new file mode 100644 index 0000000..16157ea --- /dev/null +++ b/examples/custom_0/custom_0.cpp @@ -0,0 +1,53 @@ +#include +#include + +#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 logger{ + make_unique(string(getenv("APPDATA")) + "/pixelarium/simple_app.log", "default")}; +#else +unique_ptr logger{ + make_unique(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(); +} diff --git a/examples/simple/CMakeLists.txt b/examples/simple/CMakeLists.txt index 03d8c45..6b40178 100644 --- a/examples/simple/CMakeLists.txt +++ b/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") diff --git a/examples/simple/main.cpp b/examples/simple/main.cpp deleted file mode 100644 index 9e81e19..0000000 --- a/examples/simple/main.cpp +++ /dev/null @@ -1,26 +0,0 @@ -#include - -#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 logger; -#ifdef _WIN32 - logger = make_unique(string(getenv("APPDATA")) + "/pixelarium/logfile.log", "default"); -#else - logger = make_unique(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()}; - - application::DefaultApp app = application::DefaultApp(*logger, *image_pool); - - app.Start(); -} diff --git a/examples/simple/simple.cpp b/examples/simple/simple.cpp new file mode 100644 index 0000000..13df2b7 --- /dev/null +++ b/examples/simple/simple.cpp @@ -0,0 +1,34 @@ +#include + +#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 logger{ + make_unique(string(getenv("APPDATA")) + "/pixelarium/simple_app.log", "default")}; +#else +unique_ptr logger{ + make_unique(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(); +} diff --git a/lib/app/DefaultApp.cpp b/lib/app/DefaultApp.cpp index 45ffb61..04ffde5 100644 --- a/lib/app/DefaultApp.cpp +++ b/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() diff --git a/lib/app/DefaultApp.hpp b/lib/app/DefaultApp.hpp index 76a9873..1dde81a 100644 --- a/lib/app/DefaultApp.hpp +++ b/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