From 933918454f16af118a3cb9e1359a00bca589d7e7 Mon Sep 17 00:00:00 2001 From: Syping Date: Sun, 2 Apr 2023 21:33:48 +0200 Subject: [PATCH] libragephoto 0.3.0 release - update README.md - update documentation - ragephoto-gtkviewer: fix error uint8_t -> int32_t, NULL -> nullptr - ragephoto-qtviewer: fix error uint8_t -> int32_t - RagePhotoA: fix documentation, fix error() - RagePhotoC: add brief --- README.md | 8 + doc/Doxyfile.in | 10 +- doc/build.doc | 29 ++++ doc/index.doc | 20 ++- doc/usage.doc | 189 ++++++++++++++++++++++ examples/ragephoto-gtkviewer/src/main.cpp | 6 +- examples/ragephoto-qtviewer/src/main.cpp | 2 +- src/RagePhotoA.h | 10 +- src/RagePhotoC.h | 5 +- 9 files changed, 260 insertions(+), 19 deletions(-) create mode 100644 doc/build.doc create mode 100644 doc/usage.doc diff --git a/README.md b/README.md index 1b4b5fd..98482b7 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ sudo cmake --install libragephoto-build ``` ##### Optional CMake flags +`-DCMAKE_CXX_STANDARD=17` +`-DRAGEPHOTO_BENCHMARK=ON` `-DRAGEPHOTO_C_API=OFF` `-DRAGEPHOTO_DOC=ON` `-DRAGEPHOTO_EXAMPLE_GTKVIEWER=ON` @@ -28,6 +30,12 @@ sudo cmake --install libragephoto-build [RagePhoto C API](https://libragephoto.syping.de/doc/RagePhotoC_8h.html) [RagePhoto C++ API](https://libragephoto.syping.de/doc/classRagePhoto.html) +#### libragephoto Documentation + +[Main Page](https://libragephoto.syping.de/doc/) +[Build libragephoto](https://libragephoto.syping.de/doc/Build.html) +[Using libragephoto](https://libragephoto.syping.de/doc/Usage.html) + #### How to Use ragephoto-extract ```bash diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 2090626..45c9523 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -1,12 +1,16 @@ PROJECT_NAME = "libragephoto" PROJECT_NUMBER = "Version: @ragephoto_VERSION@" INPUT = "@CMAKE_CURRENT_SOURCE_DIR@/index.doc" \ + "@CMAKE_CURRENT_SOURCE_DIR@/build.doc" \ + "@CMAKE_CURRENT_SOURCE_DIR@/usage.doc" \ "src" OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@" EXTRACT_PRIVATE = NO ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES -PREDEFINED = "protected=private" \ - "__cplusplus" \ - "@LIBRAGEPHOTO_API@" +PREDEFINED = "__cplusplus=201703L" \ + "RAGEPHOTO_CXX_STD=17" \ + "@LIBRAGEPHOTO_API@" \ + "LIBRAGEPHOTO_C_BINDING=" \ + "LIBRAGEPHOTO_CXX_BINDING=" diff --git a/doc/build.doc b/doc/build.doc new file mode 100644 index 0000000..809d092 --- /dev/null +++ b/doc/build.doc @@ -0,0 +1,29 @@ +/*! \page Build Build libragephoto + +Keep sure you have CMake and a C++ compiler installed, then do the following or the equivalent necessary. + +

Build libragephoto

+\code{.sh} +cmake -B libragephoto-build libragephoto +cmake --build libragephoto-build +\endcode + +

Install libragephoto

+\code{.sh} +sudo cmake --install libragephoto-build +\endcode + +To customise your libragephoto build, the following Optional CMake flags can be used + +

Optional CMake flags

+\code{.sh} +-DCMAKE_CXX_STANDARD=17 +-DRAGEPHOTO_BENCHMARK=ON +-DRAGEPHOTO_C_API=OFF +-DRAGEPHOTO_DOC=ON +-DRAGEPHOTO_EXAMPLE_GTKVIEWER=ON +-DRAGEPHOTO_EXAMPLE_QTVIEWER=ON +-DRAGEPHOTO_EXTRACT=OFF +-DRAGEPHOTO_STATIC=ON +\endcode +*/ diff --git a/doc/index.doc b/doc/index.doc index 0882e44..5b30a4c 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -7,12 +7,20 @@ - Export RAGE Photos to jpeg with ragephoto-extract - High Efficient and Simple C/C++ API -Main Class: -- RagePhoto +Getting started +\subpage Build "Build libragephoto" +\subpage Usage "Using libragephoto" -Project Pages: -- https://git.syping.de/Syping/libragephoto -- https://gitlab.com/Syping/libragephoto -- https://github.com/Syping/libragephoto +Reference +RagePhoto (C++ API) +RagePhotoA (C++ API based on C API) +RagePhotoC.h (C API) +RagePhotoData (Data Object Struct) +RagePhotoFormatParser (Custom Format Parser Struct) + +Project Pages +https://git.syping.de/Syping/libragephoto +https://gitlab.com/Syping/libragephoto +https://github.com/Syping/libragephoto */ diff --git a/doc/usage.doc b/doc/usage.doc new file mode 100644 index 0000000..d607d3e --- /dev/null +++ b/doc/usage.doc @@ -0,0 +1,189 @@ +/*! \page Usage Using libragephoto + +

C++ API

+ +

Including and using RagePhoto

+ +Include RagePhoto.h or RagePhotoA.h + +\code{.cpp} +#include +\endcode + +Create a RagePhoto object + +\code{.cpp} +RagePhoto ragePhoto; +\endcode + +

Loading a Photo

+ +From a file using RagePhoto::loadFile + +\code{.cpp} +const char* filename = "PGTA5123456789"; +const bool loaded = ragePhoto.loadFile(filename); +\endcode + +From a file using RagePhoto::load(const std::string&) + +\code{.cpp} +// Reading file +const char* filename = "PGTA5123456789"; +std::ifstream ifs(filename, std::ios::in | std::ios::binary); +if (!ifs.is_open()) + return; +std::string sdata(std::istreambuf_iterator{ifs}, {}); +ifs.close(); + +// Loading file +const bool loaded = ragePhoto.load(sdata); +\endcode + +From a char* using RagePhoto::load(const char*, size_t) + +\code{.cpp} +const bool loaded = ragePhoto.load(data, size); +\endcode + +

Using a Photo

+ +\code{.cpp} +// Returns the Photo Format +const uint32_t format = ragePhoto.format(); + +// Returns the JPEG as std::string +const std::string jpeg = ragePhoto.jpeg(); + +// Returns the JPEG as const char* +const char* jpeg = ragePhoto.jpegData(); +const uint32_t size = ragePhoto.jpegSize(); + +// Returns the JSON +const char* json = ragePhoto.json(); + +// Returns the Title +const char* title = ragePhoto.title(); +\endcode + +Detecting if Photo is from GTA V or RDR 2 + +\code{.cpp} +switch (ragePhoto.format()) { +case RagePhoto::PhotoFormat::GTA5: + std::cout << "GTA V format detected" << std::endl; + break; +case RagePhoto::PhotoFormat::RDR2: + std::cout << "RDR 2 format detected" << std::endl; + break; +default: + std::cout << "Unknown format detected" << std::endl; +} +\endcode + +Saving the JPEG from a Photo + +\code{.cpp} +// Example saveJpeg function +bool saveJpeg(RagePhoto* ragePhoto, const std::string& filename) { + std::ofstream ofs(filename, std::ios::out | std::ios::binary | std::ios::trunc); + if (!ofs.is_open()) + return false; + ofs << ragePhoto->jpeg(); + const bool saved = ofs.good(); + ofs.close(); + return saved; +} + +// Using the saveJpeg function +const char* filename = "PGTA5123456789"; +const bool saved = saveJpeg(&ragePhoto, filename); +\endcode + +Using the JPEG in GTK+ (gtkmm) + +\code{.cpp} +// Writing pixbuf loader +GdkPixbufLoader* pixbuf_loader = gdk_pixbuf_loader_new(); +gdk_pixbuf_loader_write(pixbuf_loader, reinterpret_cast(ragePhoto.jpegData()), ragePhoto.jpegSize(), nullptr); +GdkPixbuf* pixbuf = gdk_pixbuf_loader_get_pixbuf(pixbuf_loader); +gdk_pixbuf_loader_close(pixbuf_loader, nullptr); + +// Set image +Gtk::Image image; +image.set(Glib::wrap(pixbuf)); +\endcode + +Using the JPEG in Qt + +\code{.cpp} +// Returns the JPEG as QImage +const QImage image = QImage::fromData(QByteArray::fromRawData(ragePhoto.jpegData(), ragePhoto.jpegSize()), "JPEG"); + +// Loading the JPEG in QImage +QImage image; +const bool loaded = image.loadFromData(QByteArray::fromRawData(ragePhoto.jpegData(), ragePhoto.jpegSize()), "JPEG"); +\endcode + +Using the JSON in Boost.JSON + +\code{.cpp} +std::error_code ec; +const boost::json::value jv = boost::json::parse(ragePhoto.json(), ec); +if (ec) + return; +\endcode + +Using the JSON in Qt + +\code{.cpp} +const QByteArray json = ragePhoto.json(); +const QJsonDocument jd = QJsonDocument::fromJson(json); +if (jd.isNull()) + return; +\endcode + +

Detect Photo errors

+ +\code{.cpp} +const int32_t error = ragePhoto.error(); +switch (error) { +case RagePhoto::Error::NoFormatIdentifier: + std::cout << "No format identifier" << std::endl; + break; +case RagePhoto::Error::IncompatibleFormat: + std::cout << "Incompatible format" << std::endl; + break; +// Detect for more errors here... +case RagePhoto::Error::NoError: + std::cout << "No error detected" << std::endl; + break; +default: + std::cout << "Unknown error detected" << std::endl; +} +\endcode + +Available error codes: RagePhoto::Error + +

Including libragephoto in a CMake project

+ +

Using PkgConfig

+ +\code{.cmake} +find_package(PkgConfig REQUIRED) +pkg_check_modules(RAGEPHOTO REQUIRED ragephoto) +target_compile_options(your_project PRIVATE ${RAGEPHOTO_CFLAGS}) +target_link_libraries(your_project PRIVATE ${RAGEPHOTO_LIBRARIES}) +if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.13.0") + target_link_directories(your_project PRIVATE ${RAGEPHOTO_LIBRARY_DIRS}) +endif() +target_include_directories(your_project PRIVATE ${RAGEPHOTO_INCLUDE_DIRS}) +\endcode + +

Using add_subdirectory

+ +\code{.cmake} +add_subdirectory(src/libragephoto) +target_link_libraries(your_project PRIVATE ragephoto) +\endcode +*/ diff --git a/examples/ragephoto-gtkviewer/src/main.cpp b/examples/ragephoto-gtkviewer/src/main.cpp index e865ef5..845f003 100644 --- a/examples/ragephoto-gtkviewer/src/main.cpp +++ b/examples/ragephoto-gtkviewer/src/main.cpp @@ -39,7 +39,7 @@ bool readPhotoFile(const std::string &filename, Gtk::Window *win, Gtk::Image *im RagePhoto ragePhoto; const bool loaded = ragePhoto.load(data); if (!loaded) { - const uint8_t error = ragePhoto.error(); + const int32_t error = ragePhoto.error(); if (error <= RagePhoto::PhotoReadError) { Gtk::MessageDialog msg(*win, "Failed to read photo: " + filename, false, Gtk::MESSAGE_WARNING, Gtk::BUTTONS_OK, true); msg.set_title("Open Photo"); @@ -48,9 +48,9 @@ bool readPhotoFile(const std::string &filename, Gtk::Window *win, Gtk::Image *im } } GdkPixbufLoader *pixbuf_loader = gdk_pixbuf_loader_new(); - gdk_pixbuf_loader_write(pixbuf_loader, reinterpret_cast(ragePhoto.jpegData()), ragePhoto.jpegSize(), NULL); + gdk_pixbuf_loader_write(pixbuf_loader, reinterpret_cast(ragePhoto.jpegData()), ragePhoto.jpegSize(), nullptr); GdkPixbuf *pixbuf = gdk_pixbuf_loader_get_pixbuf(pixbuf_loader); - gdk_pixbuf_loader_close(pixbuf_loader, NULL); + gdk_pixbuf_loader_close(pixbuf_loader, nullptr); image->set(Glib::wrap(pixbuf)); win->set_title("RagePhoto GTK Photo Viewer - " + std::string(ragePhoto.title())); return true; diff --git a/examples/ragephoto-qtviewer/src/main.cpp b/examples/ragephoto-qtviewer/src/main.cpp index 3b147f6..6df9c6b 100644 --- a/examples/ragephoto-qtviewer/src/main.cpp +++ b/examples/ragephoto-qtviewer/src/main.cpp @@ -38,7 +38,7 @@ bool readPhotoFile(const QString &filename, QMainWindow *mainWindow, QLabel *pho RagePhoto ragePhoto; const bool loaded = ragePhoto.load(fileData.data(), static_cast(fileData.size())); if (!loaded) { - const uint8_t error = ragePhoto.error(); + const int32_t error = ragePhoto.error(); if (error <= RagePhoto::PhotoReadError) { QMessageBox::warning(mainWindow, "Open Photo", "Failed to read photo: " + filename); return false; diff --git a/src/RagePhotoA.h b/src/RagePhotoA.h index 83085b5..3e1203d 100644 --- a/src/RagePhotoA.h +++ b/src/RagePhotoA.h @@ -142,7 +142,7 @@ public: return ragephoto_loadfile(instance, filename); } /** Returns the last error occurred. */ - uint8_t error() const { + int32_t error() const { return ragephoto_error(instance); } /** Returns the Photo Format (GTA V or RDR 2). */ @@ -171,19 +171,19 @@ public: const char* jpegData() const { return ragephoto_getphotojpeg(instance); } - /**< Returns the Photo JPEG sign. */ + /** Returns the Photo JPEG sign. */ static uint64_t jpegSign(uint32_t photoFormat, RagePhotoData *rp_data) { return ragephotodata_getphotosignf(rp_data, photoFormat); } - /**< Returns the Photo JPEG sign. */ + /** Returns the Photo JPEG sign. */ static uint64_t jpegSign(RagePhotoData *rp_data) { return ragephotodata_getphotosign(rp_data); } - /**< Returns the Photo JPEG sign. */ + /** Returns the Photo JPEG sign. */ uint64_t jpegSign(uint32_t photoFormat) const { return ragephoto_getphotosignf(instance, photoFormat); } - /**< Returns the Photo JPEG sign. */ + /** Returns the Photo JPEG sign. */ uint64_t jpegSign() const { return ragephoto_getphotosign(instance); } diff --git a/src/RagePhotoC.h b/src/RagePhotoC.h index e88a361..f6b0efc 100644 --- a/src/RagePhotoC.h +++ b/src/RagePhotoC.h @@ -31,7 +31,10 @@ #ifdef __cplusplus extern "C" { #endif // __cplusplus -/** \file RagePhotoC.h */ + +/** C API for RagePhoto. +* \file RagePhotoC.h +*/ /** RagePhoto C++ class typedef for C API. */ typedef void* ragephoto_t;