code_app/modules/base/HGImage.h

#ifndef __HGIMAGE_H__
#define __HGIMAGE_H__

#include "HGDef.h"
#include "HGBaseErr.h"
#if defined(HG_CMP_MSC)
#include <windows.h>
#endif

HG_DECLARE_HANDLE(HGImage);

/* 1位黑白图 */
#define HGBASE_IMGTYPE_BINARY	1L
/* 8位灰度图 */
#define HGBASE_IMGTYPE_GRAY		2L
/* 24位真彩色，B8G8R8格式 */
#define HGBASE_IMGTYPE_BGR		3L
/* 24位真彩色，R8G8B8格式 */
#define HGBASE_IMGTYPE_RGB		4L
/* 32位真彩色，带Alpha通道，B8G8R8A8格式 */
#define HGBASE_IMGTYPE_BGRA		5L
/* 32位真彩色，带Alpha通道，R8G8B8A8格式 */
#define HGBASE_IMGTYPE_RGBA		6L

/* 顶左结构 */
#define HGBASE_IMGORIGIN_TOP	1L
/* 底左结构 */
#define HGBASE_IMGORIGIN_BOTTOM	2L

#pragma pack(push)
#pragma pack(4)

/* 图像信息 */
typedef struct
{
	HGUInt width;	/* 宽(像素)，列数 */
	HGUInt height;	/* 高(像素)，行数 */
	HGUInt type;	/* 类型，参见HGBASE_IMGTYPE_* */
	HGUInt widthStep; /* 每行的字节数 */
	HGUInt origin; /* 数据排列方式，参见HGBASE_IMGORIGIN_* */
}HGImageInfo;

/* 图像感兴趣区域 */
typedef struct
{
	HGUInt left;
	HGUInt top;
	HGUInt right;
	HGUInt bottom;
}HGImageRoi;

#pragma pack(pop)

/* 创建空白的新图像
* 参数:
* 1) width: in, 新图像宽度
* 2) height: in, 新图像高度
* 3) type: in, 新图像类型
* 4) origin: in, 新图像的数据排列方式
* 5) image: out，新图像句柄
* 说明: 
* 1）在windows系统上，当type为HGBASE_IMGTYPE_BINARY、HGBASE_IMGTYPE_GRAY、HGBASE_IMGTYPE_BGR或HGBASE_IMGTYPE_BGRA时，新图像内部实际创建DIB位图(有HBITMAP),
*	 否则内部分配普通内存(无HBITMAP); 在linux系统上，新图像内部分配普通内存(无HBITMAP)
* 2) 新图像的width=width; 新图像的height=height; 新图像的type=type; 新图像的widthStep为4字节对齐; 新图像的origin=origin
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=0, ydpi=0
*/
HGEXPORT HGResult HGAPI HGBase_CreateImage(HGUInt width, HGUInt height, HGUInt type, HGUInt origin, HGImage* image);

/* 从源数据创建新图像(不分配内存, 也不拷贝数据)
* 参数:
* 1) data: in, 源数据的地址
* 2) info: in, 源数据的图像信息
* 3) image: out，新图像句柄
* 说明:
* 1) 新图像内部不会分配普通像素内存，也不会创建DIB位图(windows系统上, 无HBITMAP)，而是直接使用源数据, 在该图像销毁之前需要保证源数据一直有效
* 2) 新图像的width=info->width; 新图像的height=info->height; 新图像的type=info->type; 新图像的widthStep=info->widthStep;
*	 新图像的origin=info->origin
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=0, ydpi=0
*/
HGEXPORT HGResult HGAPI HGBase_CreateImageWithData(HGByte* data, const HGImageInfo* info, HGImage* image);

/* 从源数据创建新图像
* 参数:
* 1) data: in, 源数据的地址
* 2) info: in, 源数据的图像信息
* 3) roi: in, 源数据的感兴趣区域, NULL表示整个图像区域
* 4) type: in, 新图像的类型, 0表示和源数据一样
* 5) origin: in, 新图像的数据排列方式, 0表示和源数据一样
* 6) image: out，新图像句柄
* 说明:
* 1）在windows系统上，当type为HGBASE_IMGTYPE_BINARY、HGBASE_IMGTYPE_GRAY、HGBASE_IMGTYPE_BGR或HGBASE_IMGTYPE_BGRA时，新图像内部实际创建DIB位图(有HBITMAP),
*	 否则内部分配普通内存(无HBITMAP); 在linux系统上，新图像内部分配普通内存(无HBITMAP)
* 2) 新图像的width=roi->right-roi->left; 新图像的height=roi->bottom-roi->top; 新图像的type=type; 新图像的widthStep为4字节对齐; 
*	 新图像的origin=origin, 如果origin和info->origin不一致，拷贝时像素会进行上下翻转
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=0, ydpi=0
*/
HGEXPORT HGResult HGAPI HGBase_CreateImageFromData(HGByte* data, const HGImageInfo *info, const HGImageRoi *roi, 
	HGUInt type, HGUInt origin, HGImage* image);

#if defined(HG_CMP_MSC)

/* 从DIB位图创建新图像
* 参数:
* 1) hBmp: in, DIB位图句柄
* 2) roi: DIB位图的感兴趣区域, NULL表示整个图像区域
* 3) type: in, 新图像的类型, 0表示自动生成和DIB位图最接近的type
* 4) origin: in, 新图像的数据排列方式, 必须指定
* 5) image: out，新图像句柄
* 说明:
* 1）当type为HGBASE_IMGTYPE_BINARY、HGBASE_IMGTYPE_GRAY、HGBASE_IMGTYPE_BGR或HGBASE_IMGTYPE_BGRA时，新图像内部实际创建DIB位图(有HBITMAP),
*	 否则内部分配普通内存(无HBITMAP)
* 2) 新图像的width=roi->right-roi->left; 新图像的height=roi->bottom-roi->top; 新图像的type=type; 新图像的widthStep为4字节对齐;
*	 新图像的origin=origin
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=hBmp的xDPI, ydpi=hBmp的yDPI
*/
HGEXPORT HGResult HGAPI HGBase_CreateImageFromHBITMAP(HBITMAP hBmp, const HGImageRoi* roi, 
	HGUInt type, HGUInt origin, HGImage* image);

/* 从DIB内存创建新图像
* 参数:
* 1) hMem: in, DIB内存句柄
* 2) roi: DIB内存的感兴趣区域, NULL表示整个图像区域
* 3) type: in, 新图像的类型, 0表示自动生成和DIB内存最接近的type
* 4) origin: in, 新图像的数据排列方式, 必须指定
* 5) image: out，新图像句柄
* 说明:
* 1）当type为HGBASE_IMGTYPE_BINARY、HGBASE_IMGTYPE_GRAY、HGBASE_IMGTYPE_BGR或HGBASE_IMGTYPE_BGRA时，新图像内部实际创建DIB位图(有HBITMAP),
*	 否则内部分配普通内存(无HBITMAP)
* 2) 新图像的width=roi->right-roi->left; 新图像的height=roi->bottom-roi->top; 新图像的type=type; 新图像的widthStep为4字节对齐;
*	 新图像的origin=origin
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=DIB的xDPI, ydpi=DIB的yDPI
*/
HGEXPORT HGResult HGAPI HGBase_CreateImageFromDIB(HGLOBAL hMem, const HGImageRoi* roi,
	HGUInt type, HGUInt origin, HGImage* image);

#endif /* HG_CMP_MSC */

/* 从源图像创建新图像
* 参数:
* 1) srcImage: in, 源图像
* 2) type: in, 新图像的类型, 0表示和源图像一样
* 3) origin: in, 新图像的数据排列方式, 0表示和源图像一样
* 4) image: out，新图像句柄
* 说明：
* 1）在windows系统上，当type为HGBASE_IMGTYPE_BINARY、HGBASE_IMGTYPE_GRAY、HGBASE_IMGTYPE_BGR或HGBASE_IMGTYPE_BGRA时，新图像内部实际创建DIB位图(有HBITMAP),
*	 否则内部分配普通内存(无HBITMAP); 在linux系统上，新图像内部分配普通内存(无HBITMAP)
* 2) 新图像的width=srcImage->roi.right-srcImage->roi.left; 新图像的height=srcImage->roi.bottom-srcImage->roi.top; 
*	 新图像的type=type; 新图像的widthStep为4字节对齐; 新图像的origin=origin, 如果origin和srcImage->origin不一致，拷贝时像素会进行上下翻转
* 3) 新图像的roi为{0, 0, width, height}
* 4) 新图像的xdpi=srcImage->xdpi, ydpi=srcImage->ydpi
*/
HGEXPORT HGResult HGAPI HGBase_CloneImage(HGImage srcImage, HGUInt type, HGUInt origin, HGImage* image);

/* 销毁图像
* 参数:
* 1) image: in, 图像句柄
* 说明:
* 1) 如果图像内部分配了像素内存, 销毁图像的同时会自动释放
* 2) 如果图像内部创建了DIB位图(windows上), 销毁图像的同时会自动调用DeleteObject进行销毁
* 3) 如果图像内存没有分配内存，也没有创建DIB位图，而是直接使用源数据，销毁图像后源数据才可以释放
*/
HGEXPORT HGResult HGAPI HGBase_DestroyImage(HGImage image);

/* 获取图像数据地址
* 参数:
* 1) image: in, 图像句柄
* 2) data: out, 数据地址
* 说明:
* 1) 如果图像内部分配了内存, 返回的是分配的内存地址
* 2) 如果图像内部创建了DIB位图，返回的是DIB位图像素数据的内存地址
* 3) 否则，返回的是源数据地址
*/
HGEXPORT HGResult HGAPI HGBase_GetImageData(HGImage image, HGByte** data);

/* 获取图像信息
* 参数:
* 1) image: in, 图像句柄
* 2) info: out, 图像信息
* 说明:
*/
HGEXPORT HGResult HGAPI HGBase_GetImageInfo(HGImage image, HGImageInfo* info);

/* 获取图像感兴趣区域
* 参数:
* 1) image: in, 图像句柄
* 2) roi: out, 图像感兴趣区域
* 说明:
* 1) 默认的感兴趣区域整张图, 即left=0,top=0,right=width,bottom=height
* 2) 图像算法模块可以仅处理感兴趣区域
*/
HGEXPORT HGResult HGAPI HGBase_GetImageROI(HGImage image, HGImageRoi* roi);

/* 设置图像感兴趣区域
* 参数:
* 1) image: in, 图像句柄
* 2) roi: in, 图像感兴趣区域
* 说明:
* 1) roi所指定的区域必须是整个图像幅面的子集
*/
HGEXPORT HGResult HGAPI HGBase_SetImageROI(HGImage image, const HGImageRoi* roi);

/* 重置图像感兴趣区域
* 参数:
* 1) image: in, 图像句柄
* 说明:
* 1) 默认的感兴趣区域整张图, 即left=0,top=0,right=width,bottom=height
*/
HGEXPORT HGResult HGAPI HGBase_ResetImageROI(HGImage image);

/* 获取图像DPI
* 参数:
* 1) image: in, 图像句柄
* 2) xDpi: out, xdpi
* 3) yDpi: out, ydpi
* 说明:
*/
HGEXPORT HGResult HGAPI HGBase_GetImageDpi(HGImage image, HGUInt *xDpi, HGUInt* yDpi);

/* 设置图像DPI
* 参数:
* 1) image: in, 图像句柄
* 2) xDpi: in, xdpi
* 3) yDpi: in, ydpi
* 说明:
*/
HGEXPORT HGResult HGAPI HGBase_SetImageDpi(HGImage image, HGUInt xDpi, HGUInt yDpi);

#if defined(HG_CMP_MSC)

/* 获取图像内部的DIB位图句柄
* 参数:
* 1) image: in, 图像句柄
* 2) hBmp: out, DIB位图句柄
* 说明:
* 1) 该函数只对windows平台有效
* 2) 返回的HBITMAP不能用DeleteObject销毁
*/
HGEXPORT HGResult HGAPI HGBase_GetHBITMAPOfImage(HGImage image, HBITMAP *hBmp);

/* 创建DIB位图
* 参数:
* 1) image: in, 图像句柄
* 2) hBmp: out, DIB位图句柄
* 说明:
* 1) 该函数只对windows平台有效
* 2) 返回的hBmp必须用DeleteObject销毁
* 3) 操作的只是图像的ROI区域
* 4) HGBASE_IMGTYPE_RGB会自动转为BGR排列, HGBASE_IMGTYPE_RGBA会自动转为BGRA排列
*/
HGEXPORT HGResult HGAPI HGBase_CreateHBITMAPFromImage(HGImage image, HBITMAP* hBmp);

/* 创建DIB内存
* 参数:
* 1) image: in, 图像句柄
* 2) hMem: out, DIB内存句柄
* 说明:
* 1) 该函数只对windows平台有效
* 2) 返回的hMem必须用GlobalFree销毁
* 3) 操作的只是图像的ROI区域
* 4) HGBASE_IMGTYPE_RGB会自动转为BGR排列, HGBASE_IMGTYPE_RGBA会自动转为BGRA排列
*/
HGEXPORT HGResult HGAPI HGBase_CreateDIBFromImage(HGImage image, HGLOBAL* hMem);

#endif /* HG_CMP_MSC */

/* 图像左右镜像
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage可以是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageMirror(HGImage image, HGImage destImage);

/* 图像上下镜像
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage可以是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageFlip(HGImage image, HGImage destImage);

/* 图像左转
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须宽高互反
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage不能是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageRotateLeft(HGImage image, HGImage destImage);

/* 图像右转
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须宽高互反
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage不能是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageRotateRight(HGImage image, HGImage destImage);

/* 图像左转后再左右镜像
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须宽高互反
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage不能是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageRotateLeftMirror(HGImage image, HGImage destImage);

/* 图像右转后再左右镜像
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须宽高互反
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage不能是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageRotateRightMirror(HGImage image, HGImage destImage);

/* 图像旋转180度
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage可以是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageRotate180(HGImage image, HGImage destImage);

/* 图像灰度化
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage可以是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ImageGrayscale(HGImage image, HGImage destImage);

/* 图像反色
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 源图像和目标图像的type必须一样
* 3) 自动处理origon不一致的情况
* 4) image和destImage可以是同一个句柄
*/
HGEXPORT HGResult HGAPI HGBase_ReverseImage(HGImage image, HGImage destImage);

/* 拷贝图像
* 参数:
* 1) image: in, 源图像句柄
* 2) destImage: in, 目标图像句柄
* 说明:
* 1) 操作的只是图像的ROI区域, 源图像和目标图像的ROI大小必须一样
* 2) 拷贝的时候会自动处理type不一致的情况
* 3) 拷贝的时候自动处理origin不一致的情况
* 4) image和destImage不能是同一个图像句柄
*/
HGEXPORT HGResult HGAPI HGBase_CopyImage(HGImage image, HGImage destImage);

#endif /* __HGIMAGE_H__ */