MdePkg/Include/Protocol/HiiImageEx.h

   1 /** @file
   2   Protocol which allows access to the images in the images database.
   3
   4 (C) Copyright 2016-2018 Hewlett Packard Enterprise Development LP<BR>
   5
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php.
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference:
  15   This Protocol was introduced in UEFI Specification 2.6.
  16
  17 **/
  18
  19 #ifndef __EFI_HII_IMAGE_EX_H__
  20 #define __EFI_HII_IMAGE_EX_H__
  21
  22 #include <Protocol/HiiImage.h>
  23
  24 //
  25 // Global ID for the Hii Image Ex Protocol.
  26 //
  27 #define EFI_HII_IMAGE_EX_PROTOCOL_GUID \
  28   {0x1a1241e6, 0x8f19, 0x41a9,  { 0xbc, 0xe, 0xe8, 0xef, 0x39, 0xe0, 0x65, 0x46 }}
  29
  30 typedef struct _EFI_HII_IMAGE_EX_PROTOCOL EFI_HII_IMAGE_EX_PROTOCOL;
  31
  32 /**
  33   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NewImage().
  34   This protocol invokes EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.
  35
  36   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
  37   @param  PackageList            Handle of the package list where this image will
  38                                  be added.
  39   @param  ImageId                On return, contains the new image id, which is
  40                                  unique within PackageList.
  41   @param  Image                  Points to the image.
  42
  43   @retval EFI_SUCCESS            The new image was added successfully.
  44   @retval EFI_NOT_FOUND          The specified PackageList could not be found in
  45                                  database.
  46   @retval EFI_OUT_OF_RESOURCES   Could not add the image due to lack of resources.
  47   @retval EFI_INVALID_PARAMETER  Image is NULL or ImageId is NULL.
  48
  49 **/
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EFI_HII_NEW_IMAGE_EX)(
  53   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL  *This,
  54   IN        EFI_HII_HANDLE              PackageList,
  55   OUT       EFI_IMAGE_ID                *ImageId,
  56   IN CONST  EFI_IMAGE_INPUT             *Image
  57   );
  58
  59 /**
  60   Return the information about the image, associated with the package list.
  61   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GetImage().
  62
  63   This function is similar to EFI_HII_IMAGE_PROTOCOL.GetImage().The difference is that
  64   this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the
  65   system if the decoder of the certain image type is not supported by the
  66   EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the
  67   EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that
  68   supports the requested image type.
  69
  70   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
  71   @param  PackageList            The package list in the HII database to search for the
  72                                  specified image.
  73   @param  ImageId                The image's id, which is unique within PackageList.
  74   @param  Image                  Points to the image.
  75
  76   @retval EFI_SUCCESS            The new image was returned successfully.
  77   @retval EFI_NOT_FOUND          The image specified by ImageId is not available. The specified
  78                                  PackageList is not in the Database.
  79   @retval EFI_INVALID_PARAMETER  Image was NULL or ImageId was 0.
  80   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there
  81                                  was not enough memory.
  82
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_HII_GET_IMAGE_EX)(
  87   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL       *This,
  88   IN        EFI_HII_HANDLE                  PackageList,
  89   IN        EFI_IMAGE_ID                    ImageId,
  90   OUT       EFI_IMAGE_INPUT                 *Image
  91   );
  92
  93 /**
  94   Change the information about the image.
  95
  96   Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes
  97   EFI_HII_IMAGE_PROTOCOL.SetImage()implicitly.
  98
  99   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
 100   @param  PackageList            The package list containing the images.
 101   @param  ImageId                The image's id, which is unique within PackageList.
 102   @param  Image                  Points to the image.
 103
 104   @retval EFI_SUCCESS            The new image was successfully updated.
 105   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the
 106                                  database. The specified PackageList is not in
 107                                  the database.
 108   @retval EFI_INVALID_PARAMETER  The Image was NULL, the ImageId was 0 or
 109                                  the Image->Bitmap was NULL.
 110
 111 **/
 112 typedef
 113 EFI_STATUS
 114 (EFIAPI *EFI_HII_SET_IMAGE_EX)(
 115   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,
 116   IN        EFI_HII_HANDLE              PackageList,
 117   IN        EFI_IMAGE_ID                ImageId,
 118   IN CONST  EFI_IMAGE_INPUT             *Image
 119   );
 120
 121 /**
 122   Renders an image to a bitmap or to the display.
 123
 124   The prototype of this extension function is the same with
 125   EFI_HII_IMAGE_PROTOCOL.DrawImage(). This protocol invokes
 126   EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly.
 127
 128   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
 129   @param  Flags                  Describes how the image is to be drawn.
 130   @param  Image                  Points to the image to be displayed.
 131   @param  Blt                    If this points to a non-NULL on entry, this points
 132                                  to the image, which is Width pixels wide and
 133                                  Height pixels high.  The image will be drawn onto
 134                                  this image and  EFI_HII_DRAW_FLAG_CLIP is implied.
 135                                  If this points to a NULL on entry, then a buffer
 136                                  will be allocated to hold the generated image and
 137                                  the pointer updated on exit. It is the caller's
 138                                  responsibility to free this buffer.
 139   @param  BltX                   Specifies the offset from the left and top edge of
 140                                  the output image of the first pixel in the image.
 141   @param  BltY                   Specifies the offset from the left and top edge of
 142                                  the output image of the first pixel in the image.
 143
 144   @retval EFI_SUCCESS            The image was successfully drawn.
 145   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.
 146   @retval EFI_INVALID_PARAMETER  The Image or Blt was NULL.
 147
 148 **/
 149 typedef
 150 EFI_STATUS
 151 (EFIAPI *EFI_HII_DRAW_IMAGE_EX)(
 152   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,
 153   IN        EFI_HII_DRAW_FLAGS          Flags,
 154   IN CONST  EFI_IMAGE_INPUT             *Image,
 155   IN OUT    EFI_IMAGE_OUTPUT            **Blt,
 156   IN        UINTN                       BltX,
 157   IN        UINTN                       BltY
 158   );
 159
 160 /**
 161   Renders an image to a bitmap or the screen containing the contents of the specified
 162   image.
 163
 164   This function is similar to EFI_HII_IMAGE_PROTOCOL.DrawImageId(). The difference is that
 165   this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the
 166   system if the decoder of the certain image type is not supported by the
 167   EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the
 168   EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that
 169   supports the requested image type.
 170
 171   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
 172   @param  Flags                  Describes how the image is to be drawn.
 173   @param  PackageList            The package list in the HII database to search for
 174                                  the  specified image.
 175   @param  ImageId                The image's id, which is unique within PackageList.
 176   @param  Blt                    If this points to a non-NULL on entry, this points
 177                                  to the image, which is Width pixels wide and
 178                                  Height pixels high. The image will be drawn onto
 179                                  this image and EFI_HII_DRAW_FLAG_CLIP is implied.
 180                                  If this points to a NULL on entry, then a buffer
 181                                  will be allocated to hold  the generated image
 182                                  and the pointer updated on exit. It is the caller's
 183                                  responsibility to free this buffer.
 184   @param  BltX                   Specifies the offset from the left and top edge of
 185                                  the output image of the first pixel in the image.
 186   @param  BltY                   Specifies the offset from the left and top edge of
 187                                  the output image of the first pixel in the image.
 188
 189   @retval EFI_SUCCESS            The image was successfully drawn.
 190   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.
 191   @retval EFI_INVALID_PARAMETER  The Blt was NULL or ImageId was 0.
 192   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the database.
 193                                  The specified PackageList is not in the database.
 194
 195 **/
 196 typedef
 197 EFI_STATUS
 198 (EFIAPI *EFI_HII_DRAW_IMAGE_ID_EX)(
 199   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL   *This,
 200   IN        EFI_HII_DRAW_FLAGS          Flags,
 201   IN        EFI_HII_HANDLE              PackageList,
 202   IN        EFI_IMAGE_ID                ImageId,
 203   IN OUT    EFI_IMAGE_OUTPUT            **Blt,
 204   IN        UINTN                       BltX,
 205   IN        UINTN                       BltY
 206   );
 207
 208 /**
 209   This function returns the image information to EFI_IMAGE_OUTPUT. Only the width
 210   and height are returned to the EFI_IMAGE_OUTPUT instead of decoding the image
 211   to the buffer. This function is used to get the geometry of the image. This function
 212   will try to locate all of the EFI_HII_IMAGE_DECODER_PROTOCOL installed on the
 213   system if the decoder of image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL.
 214
 215   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
 216   @param  PackageList            Handle of the package list where this image will
 217                                  be searched.
 218   @param  ImageId                The image's id, which is unique within PackageList.
 219   @param  Image                  Points to the image.
 220
 221   @retval EFI_SUCCESS            The new image was returned successfully.
 222   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the
 223                                  database. The specified PackageList is not in the database.
 224   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to
 225                                  hold the image.
 226   @retval EFI_INVALID_PARAMETER  The Image was NULL or the ImageId was 0.
 227   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there
 228                                  was not enough memory.
 229
 230 **/
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *EFI_HII_GET_IMAGE_INFO)(
 234   IN CONST  EFI_HII_IMAGE_EX_PROTOCOL       *This,
 235   IN        EFI_HII_HANDLE                  PackageList,
 236   IN        EFI_IMAGE_ID                    ImageId,
 237   OUT       EFI_IMAGE_OUTPUT                *Image
 238   );
 239
 240 ///
 241 /// Protocol which allows access to the images in the images database.
 242 ///
 243 struct _EFI_HII_IMAGE_EX_PROTOCOL {
 244   EFI_HII_NEW_IMAGE_EX      NewImageEx;
 245   EFI_HII_GET_IMAGE_EX      GetImageEx;
 246   EFI_HII_SET_IMAGE_EX      SetImageEx;
 247   EFI_HII_DRAW_IMAGE_EX     DrawImageEx;
 248   EFI_HII_DRAW_IMAGE_ID_EX  DrawImageIdEx;
 249   EFI_HII_GET_IMAGE_INFO    GetImageInfo;
 250 };
 251
 252 extern EFI_GUID gEfiHiiImageExProtocolGuid;
 253
 254 #endif