MdePkg/Include/Protocol/HiiImageEx.h

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