Image Decoder

Detailed Description

Class: kodi::addon::CInstanceImageDecoder

Image decoder add-on instance
This instance type is used to allow Kodi various additional image format types.

This usage can be requested under various conditions, by a Mimetype protocol defined in addon.xml or supported file extensions.

Include the header #include <kodi/addon-instance/ImageDecoder.h> to use this class.

---

Here is an example of what the addon.xml.in would look like for an image decoder addon:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="imagedecoder.myspecialnamefor"
  version="1.0.0"
  name="My image decoder addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="kodi.imagedecoder"
    library_@PLATFORM@="@LIBRARY_FILENAME@">
    <support>
      <mimetype name="image/mymimea">
        <extension>.imga</extension>
        <description>30100</description>
        <icon>resources/file_format_icon_a.png</icon>
      </mimetype>
      <mimetype name="image/mymimeb">
        <extension>.imgb</extension>
        <description>30101</description>
        <icon>resources/file_format_icon_b.png</icon>
      </mimetype>
    </support>
  </extension>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My image decoder addon summary</summary>
    <description lang="en_GB">My image decoder description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Standard values that can be declared for processing in addon.xml.

These values are used by Kodi to identify associated images and file extensions and then to select the associated addon.

Labels	Type	Description
point	string	The identification of the addon instance to image decoder is mandatory kodi.imagedecoder. In addition, the instance declared in the first <support> is also the main type of addon.
library_@PLATFORM@	string	The runtime library used for the addon. This is usually declared by cmake and correctly displayed in the translated addon.xml.
<support>...</support>	XML group	Contains the formats supported by the addon.
<mimetype name="image/mymimea">...</mimetype>	string / group	The from addon operated image mimetypes. Optional can be with <description> and <icon> additional info added where used for list views in Kodi.
<mimetype ...><extension>...</extension></mimetype>	string	The file extensions / styles supported by this addon and relates to given mimetype before. Note Required to use about info support by CInstanceImageDecoder::SupportsFile and CInstanceImageDecoder::ReadTag!

Remarks

For more detailed description of the addon.xml, see also https://kodi.wiki/view/Addon.xml.

---

Example:

#include <kodi/addon-instance/ImageDecoder.h>
 
class ATTR_DLL_LOCAL CMyImageDecoder : public kodi::addon::CInstanceImageDecoder
{
public:
  CMyImageDecoder(const kodi::addon::IInstanceInfo& instance);
 
  bool LoadImageFromMemory(const std::string& mimetype,
                           const uint8_t* buffer,
                           size_t bufSize,
                           unsigned int& width,
                           unsigned int& height) override;
 
  bool Decode(uint8_t* pixels,
              size_t pixelBufferSize,
              unsigned int width,
              unsigned int height,
              unsigned int pitch,
              ADDON_IMG_FMT format) override;
 
  ...
};
 
CMyImageDecoder::CMyImageDecoder(const kodi::addon::IInstanceInfo& instance)
  : CInstanceImageDecoder(instance)
{
  ...
}
 
bool CMyImageDecoder::LoadImageFromMemory(const std::string& mimetype,
                                          const uint8_t* buffer,
                                          size_t bufSize,
                                          unsigned int& width,
                                          unsigned int& height)
{
  ...
  return true;
}
 
bool CMyImageDecoder::Decode(uint8_t* pixels,
                             size_t pixelBufferSize,
                             unsigned int width,
                             unsigned int height,
                             unsigned int pitch,
                             ADDON_IMG_FMT format)
{
  ...
  return true;
}
 
//----------------------------------------------------------------------
 
class ATTR_DLL_LOCAL CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(const kodi::addon::IInstanceInfo& instance,
                              KODI_ADDON_INSTANCE_HDL& hdl) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  if (instance.IsType(ADDON_INSTANCE_IMAGEDECODER))
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my image decoder instance");
    hdl = new CMyImageDecoder(instance);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyImageDecoder is called from Kodi's header. Manually deleting the add-on instance is not required.

Topics
	Definitions, structures and enumerators
	Image decoder add-on general variables

Function Documentation

CInstanceImageDecoder()

CInstanceImageDecoder ( const IInstanceInfo & instance )

inlineexplicit

Class constructor.

Parameters

[in]

instance

The from Kodi given instance given be add-on CreateInstance call with instance id ADDON_INSTANCE_IMAGEDECODER.

SupportsFile()

virtual bool SupportsFile ( const std::string & filename )

inlinevirtual

Checks addon support given file path.

Parameters

[in]

filename

The file to read

Returns

true if successfully done and supported, otherwise false

Note

Optional to add, as default becomes true used.

ReadTag()

virtual bool ReadTag ( const std::string & file, kodi::addon::ImageDecoderInfoTag & tag )

inlinevirtual

Read tag of a file.

Parameters

[in]	file	File to read tag for
[out]	tag	Information tag about

Returns

True on success, false on failure

---

The following table contains values that can be set with class ImageDecoderInfoTag :

Name	Type	Set call	Get call
Width	int	SetWidth	GetWidth
Height	int	SetHeight	GetHeight
Distance	float	SetDistance	GetDistance
Color	enum ADDON_IMG_COLOR	SetColor	GetColor
Orientation	enum ADDON_IMG_ORIENTATION	SetOrientation	GetOrientation
Metering mode	enum ADDON_IMG_METERING_MODE	SetMeteringMode	GetMeteringMode
Exposure time	float	SetExposureTime	GetExposureTime
Exposure bias	float	SetExposureBias	GetExposureBias
Exposure program	enum ADDON_IMG_EXPOSURE_PROGRAM	SetExposureProgram	GetExposureProgram
Exposure mode	enum ADDON_IMG_EXPOSURE_MODE	SetExposureMode	GetExposureMode
Time created	time_t	SetTimeCreated	GetTimeCreated
Aperture F number	float	SetApertureFNumber	GetApertureFNumber
Flash used	ADDON_IMG_FLASH_TYPE	SetFlashUsed	GetFlashUsed
Light source	ADDON_IMG_LIGHT_SOURCE	SetLightSource	GetLightSource
Focal length	int	SetFocalLength	GetFocalLength
Focal length in 35 mm format	int	SetFocalLengthIn35mmFormat	GetFocalLengthIn35mmFormat
Digital zoom ratio	float	SetDigitalZoomRatio	GetDigitalZoomRatio
ISO sensitivity	float	SetISOSpeed	GetISOSpeed
Camera manufacturer	std::string	SetCameraManufacturer	GetCameraManufacturer
GPS info	bool, char, float[3], char, float[3], int, float	SetGPSInfo	GetGPSInfo
Camera model	std::string	SetCameraModel	GetCameraModel
Author	std::string	SetAuthor	GetAuthor
Description	std::string	SetDescription	GetDescription
Copyright	std::string	SetCopyright	GetCopyright

LoadImageFromMemory()

virtual bool LoadImageFromMemory ( const std::string & mimetype, const uint8_t * buffer, size_t bufSize, unsigned int & width, unsigned int & height )

pure virtual

Load an image from a memory buffer.

Parameters

[in]	mimetype	The mimetype wanted from Kodi
[in]	buffer	The data to read from memory
[in]	bufSize	The buffer size
[in,out]	width	Upper bound for the width on entry, the width actually produced on return
[in,out]	height	Upper bound for the height on entry, the height actually produced on return

Returns

true if successful done, false on error

Note

width and height are a maximum, not a request. Kodi passes the renderer's maximum texture size here when the caller has no preferred size, so returning them unchanged as the image's natural size can ask for an allocation of several thousand pixels square. Report the size the image actually has.

Decode()

virtual bool Decode ( uint8_t * pixels, size_t pixelBufferSize, unsigned int width, unsigned int height, unsigned int pitch, ADDON_IMG_FMT format )

pure virtual

Decode previously loaded image.

Parameters

[out]	pixels	Output buffer
[in]	pixelBufferSize	Size of the output buffer in bytes
[in]	width	Width of output image
[in]	height	Height of output image
[in]	pitch	Byte offset between the start of one output row and the next
[in]	format	Format of output image

Returns

true if successful done, false on error

Note

The buffer holds height rows of pitch bytes, pixelBufferSize in total. pitch already accounts for format, so an add-on that writes a fixed number of bytes per pixel regardless of format will overrun the buffer for any format narrower than the one it assumes. Return false for a format the add-on does not implement rather than falling through to a default.