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