hgl 0.5.42~jessie
A compiler/interpreter suite for developing images (plugin development)
Image Output Plugins in detail

Image output plugins are far the most easy to implement plugins.

Simply one of your classes must inherit from HGL::ImageOutput::IPreRenderOutput and implement the HGL::ImageOutput::IPreRenderOutput::writeImage method.

Further it must register to HGL by using #REGISTER_IOPLUGIN in your definition file of the derived class.

The rest is subject to your implemenentation of the plugin. You can throw an HGL::ImageOutput::ImageOutputException if there is an unrecoverable error in your plugin. HGL will display it as message and exits then.

You must support output to the standard output if no filename (i.e. an empty string) is given, otherwise write your image to that file.

The data of the image can get accessed by the provided HGL::ImageOutput::ICanvas interface.

As you can see it is quite straightforward to develop image output plugins for HGL.

Below is an code example how to write an plugin.

The exampleoutput.h:

/***
* Copyright (c) 2013, Heiko Schäfer <heiko@hgl.rangun.de>
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted
* provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this list of conditions and
* the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions
* and the following disclaimer in the documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY Heiko Schäfer <heiko@hgl.rangun.de> "AS IS" AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
* FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Heiko Schäfer <heiko@hgl.rangun.de>
* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
***/
#ifndef MYIOLUGIN_EXAMPLEOUTPUT_H
#define MYIOLUGIN_EXAMPLEOUTPUT_H
#include "iprerenderoutput.h"
namespace MyIOPlugin {
class ExampleOutput : public HGL::ImageOutput::IPreRenderOutput {
public:
ExampleOutput();
virtual ~ExampleOutput();
virtual void writeImage(const HGL::ImageOutput::ICanvas &canvas, const std::string &filename) const throw(HGL::ImageOutput::ImageOutputException);
};
}
#endif MYIOLUGIN_EXAMPLEOUTPUT_H

The exampleoutput.cpp:

/***
* Copyright (c) 2013, Heiko Schäfer <heiko@hgl.rangun.de>
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted
* provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this list of conditions and
* the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions
* and the following disclaimer in the documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY Heiko Schäfer <heiko@hgl.rangun.de> "AS IS" AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
* FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Heiko Schäfer <heiko@hgl.rangun.de>
* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
***/
#include <cstdio>
#include <exm.h>
#include "exampleoutput.h"
#include "icanvas.h"
#include "writer.h"
using namespace MyIOPlugin;
REGISTER_IOPLUGIN(ExampleOutput,
"EXM",
L"EXM Image Output",
L"Your Name",
L"(c) 2013 by Your Name <me@mycompany.com>",
L"writes EXM Example images")
ExampleOutput::ExampleOutput() : HGL::ImageOutput::IPreRenderOutput() {}
ExampleOutput::~ExampleOutput() {}
void ExampleOutput::writeImage(const HGL::ImageOutput::ICanvas &canvas, const std::string &filename) const throw(HGL::ImageOutput::ImageOutputException) {
HGL::ImageOutput::Writer out(filename);
for(uint16_t row = 0; row < canvas.getHeight(); ++row) {
exm_write_row(out.getFile(), canvas.getRow(row));
}
out.endWrite();
}

Finally you must produce the actual plugin. On Linux it can be done the following way:

  1. g++ -fPIC -DPIC -c example.cpp
  2. g++ -shared -module -o libhglioexm.so -Wl,-soname,libhglioexm.so example.o /usr/lib/i386-linux-gnu/hgl/libhglimageoutput.so
  3. Copying the plugin into the plugin directory:
    cp libhglioexm.so /usr/lib/i386-linux-gnu/hgl/plugins
    NOTE: adjust the paths according your system, the plugins have to start with libhglio*

For classes, methods, etc see ioplugins.