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 249