LADI
/
gmic-qt
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update NEW_HOST_HOWTO.md

This commit is contained in:
Sebastien Fourey 2021-05-31 16:36:48 +02:00
parent d8ae746b80
commit 4c3ba3148a
1 changed files with 5 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
NEW_HOST_HOWTO.md
View File

@ -7,7 +7,7 @@ This document describes the architecture of the plugin (especially its link with
The plugin is intended to be a standalone program which communicates with the host application (typically digital painting or photo retouching software) to exchange image data and commands. This architecture, as opposed to a software component fully integrated in the host application process, has been designed like this for several reasons, among which :
* The plugin cannot mess up with the host application process which means in the worst case, make it crash. This would be a responsibility we don't want to endorse. If unfortunately the plugin crashes, the host application does not, and no user data are lost. As long as the host application handles properly its communication with the plugin, nothing bad should ever happen because of a plugin misbehavior.
* Being based on Qt, the plugin GUI inherits the desktop environment theme but also handles its own custom "dark theme" using stylesheets in an application-wide way. Consequently, a Qt-based host application could inherit from these modifications with unexpected results (for instance, messing up the whole theme of the host GUI).
* Being based on Qt, the plugin GUI inherits the desktop environment theme but also handles its own custom "dark theme" using style sheets in an application-wide way. Consequently, a Qt-based host application could inherit from these modifications with unexpected results (for instance, messing up the whole theme of the host GUI).
* This plugin architecture has allowed us to define our own and quite simple API made of a few functions (exactly 6) that need to be implemented for the plugin to be able to communicate with the host application. Namely, this API is the interface (in the software engineering sense) of the communication layer between the host and the plugin, from the viewpoint of the latter. Thus, any suitable implementation of this interface should be enough to make the plugin work with a given host. Note that only 4% of the whole "G'MIC-Qt for Gimp" source code is host-dependent. The next section gives more details about the work that needs to be done to have a functional plugin for a new host.
* With a plugin being a self-contained application whose host-related code is clearly identified, we can more easily build the plugin and quickly distribute new versions, thus following the rapid development cycle of G'MIC.
@ -17,14 +17,14 @@ Consequently, in order to adapt the plug-in to a new host application cleanly, a
* Provide the host application with a communication system targeted to an external application, if it does not exist yet, so that it supports passing commands and possibly large image data (preferably through memory for improved performances).
* Write a program:
* Which is linked to an implementation of all functions declared and documented in the API header [`Host/GmicQtHost.h`](https://github.com/c-koi/gmic-qt/blob/master/src/Host/GmicQtHost.h) (implementation usually written, at least in part, in a file named `host_HOSTNAME.cpp`). This is the only place where all the communication between the plugin and the host should occur. The plugin relies only on this interface to be implemented.
* Which is linked to the host-agnostic code of the plugin found in this repository. (See [GmicQt.h](src/GmicQt.h) for more details about the services offered by this part of the plug-in's code.)
* Which is linked to an implementation of all functions declared and documented in the API header [`Host/GmicQtHost.h`](src/Host/GmicQtHost.h) (implementation usually written, at least in part, in a file named `host_HOSTNAME.cpp`). This is the only place where all the communication between the plugin and the host should occur. The plugin relies only on this interface to be implemented.
* Which is linked to the host-agnostic code of the plugin found in this repository. (See [`GmicQt.h`](src/GmicQt.h) for more details about the services offered by this part of the plug-in's code.)
![Architecture](architecture.svg)
* Which calls the `GmicQt::run()` function provided by the G'MIC-Qt code, once initialisations are done and the communication with the host is established.
* It should be noticed that tweaking the API internals to adapt the plugin to a new host is definitely not good practice. It may break the compatibility with the plugin's future versions.
* Adapt the [qmake](https://github.com/c-koi/gmic-qt/blob/master/gmic_qt.pro) or [CMake](https://github.com/c-koi/gmic-qt/blob/master/CMakeLists.txt) project files and follow the [build instructions](https://github.com/c-koi/gmic-qt/blob/master/README.md#build-instructions) from the README.
* Adapt the [qmake](gmic_qt.pro) or [CMake](CMakeLists.txt) project files and follow the [build instructions](README.md#build-instructions) from the README.
In all these steps, valuable hints may be obtained from the [implementation for the GIMP host](https://github.com/c-koi/gmic-qt/tree/master/src/Host/Gimp), found in the [src/Host](https://github.com/c-koi/gmic-qt/tree/master/src/Host) folder, which is where all of a given host related code should go (for the plugin side).
In all these steps, valuable hints may be obtained from the [implementation for the GIMP host](src/Host/Gimp), found in the [src/Host](src/Host) folder, which is where all of a given host related code should go (for the plugin side).
If you succeed in creating such a file for a new host application, you are welcome to open a [pull request.](https://github.com/c-koi/gmic-qt/pulls)