[mirror_edk2.git] / MdePkg / Include / Protocol / ImageDecoder.h

/** @file\r
  This protocol provides generic image decoder interfaces to various image formats.\r
\r
(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>\r
\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
#ifndef __EFI_IMAGE_DECODER_PROTOCOL_H__\r
#define __EFI_IMAGE_DECODER_PROTOCOL_H__\r
\r
#include <Protocol/HiiImage.h>\r
\r
\r
//\r
// In UEFI 2.6 spec,this guid value is duplicate with\r
// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID. Now update this guid value to\r
// avoid the duplicate guid issue. So its value is not consistent with\r
// UEFI spec definition now. We have proposed to update UEFI spec to\r
// use this new guid. After new spec released, we will remove this\r
// comments.\r
//\r
#define EFI_HII_IMAGE_DECODER_PROTOCOL_GUID \\r
  {0x9e66f251, 0x727c, 0x418c, { 0xbf, 0xd6, 0xc2, 0xb4, 0x25, 0x28, 0x18, 0xea }}\r
\r
\r
#define EFI_HII_IMAGE_DECODER_NAME_JPEG_GUID \\r
  {0xefefd093, 0xd9b, 0x46eb,  { 0xa8, 0x56, 0x48, 0x35, 0x7, 0x0, 0xc9, 0x8 }}\r
\r
#define EFI_HII_IMAGE_DECODER_NAME_PNG_GUID \\r
  {0xaf060190, 0x5e3a, 0x4025, { 0xaf, 0xbd, 0xe1, 0xf9, 0x5, 0xbf, 0xaa, 0x4c }}\r
\r
typedef struct _EFI_HII_IMAGE_DECODER_PROTOCOL EFI_HII_IMAGE_DECODER_PROTOCOL;\r
\r
typedef enum {\r
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGB     = 0x0,\r
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGBA    = 0x1,\r
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_CMYK    = 0x2,\r
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_UNKNOWN = 0xFF\r
} EFI_HII_IMAGE_DECODER_COLOR_TYPE;\r
\r
//\r
// EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER\r
//\r
// DecoderName        Name of the decoder\r
// ImageInfoSize      The size of entire image information structure in bytes\r
// ImageWidth         The image width\r
// ImageHeight        The image height\r
// ColorType          The color type, see EFI_HII_IMAGE_DECODER_COLOR_TYPE.\r
// ColorDepthInBits   The color depth in bits\r
//\r
typedef struct _EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER {\r
  EFI_GUID                            DecoderName;\r
  UINT16                              ImageInfoSize;\r
  UINT16                              ImageWidth;\r
  UINT16                              ImageHeight;\r
  EFI_HII_IMAGE_DECODER_COLOR_TYPE    ColorType;\r
  UINT8                               ColorDepthInBits;\r
} EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER;\r
\r
//\r
// EFI_HII_IMAGE_DECODER_JPEG_INFO\r
// Header         The common header\r
// ScanType       The scan type of JPEG image\r
// Reserved       Reserved\r
//\r
typedef struct _EFI_HII_IMAGE_DECODER_JPEG_INFO {\r
  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  Header;\r
\r
#define EFI_IMAGE_JPEG_SCANTYPE_PROGREESSIVE 0x01\r
#define EFI_IMAGE_JPEG_SCANTYPE_INTERLACED   0x02\r
  UINT16                                    ScanType;\r
  UINT64                                    Reserved;\r
} EFI_HII_IMAGE_DECODER_JPEG_INFO;\r
\r
//\r
// EFI_HII_IMAGE_DECODER_PNG_INFO\r
// Header         The common header\r
// Channels       Number of channels in the PNG image\r
// Reserved       Reserved\r
//\r
typedef struct _EFI_HII_IMAGE_DECODER_PNG_INFO {\r
  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  Header;\r
  UINT16                                    Channels;\r
  UINT64                                    Reserved;\r
} EFI_HII_IMAGE_DECODER_PNG_INFO;\r
\r
/**\r
  There could be more than one EFI_HII_IMAGE_DECODER_PROTOCOL instances installed\r
  in the system for different image formats. This function returns the decoder\r
  name which callers can use to find the proper image decoder for the image. It\r
  is possible to support multiple image formats in one EFI_HII_IMAGE_DECODER_PROTOCOL.\r
  The capability of the supported image formats is returned in DecoderName and\r
  NumberOfDecoderName.\r
\r
  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
  @param DecoderName             Pointer to a dimension to retrieve the decoder\r
                                 names in EFI_GUID format. The number of the\r
                                 decoder names is returned in NumberOfDecoderName.\r
  @param NumberofDecoderName     Pointer to retrieve the number of decoders which\r
                                 supported by this decoder driver.\r
\r
  @retval EFI_SUCCESS            Get decoder name success.\r
  @retval EFI_UNSUPPORTED        Get decoder name fail.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_IMAGE_DECODER_GET_DECODER_NAME)(\r
  IN      EFI_HII_IMAGE_DECODER_PROTOCOL   *This,\r
  IN OUT  EFI_GUID                         **DecoderName,\r
  IN OUT  UINT16                           *NumberofDecoderName\r
  );\r
\r
/**\r
  This function returns the image information of the given image raw data. This\r
  function first checks whether the image raw data is supported by this decoder\r
  or not. This function may go through the first few bytes in the image raw data\r
  for the specific data structure or the image signature. If the image is not supported\r
  by this image decoder, this function returns EFI_UNSUPPORTED to the caller.\r
  Otherwise, this function returns the proper image information to the caller.\r
  It is the caller?s responsibility to free the ImageInfo.\r
\r
  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
  @param Image                   Pointer to the image raw data.\r
  @param SizeOfImage             Size of the entire image raw data.\r
  @param ImageInfo               Pointer to recieve EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER.\r
\r
  @retval EFI_SUCCESS            Get image info success.\r
  @retval EFI_UNSUPPORTED        Unsupported format of image.\r
  @retval EFI_INVALID_PARAMETER  Incorrect parameter.\r
  @retval EFI_BAD_BUFFER_SIZE    Not enough memory.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO)(\r
  IN      EFI_HII_IMAGE_DECODER_PROTOCOL           *This,\r
  IN      VOID                                     *Image,\r
  IN      UINTN                                    SizeOfImage,\r
  IN OUT  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  **ImageInfo\r
  );\r
\r
/**\r
  This function decodes the image which the image type of this image is supported\r
  by this EFI_HII_IMAGE_DECODER_PROTOCOL. If **Bitmap is not NULL, the caller intends\r
  to put the image in the given image buffer. That allows the caller to put an\r
  image overlap on the original image. The transparency is handled by the image\r
  decoder because the transparency capability depends on the image format. Callers\r
  can set Transparent to FALSE to force disabling the transparency process on the\r
  image. Forcing Transparent to FALSE may also improve the performance of the image\r
  decoding because the image decoder can skip the transparency processing.  If **Bitmap\r
  is NULL, the image decoder allocates the memory buffer for the EFI_IMAGE_OUTPUT\r
  and decodes the image to the image buffer. It is the caller?s responsibility to\r
  free the memory for EFI_IMAGE_OUTPUT. Image decoder doesn?t have to handle the\r
  transparency in this case because there is no background image given by the caller.\r
  The background color in this case is all black (#00000000).\r
\r
  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
  @param Image                   Pointer to the image raw data.\r
  @param ImageRawDataSize        Size of the entire image raw data.\r
  @param Blt                     EFI_IMAGE_OUTPUT to receive the image or overlap\r
                                 the image on the original buffer.\r
  @param Transparent             BOOLEAN value indicates whether the image decoder\r
                                 has to handle the transparent image or not.\r
\r
\r
  @retval EFI_SUCCESS            Image decode success.\r
  @retval EFI_UNSUPPORTED        Unsupported format of image.\r
  @retval EFI_INVALID_PARAMETER  Incorrect parameter.\r
  @retval EFI_BAD_BUFFER_SIZE    Not enough memory.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_IMAGE_DECODER_DECODE)(\r
  IN      EFI_HII_IMAGE_DECODER_PROTOCOL   *This,\r
  IN      VOID                              *Image,\r
  IN      UINTN                             ImageRawDataSize,\r
  IN OUT  EFI_IMAGE_OUTPUT                  **BitMap OPTIONAL,\r
  IN      BOOLEAN                           Transparent\r
  );\r
\r
struct _EFI_HII_IMAGE_DECODER_PROTOCOL {\r
  EFI_HII_IMAGE_DECODER_GET_DECODER_NAME  GetImageDecoderName;\r
  EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO    GetImageInfo;\r
  EFI_HII_IMAGE_DECODER_DECODE            DecodeImage;\r
};\r
\r
extern EFI_GUID gEfiHiiImageDecoderProtocolGuid;\r
extern EFI_GUID gEfiHiiImageDecoderNameJpegGuid;\r
extern EFI_GUID gEfiHiiImageDecoderNamePngGuid;\r
\r
#endif\r
Commit	Line	Data
a48d0a3d CS	1	/** @file\r
	2	This protocol provides generic image decoder interfaces to various image formats.\r
	3	\r
	4	(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>\r
	5	\r
	6	This program and the accompanying materials are licensed and made available under\r
	7	the terms and conditions of the BSD License that accompanies this distribution.\r
	8	The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php.\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
	14	**/\r
	15	#ifndef __EFI_IMAGE_DECODER_PROTOCOL_H__\r
	16	#define __EFI_IMAGE_DECODER_PROTOCOL_H__\r
	17	\r
	18	#include <Protocol/HiiImage.h>\r
	19	\r
	20	\r
d35ec1e0 ED	21	//\r
	22	// In UEFI 2.6 spec,this guid value is duplicate with\r
	23	// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID. Now update this guid value to\r
	24	// avoid the duplicate guid issue. So its value is not consistent with\r
	25	// UEFI spec definition now. We have proposed to update UEFI spec to\r
	26	// use this new guid. After new spec released, we will remove this\r
	27	// comments.\r
	28	//\r
a48d0a3d	29	#define EFI_HII_IMAGE_DECODER_PROTOCOL_GUID \\r
d35ec1e0	30	{0x9e66f251, 0x727c, 0x418c, { 0xbf, 0xd6, 0xc2, 0xb4, 0x25, 0x28, 0x18, 0xea }}\r
a48d0a3d CS	31	\r
	32	\r
	33	#define EFI_HII_IMAGE_DECODER_NAME_JPEG_GUID \\r
	34	{0xefefd093, 0xd9b, 0x46eb, { 0xa8, 0x56, 0x48, 0x35, 0x7, 0x0, 0xc9, 0x8 }}\r
	35	\r
	36	#define EFI_HII_IMAGE_DECODER_NAME_PNG_GUID \\r
	37	{0xaf060190, 0x5e3a, 0x4025, { 0xaf, 0xbd, 0xe1, 0xf9, 0x5, 0xbf, 0xaa, 0x4c }}\r
	38	\r
	39	typedef struct _EFI_HII_IMAGE_DECODER_PROTOCOL EFI_HII_IMAGE_DECODER_PROTOCOL;\r
	40	\r
	41	typedef enum {\r
	42	EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGB = 0x0,\r
	43	EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGBA = 0x1,\r
	44	EFI_HII_IMAGE_DECODER_COLOR_TYPE_CMYK = 0x2,\r
	45	EFI_HII_IMAGE_DECODER_COLOR_TYPE_UNKNOWN = 0xFF\r
	46	} EFI_HII_IMAGE_DECODER_COLOR_TYPE;\r
	47	\r
	48	//\r
	49	// EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER\r
	50	//\r
	51	// DecoderName Name of the decoder\r
	52	// ImageInfoSize The size of entire image information structure in bytes\r
	53	// ImageWidth The image width\r
	54	// ImageHeight The image height\r
	55	// ColorType The color type, see EFI_HII_IMAGE_DECODER_COLOR_TYPE.\r
	56	// ColorDepthInBits The color depth in bits\r
	57	//\r
	58	typedef struct _EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER {\r
	59	EFI_GUID DecoderName;\r
	60	UINT16 ImageInfoSize;\r
	61	UINT16 ImageWidth;\r
	62	UINT16 ImageHeight;\r
	63	EFI_HII_IMAGE_DECODER_COLOR_TYPE ColorType;\r
	64	UINT8 ColorDepthInBits;\r
	65	} EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER;\r
	66	\r
	67	//\r
	68	// EFI_HII_IMAGE_DECODER_JPEG_INFO\r
	69	// Header The common header\r
	70	// ScanType The scan type of JPEG image\r
	71	// Reserved Reserved\r
	72	//\r
	73	typedef struct _EFI_HII_IMAGE_DECODER_JPEG_INFO {\r
	74	EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER Header;\r
	75	\r
	76	#define EFI_IMAGE_JPEG_SCANTYPE_PROGREESSIVE 0x01\r
	77	#define EFI_IMAGE_JPEG_SCANTYPE_INTERLACED 0x02\r
	78	UINT16 ScanType;\r
	79	UINT64 Reserved;\r
	80	} EFI_HII_IMAGE_DECODER_JPEG_INFO;\r
	81	\r
	82	//\r
	83	// EFI_HII_IMAGE_DECODER_PNG_INFO\r
	84	// Header The common header\r
	85	// Channels Number of channels in the PNG image\r
	86	// Reserved Reserved\r
	87	//\r
	88	typedef struct _EFI_HII_IMAGE_DECODER_PNG_INFO {\r
	89	EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER Header;\r
	90	UINT16 Channels;\r
	91	UINT64 Reserved;\r
	92	} EFI_HII_IMAGE_DECODER_PNG_INFO;\r
	93	\r
	94	/**\r
95	There could be more than one EFI_HII_IMAGE_DECODER_PROTOCOL instances installed\r
96	in the system for different image formats. This function returns the decoder\r
97	name which callers can use to find the proper image decoder for the image. It\r
98	is possible to support multiple image formats in one EFI_HII_IMAGE_DECODER_PROTOCOL.\r
99	The capability of the supported image formats is returned in DecoderName and\r
100	NumberOfDecoderName.\r
101	\r
102	@param This EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
103	@param DecoderName Pointer to a dimension to retrieve the decoder\r
104	names in EFI_GUID format. The number of the\r
105	decoder names is returned in NumberOfDecoderName.\r
106	@param NumberofDecoderName Pointer to retrieve the number of decoders which\r
107	supported by this decoder driver.\r
108	\r
109	@retval EFI_SUCCESS Get decoder name success.\r
110	@retval EFI_UNSUPPORTED Get decoder name fail.\r
111	\r
112	**/\r
113	typedef\r
114	EFI_STATUS\r
115	(EFIAPI *EFI_HII_IMAGE_DECODER_GET_DECODER_NAME)(\r
116	IN EFI_HII_IMAGE_DECODER_PROTOCOL *This,\r
117	IN OUT EFI_GUID **DecoderName,\r
118	IN OUT UINT16 *NumberofDecoderName\r
119	);\r
120	\r
121	/**\r
122	This function returns the image information of the given image raw data. This\r
123	function first checks whether the image raw data is supported by this decoder\r
124	or not. This function may go through the first few bytes in the image raw data\r
125	for the specific data structure or the image signature. If the image is not supported\r
126	by this image decoder, this function returns EFI_UNSUPPORTED to the caller.\r
127	Otherwise, this function returns the proper image information to the caller.\r
128	It is the caller?s responsibility to free the ImageInfo.\r
129	\r
130	@param This EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
131	@param Image Pointer to the image raw data.\r
132	@param SizeOfImage Size of the entire image raw data.\r
133	@param ImageInfo Pointer to recieve EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER.\r
134	\r
135	@retval EFI_SUCCESS Get image info success.\r
136	@retval EFI_UNSUPPORTED Unsupported format of image.\r
137	@retval EFI_INVALID_PARAMETER Incorrect parameter.\r
138	@retval EFI_BAD_BUFFER_SIZE Not enough memory.\r
139	\r
140	**/\r
141	typedef\r
142	EFI_STATUS\r
143	(EFIAPI *EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO)(\r
144	IN EFI_HII_IMAGE_DECODER_PROTOCOL *This,\r
145	IN VOID *Image,\r
146	IN UINTN SizeOfImage,\r
147	IN OUT EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER **ImageInfo\r
148	);\r
149	\r
150	/**\r
151	This function decodes the image which the image type of this image is supported\r
152	by this EFI_HII_IMAGE_DECODER_PROTOCOL. If **Bitmap is not NULL, the caller intends\r
153	to put the image in the given image buffer. That allows the caller to put an\r
154	image overlap on the original image. The transparency is handled by the image\r
155	decoder because the transparency capability depends on the image format. Callers\r
156	can set Transparent to FALSE to force disabling the transparency process on the\r
157	image. Forcing Transparent to FALSE may also improve the performance of the image\r
158	decoding because the image decoder can skip the transparency processing. If **Bitmap\r
159	is NULL, the image decoder allocates the memory buffer for the EFI_IMAGE_OUTPUT\r
160	and decodes the image to the image buffer. It is the caller?s responsibility to\r
161	free the memory for EFI_IMAGE_OUTPUT. Image decoder doesn?t have to handle the\r
162	transparency in this case because there is no background image given by the caller.\r
163	The background color in this case is all black (#00000000).\r
164	\r
165	@param This EFI_HII_IMAGE_DECODER_PROTOCOL instance.\r
166	@param Image Pointer to the image raw data.\r
167	@param ImageRawDataSize Size of the entire image raw data.\r
168	@param Blt EFI_IMAGE_OUTPUT to receive the image or overlap\r
169	the image on the original buffer.\r
170	@param Transparent BOOLEAN value indicates whether the image decoder\r
171	has to handle the transparent image or not.\r
172	\r
173	\r
174	@retval EFI_SUCCESS Image decode success.\r
175	@retval EFI_UNSUPPORTED Unsupported format of image.\r
176	@retval EFI_INVALID_PARAMETER Incorrect parameter.\r
177	@retval EFI_BAD_BUFFER_SIZE Not enough memory.\r
178	\r
179	**/\r
180	typedef\r
181	EFI_STATUS\r
182	(EFIAPI *EFI_HII_IMAGE_DECODER_DECODE)(\r
183	IN EFI_HII_IMAGE_DECODER_PROTOCOL *This,\r
184	IN VOID *Image,\r
185	IN UINTN ImageRawDataSize,\r
186	IN OUT EFI_IMAGE_OUTPUT **BitMap OPTIONAL,\r
187	IN BOOLEAN Transparent\r
188	);\r
189	\r
190	struct _EFI_HII_IMAGE_DECODER_PROTOCOL {\r
191	EFI_HII_IMAGE_DECODER_GET_DECODER_NAME GetImageDecoderName;\r
192	EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO GetImageInfo;\r
193	EFI_HII_IMAGE_DECODER_DECODE DecodeImage;\r
194	};\r
195	\r
196	extern EFI_GUID gEfiHiiImageDecoderProtocolGuid;\r
197	extern EFI_GUID gEfiHiiImageDecoderNameJpegGuid;\r
198	extern EFI_GUID gEfiHiiImageDecoderNamePngGuid;\r
199	\r
200	#endif\r