MdePkg: Add UEFI2.6 HII Image Ex and Image Decoder protocol definition.

Add the definition for the new UEFI 2.6 EFI_HII_IMAGE_EX_PROTOCOL and
EFI_IMAGE_DECODER_PROTOCOL.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Cecil Sheng <cecil.sheng@hpe.com>
Reviewed-by: Samer El-Haj-Mahmoud <elhaj@hpe.com>
Reviewed-by: Abner Chang <abner.chang@hpe.com>
Reviewed-by: Eric Dong <eric.dong@intel.com>

2 files changed, 437 insertions, 0 deletions

diff --git a/MdePkg/Include/Protocol/HiiImageEx.h b/MdePkg/Include/Protocol/HiiImageEx.h
new file mode 100644
index 0000000000..9905ecda7d
--- /dev/null
+++ b/MdePkg/Include/Protocol/HiiImageEx.h
@@ -0,0 +1,245 @@
+/** @file

+  Protocol which allows access to the images in the images database.

+

+(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>

+

+This program and the accompanying materials are licensed and made available under

+the terms and conditions of the BSD License that accompanies this distribution.

+The full text of the license may be found at

+http://opensource.org/licenses/bsd-license.php.

+

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+

+**/

+

+#ifndef __EFI_HII_IMAGE_EX_H__

+#define __EFI_HII_IMAGE_EX_H__

+

+#include <Protocol/HiiImage.h>

+

+//

+// Global ID for the Hii Image Ex Protocol.

+//

+#define EFI_HII_IMAGE_EX_PROTOCOL_GUID \

+  {0x1a1241e6, 0x8f19, 0x41a9,  { 0xbc, 0xe, 0xe8, 0xef, 0x39, 0xe0, 0x65, 0x46 }}

+

+typedef struct _EFI_HII_IMAGE_EX_PROTOCOL EFI_HII_IMAGE_EX_PROTOCOL;

+

+/**

+  The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NewImage().

+  Same with EFI_HII_IMAGE_PROTOCOL.NewImage().This protocol invokes

+EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  PackageList            Handle of the package list where this image will

+                                 be added.

+  @param  ImageId                On return, contains the new image id, which is

+                                 unique within PackageList.

+  @param  Image                  Points to the image.

+

+  @retval EFI_SUCCESS            The new image was added successfully.

+  @retval EFI_NOT_FOUND          The specified PackageList could not be found in

+                                 database.

+  @retval EFI_OUT_OF_RESOURCES   Could not add the image due to lack of resources.

+  @retval EFI_INVALID_PARAMETER  Image is NULL or ImageId is NULL.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_NEW_IMAGE_EX)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL  *This,

+  IN        EFI_HII_HANDLE              PackageList,

+  OUT       EFI_IMAGE_ID                *ImageId,

+  IN CONST  EFI_IMAGE_INPUT             *Image

+  );

+

+/**

+  Return the information about the image, associated with the package list.

+  The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GetImage().

+  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  PackageList            Handle of the package list where this image will

+                                 be searched.

+  @param  ImageId                The image's id,, which is unique within

+                                 PackageList.

+  @param  Image                  Points to the image.

+

+  @retval EFI_SUCCESS            The new image was returned successfully.

+  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the

+                                 database. The specified PackageList is not in

+                                 the database.

+  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to

+                                 hold the image.

+  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.

+  @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there

+                                 was not enough memory.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_GET_IMAGE_EX)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL       *This,

+  IN        EFI_HII_HANDLE                  PackageList,

+  IN        EFI_IMAGE_ID                    ImageId,

+  OUT       EFI_IMAGE_INPUT                 *Image

+  );

+

+/**

+  Change the information about the image. The prototype of this extension

+  function is the same with EFI_HII_IMAGE_PROTOCOL.SetImage().  Same with

+  EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  PackageList            The package list containing the images.

+  @param  ImageId                The image's id,, which is unique within

+                                 PackageList.

+  @param  Image                  Points to the image.

+

+  @retval EFI_SUCCESS            The new image was updated successfully.

+  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the

+                                 database. The specified PackageList is not in

+                                 the database.

+  @retval EFI_INVALID_PARAMETER  The Image was NULL.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_SET_IMAGE_EX)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,

+  IN        EFI_HII_HANDLE              PackageList,

+  IN        EFI_IMAGE_ID                ImageId,

+  IN CONST  EFI_IMAGE_INPUT             *Image

+  );

+

+/**

+  Renders an image to a bitmap or to the display. The prototype of this extension

+  function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImage().

+  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  Flags                  Describes how the image is to be drawn.

+  @param  Image                  Points to the image to be displayed.

+  @param  Blt                    If this points to a non-NULL on entry, this points

+                                 to the image, which is Width pixels wide and

+                                 Height pixels high.  The image will be drawn onto

+                                 this image and  EFI_HII_DRAW_FLAG_CLIP is implied.

+                                 If this points to a  NULL on entry, then a buffer

+                                 will be allocated to hold  the generated image and

+                                 the pointer updated on exit. It is the caller's

+                                 responsibility to free this buffer.

+  @param  BltX                   Specifies the offset from the left and top edge of

+                                 the  output image of the first pixel in the image.

+  @param  BltY                   Specifies the offset from the left and top edge of

+                                 the  output image of the first pixel in the image.

+

+  @retval EFI_SUCCESS            The image was successfully drawn.

+  @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.

+  @retval EFI_INVALID_PARAMETER  The Image or Blt was NULL.

+                                 Any combination of Flags is invalid.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_DRAW_IMAGE_EX)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,

+  IN        EFI_HII_DRAW_FLAGS          Flags,

+  IN CONST  EFI_IMAGE_INPUT             *Image,

+  IN OUT    EFI_IMAGE_OUTPUT            **Blt,

+  IN        UINTN                       BltX,

+  IN        UINTN                       BltY

+  );

+

+/**

+  Renders an image to a bitmap or the screen containing the contents of the specified

+  image. The prototype of this extension function is the same with E

+  FI_HII_IMAGE_PROTOCOL.DrawImageId().

+  Same with EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes

+EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  Flags                  Describes how the image is to be drawn.

+  @param  PackageList            The package list in the HII database to search for

+                                 the  specified image.

+  @param  ImageId                The image's id, which is unique within

+                                 PackageList.

+  @param  Blt                    If this points to a non-NULL on entry, this points

+                                 to the image, which is Width pixels wide and

+                                 Height pixels high. The image will be drawn onto

+                                 this image and EFI_HII_DRAW_FLAG_CLIP is implied.

+                                 If this points to a NULL on entry, then a buffer

+                                 will be allocated to hold  the generated image

+                                 and the pointer updated on exit. It is the caller's

+                                 responsibility to free this buffer.

+  @param  BltX                   Specifies the offset from the left and top edge of

+                                 the output image of the first pixel in the image.

+  @param  BltY                   Specifies the offset from the left and top edge of

+                                 the output image of the first pixel in the image.

+

+  @retval EFI_SUCCESS            The image was successfully drawn.

+  @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.

+  @retval EFI_INVALID_PARAMETER  The Blt was NULL.

+  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the database.

+                                 The specified PackageList is not in the database.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_DRAW_IMAGE_ID_EX)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,

+  IN        EFI_HII_DRAW_FLAGS          Flags,

+  IN        EFI_HII_HANDLE              PackageList,

+  IN        EFI_IMAGE_ID                ImageId,

+  IN OUT    EFI_IMAGE_OUTPUT            **Blt,

+  IN        UINTN                       BltX,

+  IN        UINTN                       BltY

+  );

+

+/**

+  This function returns the image information to EFI_IMAGE_OUTPUT. Only the width

+  and height are returned to the EFI_IMAGE_OUTPUT instead of decoding the image

+  to the buffer. This function is used to get the geometry of the image. This function

+  will try to locate all of the EFI_HII_IMAGE_DECODER_PROTOCOL installed on the

+  system if the decoder of image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL.

+

+  @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.

+  @param  PackageList            Handle of the package list where this image will

+                                 be searched.

+  @param  ImageId                The image's id,, which is unique within PackageList.

+  @param  Image                  Points to the image.

+

+  @retval EFI_SUCCESS            The new image was returned successfully.

+  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the

+                                 database. The specified PackageList is not in the database.

+  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to

+                                 hold the image.

+  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.

+  @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there

+                                 was not enough memory.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_GET_IMAGE_INFO)(

+  IN CONST  EFI_HII_IMAGE_EX_PROTOCOL       *This,

+  IN        EFI_HII_HANDLE                  PackageList,

+  IN        EFI_IMAGE_ID                    ImageId,

+  OUT       EFI_IMAGE_INPUT                 *Image

+  );

+

+///

+/// Protocol which allows access to the images in the images database.

+///

+struct _EFI_HII_IMAGE_EX_PROTOCOL {

+  EFI_HII_NEW_IMAGE_EX      NewImageEx;

+  EFI_HII_GET_IMAGE_EX      GetImageEx;

+  EFI_HII_SET_IMAGE_EX      SetImageEx;

+  EFI_HII_DRAW_IMAGE_EX     DrawImageEx;

+  EFI_HII_DRAW_IMAGE_ID_EX  DrawImageIdEx;

+  EFI_HII_GET_IMAGE_INFO    GetImageInfo;

+};

+

+extern EFI_GUID gEfiHiiImageExProtocolGuid;

+

+#endif

diff --git a/MdePkg/Include/Protocol/ImageDecoder.h b/MdePkg/Include/Protocol/ImageDecoder.h
new file mode 100644
index 0000000000..f1985bcd21
--- /dev/null
+++ b/MdePkg/Include/Protocol/ImageDecoder.h
@@ -0,0 +1,192 @@
+/** @file

+  This protocol provides generic image decoder interfaces to various image formats.

+

+(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>

+

+This program and the accompanying materials are licensed and made available under

+the terms and conditions of the BSD License that accompanies this distribution.

+The full text of the license may be found at

+http://opensource.org/licenses/bsd-license.php.

+

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+

+**/

+#ifndef __EFI_IMAGE_DECODER_PROTOCOL_H__

+#define __EFI_IMAGE_DECODER_PROTOCOL_H__

+

+#include <Protocol/HiiImage.h>

+

+

+#define EFI_HII_IMAGE_DECODER_PROTOCOL_GUID \

+  { 0x2f707ebb, 0x4a1a, 0x11d4, {0x9a,0x38,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

+

+

+#define EFI_HII_IMAGE_DECODER_NAME_JPEG_GUID \

+  {0xefefd093, 0xd9b, 0x46eb,  { 0xa8, 0x56, 0x48, 0x35, 0x7, 0x0, 0xc9, 0x8 }}

+

+#define EFI_HII_IMAGE_DECODER_NAME_PNG_GUID \

+  {0xaf060190, 0x5e3a, 0x4025, { 0xaf, 0xbd, 0xe1, 0xf9, 0x5, 0xbf, 0xaa, 0x4c }}

+

+typedef struct _EFI_HII_IMAGE_DECODER_PROTOCOL EFI_HII_IMAGE_DECODER_PROTOCOL;

+

+typedef enum {

+  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGB     = 0x0,

+  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGBA    = 0x1,

+  EFI_HII_IMAGE_DECODER_COLOR_TYPE_CMYK    = 0x2,

+  EFI_HII_IMAGE_DECODER_COLOR_TYPE_UNKNOWN = 0xFF

+} EFI_HII_IMAGE_DECODER_COLOR_TYPE;

+

+//

+// EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER

+//

+// DecoderName        Name of the decoder

+// ImageInfoSize      The size of entire image information structure in bytes

+// ImageWidth         The image width

+// ImageHeight        The image height

+// ColorType          The color type, see EFI_HII_IMAGE_DECODER_COLOR_TYPE.

+// ColorDepthInBits   The color depth in bits

+//

+typedef struct _EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER {

+  EFI_GUID                            DecoderName;

+  UINT16                              ImageInfoSize;

+  UINT16                              ImageWidth;

+  UINT16                              ImageHeight;

+  EFI_HII_IMAGE_DECODER_COLOR_TYPE    ColorType;

+  UINT8                               ColorDepthInBits;

+} EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER;

+

+//

+// EFI_HII_IMAGE_DECODER_JPEG_INFO

+// Header         The common header

+// ScanType       The scan type of JPEG image

+// Reserved       Reserved

+//

+typedef struct _EFI_HII_IMAGE_DECODER_JPEG_INFO {

+  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  Header;

+

+#define EFI_IMAGE_JPEG_SCANTYPE_PROGREESSIVE 0x01

+#define EFI_IMAGE_JPEG_SCANTYPE_INTERLACED   0x02

+  UINT16                                    ScanType;

+  UINT64                                    Reserved;

+} EFI_HII_IMAGE_DECODER_JPEG_INFO;

+

+//

+// EFI_HII_IMAGE_DECODER_PNG_INFO

+// Header         The common header

+// Channels       Number of channels in the PNG image

+// Reserved       Reserved

+//

+typedef struct _EFI_HII_IMAGE_DECODER_PNG_INFO {

+  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  Header;

+  UINT16                                    Channels;

+  UINT64                                    Reserved;

+} EFI_HII_IMAGE_DECODER_PNG_INFO;

+

+/**

+  There could be more than one EFI_HII_IMAGE_DECODER_PROTOCOL instances installed

+  in the system for different image formats. This function returns the decoder

+  name which callers can use to find the proper image decoder for the image. It

+  is possible to support multiple image formats in one EFI_HII_IMAGE_DECODER_PROTOCOL.

+  The capability of the supported image formats is returned in DecoderName and

+  NumberOfDecoderName.

+

+  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.

+  @param DecoderName             Pointer to a dimension to retrieve the decoder

+                                 names in EFI_GUID format. The number of the

+                                 decoder names is returned in NumberOfDecoderName.

+  @param NumberofDecoderName     Pointer to retrieve the number of decoders which

+                                 supported by this decoder driver.

+

+  @retval EFI_SUCCESS            Get decoder name success.

+  @retval EFI_UNSUPPORTED        Get decoder name fail.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_IMAGE_DECODER_GET_DECODER_NAME)(

+  IN      EFI_HII_IMAGE_DECODER_PROTOCOL   *This,

+  IN OUT  EFI_GUID                         **DecoderName,

+  IN OUT  UINT16                           *NumberofDecoderName

+  );

+

+/**

+  This function returns the image information of the given image raw data. This

+  function first checks whether the image raw data is supported by this decoder

+  or not. This function may go through the first few bytes in the image raw data

+  for the specific data structure or the image signature. If the image is not supported

+  by this image decoder, this function returns EFI_UNSUPPORTED to the caller.

+  Otherwise, this function returns the proper image information to the caller.

+  It is the caller?s responsibility to free the ImageInfo.

+

+  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.

+  @param Image                   Pointer to the image raw data.

+  @param SizeOfImage             Size of the entire image raw data.

+  @param ImageInfo               Pointer to recieve EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER.

+

+  @retval EFI_SUCCESS            Get image info success.

+  @retval EFI_UNSUPPORTED        Unsupported format of image.

+  @retval EFI_INVALID_PARAMETER  Incorrect parameter.

+  @retval EFI_BAD_BUFFER_SIZE    Not enough memory.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO)(

+  IN      EFI_HII_IMAGE_DECODER_PROTOCOL           *This,

+  IN      VOID                                     *Image,

+  IN      UINTN                                    SizeOfImage,

+  IN OUT  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER  **ImageInfo

+  );

+

+/**

+  This function decodes the image which the image type of this image is supported

+  by this EFI_HII_IMAGE_DECODER_PROTOCOL. If **Bitmap is not NULL, the caller intends

+  to put the image in the given image buffer. That allows the caller to put an

+  image overlap on the original image. The transparency is handled by the image

+  decoder because the transparency capability depends on the image format. Callers

+  can set Transparent to FALSE to force disabling the transparency process on the

+  image. Forcing Transparent to FALSE may also improve the performance of the image

+  decoding because the image decoder can skip the transparency processing.  If **Bitmap

+  is NULL, the image decoder allocates the memory buffer for the EFI_IMAGE_OUTPUT

+  and decodes the image to the image buffer. It is the caller?s responsibility to

+  free the memory for EFI_IMAGE_OUTPUT. Image decoder doesn?t have to handle the

+  transparency in this case because there is no background image given by the caller.

+  The background color in this case is all black (#00000000).

+

+  @param This                    EFI_HII_IMAGE_DECODER_PROTOCOL instance.

+  @param Image                   Pointer to the image raw data.

+  @param ImageRawDataSize        Size of the entire image raw data.

+  @param Blt                     EFI_IMAGE_OUTPUT to receive the image or overlap

+                                 the image on the original buffer.

+  @param Transparent             BOOLEAN value indicates whether the image decoder

+                                 has to handle the transparent image or not.

+

+

+  @retval EFI_SUCCESS            Image decode success.

+  @retval EFI_UNSUPPORTED        Unsupported format of image.

+  @retval EFI_INVALID_PARAMETER  Incorrect parameter.

+  @retval EFI_BAD_BUFFER_SIZE    Not enough memory.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_HII_IMAGE_DECODER_DECODE)(

+  IN      EFI_HII_IMAGE_DECODER_PROTOCOL   *This,

+  IN      VOID                              *Image,

+  IN      UINTN                             ImageRawDataSize,

+  IN OUT  EFI_IMAGE_OUTPUT                  **BitMap OPTIONAL,

+  IN      BOOLEAN                           Transparent

+  );

+

+struct _EFI_HII_IMAGE_DECODER_PROTOCOL {

+  EFI_HII_IMAGE_DECODER_GET_DECODER_NAME  GetImageDecoderName;

+  EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO    GetImageInfo;

+  EFI_HII_IMAGE_DECODER_DECODE            DecodeImage;

+};

+

+extern EFI_GUID gEfiHiiImageDecoderProtocolGuid;

+extern EFI_GUID gEfiHiiImageDecoderNameJpegGuid;

+extern EFI_GUID gEfiHiiImageDecoderNamePngGuid;

+

+#endif