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

@@ -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

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" \
+PREDEFINED             = "__cplusplus=201703L" \
-                         "__cplusplus" \
+                         "RAGEPHOTO_CXX_STD=17" \
-                         "@LIBRAGEPHOTO_API@"
+                         "@LIBRAGEPHOTO_API@" \
+                         "LIBRAGEPHOTO_C_BINDING=" \
+                         "LIBRAGEPHOTO_CXX_BINDING="

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.
+
+<h4 id="build">Build libragephoto</h4>
+\code{.sh}
+cmake -B libragephoto-build libragephoto
+cmake --build libragephoto-build
+\endcode
+
+<h4 id="install">Install libragephoto</h4>
+\code{.sh}
+sudo cmake --install libragephoto-build
+\endcode
+
+To customise your libragephoto build, the following <a href="#flags">Optional CMake flags</a> can be used
+
+<h4 id="flags">Optional CMake flags</h4>
+\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
+*/

doc/index.doc

@@ -7,12 +7,20 @@
 - Export RAGE Photos to jpeg with ragephoto-extract
 - High Efficient and Simple C/C++ API
 
-<b>Main Class:</b>
+<b>Getting started</b>  
-- RagePhoto
+\subpage Build "Build libragephoto"  
+\subpage Usage "Using libragephoto"
 
-<b>Project Pages:</b>
+<b>Reference</b>  
-- https://git.syping.de/Syping/libragephoto
+RagePhoto (C++ API)  
-- https://gitlab.com/Syping/libragephoto
+RagePhotoA (C++ API based on C API)  
-- https://github.com/Syping/libragephoto
+RagePhotoC.h (C API)  
+RagePhotoData (Data Object Struct)  
+RagePhotoFormatParser (Custom Format Parser Struct)
+
+<b>Project Pages</b>  
+https://git.syping.de/Syping/libragephoto  
+https://gitlab.com/Syping/libragephoto  
+https://github.com/Syping/libragephoto
 
 */

doc/usage.doc

@@ -0,0 +1,189 @@
+/*! \page Usage Using libragephoto
+
+<h3 id="api_cxx">C++ API</h3>
+
+<h4 id="cxx_include_usage">Including and using RagePhoto</h4>
+
+Include RagePhoto.h or RagePhotoA.h
+
+\code{.cpp}
+#include <RagePhoto.h>
+\endcode
+
+Create a RagePhoto object
+
+\code{.cpp}
+RagePhoto ragePhoto;
+\endcode
+
+<h4 id="cxx_loading">Loading a Photo</h4>
+
+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<char>{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
+
+<h4 id="cxx_using">Using a Photo</h4>
+
+\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<const guchar*>(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
+
+<h4 id="cxx_error">Detect Photo errors</h4>
+
+\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
+
+<h3 id="cmake">Including libragephoto in a CMake project</h3>
+
+<h4 id="cmake_pkgconfig">Using PkgConfig</h4>
+
+\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
+
+<h4 id="cmake_add_subdirectory">Using add_subdirectory</h4>
+
+\code{.cmake}
+add_subdirectory(src/libragephoto)
+target_link_libraries(your_project PRIVATE ragephoto)
+\endcode
+*/

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<const guchar*>(ragePhoto.jpegData()), ragePhoto.jpegSize(), NULL);
+        gdk_pixbuf_loader_write(pixbuf_loader, reinterpret_cast<const guchar*>(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;

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<size_t>(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;

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);
     }

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;