MdePkg/Include/Protocol/HiiImageDecoder.h

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