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
This commit is contained in:
Syping 2023-04-02 21:33:48 +02:00
parent 302be665e2
commit 933918454f
9 changed files with 260 additions and 19 deletions

View file

@ -16,6 +16,8 @@ sudo cmake --install libragephoto-build
``` ```
##### Optional CMake flags ##### Optional CMake flags
`-DCMAKE_CXX_STANDARD=17`
`-DRAGEPHOTO_BENCHMARK=ON`
`-DRAGEPHOTO_C_API=OFF` `-DRAGEPHOTO_C_API=OFF`
`-DRAGEPHOTO_DOC=ON` `-DRAGEPHOTO_DOC=ON`
`-DRAGEPHOTO_EXAMPLE_GTKVIEWER=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/RagePhotoC_8h.html)
[RagePhoto C++ API](https://libragephoto.syping.de/doc/classRagePhoto.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 #### How to Use ragephoto-extract
```bash ```bash

View file

@ -1,12 +1,16 @@
PROJECT_NAME = "libragephoto" PROJECT_NAME = "libragephoto"
PROJECT_NUMBER = "Version: @ragephoto_VERSION@" PROJECT_NUMBER = "Version: @ragephoto_VERSION@"
INPUT = "@CMAKE_CURRENT_SOURCE_DIR@/index.doc" \ INPUT = "@CMAKE_CURRENT_SOURCE_DIR@/index.doc" \
"@CMAKE_CURRENT_SOURCE_DIR@/build.doc" \
"@CMAKE_CURRENT_SOURCE_DIR@/usage.doc" \
"src" "src"
OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@" OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@"
EXTRACT_PRIVATE = NO EXTRACT_PRIVATE = NO
ENABLE_PREPROCESSING = YES ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = 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="

29
doc/build.doc Normal file
View file

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

View file

@ -7,12 +7,20 @@
- Export RAGE Photos to jpeg with ragephoto-extract - Export RAGE Photos to jpeg with ragephoto-extract
- High Efficient and Simple C/C++ API - 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
*/ */

189
doc/usage.doc Normal file
View file

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

View file

@ -39,7 +39,7 @@ bool readPhotoFile(const std::string &filename, Gtk::Window *win, Gtk::Image *im
RagePhoto ragePhoto; RagePhoto ragePhoto;
const bool loaded = ragePhoto.load(data); const bool loaded = ragePhoto.load(data);
if (!loaded) { if (!loaded) {
const uint8_t error = ragePhoto.error(); const int32_t error = ragePhoto.error();
if (error <= RagePhoto::PhotoReadError) { if (error <= RagePhoto::PhotoReadError) {
Gtk::MessageDialog msg(*win, "Failed to read photo: " + filename, false, Gtk::MESSAGE_WARNING, Gtk::BUTTONS_OK, true); Gtk::MessageDialog msg(*win, "Failed to read photo: " + filename, false, Gtk::MESSAGE_WARNING, Gtk::BUTTONS_OK, true);
msg.set_title("Open Photo"); 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(); 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); 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)); image->set(Glib::wrap(pixbuf));
win->set_title("RagePhoto GTK Photo Viewer - " + std::string(ragePhoto.title())); win->set_title("RagePhoto GTK Photo Viewer - " + std::string(ragePhoto.title()));
return true; return true;

View file

@ -38,7 +38,7 @@ bool readPhotoFile(const QString &filename, QMainWindow *mainWindow, QLabel *pho
RagePhoto ragePhoto; RagePhoto ragePhoto;
const bool loaded = ragePhoto.load(fileData.data(), static_cast<size_t>(fileData.size())); const bool loaded = ragePhoto.load(fileData.data(), static_cast<size_t>(fileData.size()));
if (!loaded) { if (!loaded) {
const uint8_t error = ragePhoto.error(); const int32_t error = ragePhoto.error();
if (error <= RagePhoto::PhotoReadError) { if (error <= RagePhoto::PhotoReadError) {
QMessageBox::warning(mainWindow, "Open Photo", "Failed to read photo: " + filename); QMessageBox::warning(mainWindow, "Open Photo", "Failed to read photo: " + filename);
return false; return false;

View file

@ -142,7 +142,7 @@ public:
return ragephoto_loadfile(instance, filename); return ragephoto_loadfile(instance, filename);
} }
/** Returns the last error occurred. */ /** Returns the last error occurred. */
uint8_t error() const { int32_t error() const {
return ragephoto_error(instance); return ragephoto_error(instance);
} }
/** Returns the Photo Format (GTA V or RDR 2). */ /** Returns the Photo Format (GTA V or RDR 2). */
@ -171,19 +171,19 @@ public:
const char* jpegData() const { const char* jpegData() const {
return ragephoto_getphotojpeg(instance); return ragephoto_getphotojpeg(instance);
} }
/**< Returns the Photo JPEG sign. */ /** Returns the Photo JPEG sign. */
static uint64_t jpegSign(uint32_t photoFormat, RagePhotoData *rp_data) { static uint64_t jpegSign(uint32_t photoFormat, RagePhotoData *rp_data) {
return ragephotodata_getphotosignf(rp_data, photoFormat); return ragephotodata_getphotosignf(rp_data, photoFormat);
} }
/**< Returns the Photo JPEG sign. */ /** Returns the Photo JPEG sign. */
static uint64_t jpegSign(RagePhotoData *rp_data) { static uint64_t jpegSign(RagePhotoData *rp_data) {
return ragephotodata_getphotosign(rp_data); return ragephotodata_getphotosign(rp_data);
} }
/**< Returns the Photo JPEG sign. */ /** Returns the Photo JPEG sign. */
uint64_t jpegSign(uint32_t photoFormat) const { uint64_t jpegSign(uint32_t photoFormat) const {
return ragephoto_getphotosignf(instance, photoFormat); return ragephoto_getphotosignf(instance, photoFormat);
} }
/**< Returns the Photo JPEG sign. */ /** Returns the Photo JPEG sign. */
uint64_t jpegSign() const { uint64_t jpegSign() const {
return ragephoto_getphotosign(instance); return ragephoto_getphotosign(instance);
} }

View file

@ -31,7 +31,10 @@
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif // __cplusplus #endif // __cplusplus
/** \file RagePhotoC.h */
/** C API for RagePhoto.
* \file RagePhotoC.h
*/
/** RagePhoto C++ class typedef for C API. */ /** RagePhoto C++ class typedef for C API. */
typedef void* ragephoto_t; typedef void* ragephoto_t;