1 /** @file 2 The file provides services to access to images in the images database. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 @par Revision Reference: 8 This Protocol was introduced in UEFI Specification 2.1. 9 10 **/ 11 12 #ifndef __HII_IMAGE_H__ 13 #define __HII_IMAGE_H__ 14 15 #include <Protocol/GraphicsOutput.h> 16 17 #define EFI_HII_IMAGE_PROTOCOL_GUID \ 18 { 0x31a6406a, 0x6bdf, 0x4e46, { 0xb2, 0xa2, 0xeb, 0xaa, 0x89, 0xc4, 0x9, 0x20 } } 19 20 typedef struct _EFI_HII_IMAGE_PROTOCOL EFI_HII_IMAGE_PROTOCOL; 21 22 /// 23 /// Flags in EFI_IMAGE_INPUT 24 /// 25 #define EFI_IMAGE_TRANSPARENT 0x00000001 26 27 /** 28 29 Definition of EFI_IMAGE_INPUT. 30 31 @param Flags Describe image characteristics. If 32 EFI_IMAGE_TRANSPARENT is set, then the image was 33 designed for transparent display. 34 35 @param Width Image width, in pixels. 36 37 @param Height Image height, in pixels. 38 39 @param Bitmap A pointer to the actual bitmap, organized left-to-right, 40 top-to-bottom. The size of the bitmap is 41 Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL). 42 43 44 **/ 45 typedef struct _EFI_IMAGE_INPUT { 46 UINT32 Flags; 47 UINT16 Width; 48 UINT16 Height; 49 EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Bitmap; 50 } EFI_IMAGE_INPUT; 51 52 /** 53 54 This function adds the image Image to the group of images 55 owned by PackageList, and returns a new image identifier 56 (ImageId). 57 58 @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. 59 60 @param PackageList Handle of the package list where this image will be added. 61 62 @param ImageId On return, contains the new image id, which is 63 unique within PackageList. 64 65 @param Image Points to the image. 66 67 @retval EFI_SUCCESS The new image was added 68 successfully 69 70 @retval EFI_OUT_OF_RESOURCES Could not add the image. 71 72 @retval EFI_INVALID_PARAMETER Image is NULL or ImageId is 73 NULL. 74 75 76 **/ 77 typedef 78 EFI_STATUS 79 (EFIAPI *EFI_HII_NEW_IMAGE)( 80 IN CONST EFI_HII_IMAGE_PROTOCOL *This, 81 IN EFI_HII_HANDLE PackageList, 82 OUT EFI_IMAGE_ID *ImageId, 83 IN CONST EFI_IMAGE_INPUT *Image 84 ); 85 86 /** 87 88 This function retrieves the image specified by ImageId which 89 is associated with the specified PackageList and copies it 90 into the buffer specified by Image. If the image specified by 91 ImageId is not present in the specified PackageList, then 92 EFI_NOT_FOUND is returned. If the buffer specified by 93 ImageSize is too small to hold the image, then 94 EFI_BUFFER_TOO_SMALL will be returned. ImageSize will be 95 updated to the size of buffer actually required to hold the 96 image. 97 98 @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. 99 100 @param PackageList The package list in the HII database to 101 search for the specified image. 102 103 @param ImageId The image's id, which is unique within 104 PackageList. 105 106 @param Image Points to the new image. 107 108 @retval EFI_SUCCESS The image was returned successfully. 109 110 @retval EFI_NOT_FOUND The image specified by ImageId is not 111 available. Or The specified PackageList is not in the database. 112 113 @retval EFI_INVALID_PARAMETER The Image or Langugae was NULL. 114 @retval EFI_OUT_OF_RESOURCES The bitmap could not be retrieved because there was not 115 enough memory. 116 117 118 **/ 119 typedef 120 EFI_STATUS 121 (EFIAPI *EFI_HII_GET_IMAGE)( 122 IN CONST EFI_HII_IMAGE_PROTOCOL *This, 123 IN EFI_HII_HANDLE PackageList, 124 IN EFI_IMAGE_ID ImageId, 125 OUT EFI_IMAGE_INPUT *Image 126 ); 127 128 /** 129 130 This function updates the image specified by ImageId in the 131 specified PackageListHandle to the image specified by Image. 132 133 134 @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. 135 136 @param PackageList The package list containing the images. 137 138 @param ImageId The image id, which is unique within PackageList. 139 140 @param Image Points to the image. 141 142 @retval EFI_SUCCESS The image was successfully updated. 143 144 @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. 145 The specified PackageList is not in the database. 146 147 @retval EFI_INVALID_PARAMETER The Image or Language was NULL. 148 149 **/ 150 typedef 151 EFI_STATUS 152 (EFIAPI *EFI_HII_SET_IMAGE)( 153 IN CONST EFI_HII_IMAGE_PROTOCOL *This, 154 IN EFI_HII_HANDLE PackageList, 155 IN EFI_IMAGE_ID ImageId, 156 IN CONST EFI_IMAGE_INPUT *Image 157 ); 158 159 /// 160 /// EFI_HII_DRAW_FLAGS describes how the image is to be drawn. 161 /// These flags are defined as EFI_HII_DRAW_FLAG_*** 162 /// 163 typedef UINT32 EFI_HII_DRAW_FLAGS; 164 165 #define EFI_HII_DRAW_FLAG_CLIP 0x00000001 166 #define EFI_HII_DRAW_FLAG_TRANSPARENT 0x00000030 167 #define EFI_HII_DRAW_FLAG_DEFAULT 0x00000000 168 #define EFI_HII_DRAW_FLAG_FORCE_TRANS 0x00000010 169 #define EFI_HII_DRAW_FLAG_FORCE_OPAQUE 0x00000020 170 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080 171 172 /** 173 174 Definition of EFI_IMAGE_OUTPUT. 175 176 @param Width Width of the output image. 177 178 @param Height Height of the output image. 179 180 @param Bitmap Points to the output bitmap. 181 182 @param Screen Points to the EFI_GRAPHICS_OUTPUT_PROTOCOL which 183 describes the screen on which to draw the 184 specified image. 185 186 **/ 187 typedef struct _EFI_IMAGE_OUTPUT { 188 UINT16 Width; 189 UINT16 Height; 190 union { 191 EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Bitmap; 192 EFI_GRAPHICS_OUTPUT_PROTOCOL *Screen; 193 } Image; 194 } EFI_IMAGE_OUTPUT; 195 196 /** 197 198 This function renders an image to a bitmap or the screen using 199 the specified color and options. It draws the image on an 200 existing bitmap, allocates a new bitmap or uses the screen. The 201 images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then 202 all pixels drawn outside the bounding box specified by Width and 203 Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT is set, 204 then all 'off' pixels in the images drawn will use the 205 pixel value from Blt. This flag cannot be used if Blt is NULL 206 upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then the image 207 will be written directly to the output device specified by 208 Screen. Otherwise the image will be rendered to the bitmap 209 specified by Bitmap. 210 211 212 @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. 213 214 @param Flags Describes how the image is to be drawn. 215 EFI_HII_DRAW_FLAGS is defined in Related 216 Definitions, below. 217 218 @param Image Points to the image to be displayed. 219 220 @param Blt If this points to a non-NULL on entry, this points 221 to the image, which is Width pixels wide and 222 Height pixels high. The image will be drawn onto 223 this image and EFI_HII_DRAW_FLAG_CLIP is implied. 224 If this points to a NULL on entry, then a buffer 225 will be allocated to hold the generated image and 226 the pointer updated on exit. It is the caller's 227 responsibility to free this buffer. 228 229 @param BltX, BltY Specifies the offset from the left and top 230 edge of the image of the first pixel in 231 the image. 232 233 @retval EFI_SUCCESS The image was successfully updated. 234 235 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output 236 buffer for RowInfoArray or Blt. 237 238 @retval EFI_INVALID_PARAMETER The Image or Blt or Height or 239 Width was NULL. 240 241 242 **/ 243 typedef 244 EFI_STATUS 245 (EFIAPI *EFI_HII_DRAW_IMAGE)( 246 IN CONST EFI_HII_IMAGE_PROTOCOL *This, 247 IN EFI_HII_DRAW_FLAGS Flags, 248 IN CONST EFI_IMAGE_INPUT *Image, 249 IN OUT EFI_IMAGE_OUTPUT **Blt, 250 IN UINTN BltX, 251 IN UINTN BltY 252 ); 253 254 /** 255 256 This function renders an image as a bitmap or to the screen and 257 can clip the image. The bitmap is either supplied by the caller 258 or else is allocated by the function. The images can be drawn 259 transparently or opaquely. If EFI_HII_DRAW_FLAG_CLIP is set, 260 then all pixels drawn outside the bounding box specified by 261 Width and Height are ignored. If EFI_HII_DRAW_FLAG_TRANSPARENT 262 is set, then all "off" pixels in the character's glyph will 263 use the pixel value from Blt. This flag cannot be used if Blt 264 is NULL upon entry. If EFI_HII_DIRECT_TO_SCREEN is set, then 265 the image will be written directly to the output device 266 specified by Screen. Otherwise the image will be rendered to 267 the bitmap specified by Bitmap. 268 This function renders an image to a bitmap or the screen using 269 the specified color and options. It draws the image on an 270 existing bitmap, allocates a new bitmap or uses the screen. The 271 images can be clipped. If EFI_HII_DRAW_FLAG_CLIP is set, then 272 all pixels drawn outside the bounding box specified by Width and 273 Height are ignored. The EFI_HII_DRAW_FLAG_TRANSPARENT flag 274 determines whether the image will be drawn transparent or 275 opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image 276 will be drawn so that all 'off' pixels in the image will 277 be drawn using the pixel value from Blt and all other pixels 278 will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then 279 the image's pixels will be copied directly to the 280 destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image 281 will be drawn transparently or opaque, depending on the 282 image's transparency setting (see EFI_IMAGE_TRANSPARENT). 283 Images cannot be drawn transparently if Blt is NULL. If 284 EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written 285 directly to the output device specified by Screen. Otherwise the 286 image will be rendered to the bitmap specified by Bitmap. 287 288 @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. 289 290 @param Flags Describes how the image is to be drawn. 291 292 @param PackageList The package list in the HII database to 293 search for the specified image. 294 295 @param ImageId The image's id, which is unique within PackageList. 296 297 @param Blt If this points to a non-NULL on entry, this points 298 to the image, which is Width pixels wide and 299 Height pixels high. The image will be drawn onto 300 this image and EFI_HII_DRAW_FLAG_CLIP is implied. 301 If this points to a NULL on entry, then a buffer 302 will be allocated to hold the generated image and 303 the pointer updated on exit. It is the caller's 304 responsibility to free this buffer. 305 306 @param BltX, BltY Specifies the offset from the left and top 307 edge of the output image of the first 308 pixel in the image. 309 310 @retval EFI_SUCCESS The image was successfully updated. 311 312 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output 313 buffer for RowInfoArray or Blt. 314 315 @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. 316 Or The specified PackageList is not in the database. 317 318 @retval EFI_INVALID_PARAMETER The Blt was NULL. 319 320 **/ 321 typedef 322 EFI_STATUS 323 (EFIAPI *EFI_HII_DRAW_IMAGE_ID)( 324 IN CONST EFI_HII_IMAGE_PROTOCOL *This, 325 IN EFI_HII_DRAW_FLAGS Flags, 326 IN EFI_HII_HANDLE PackageList, 327 IN EFI_IMAGE_ID ImageId, 328 IN OUT EFI_IMAGE_OUTPUT **Blt, 329 IN UINTN BltX, 330 IN UINTN BltY 331 ); 332 333 /// 334 /// Services to access to images in the images database. 335 /// 336 struct _EFI_HII_IMAGE_PROTOCOL { 337 EFI_HII_NEW_IMAGE NewImage; 338 EFI_HII_GET_IMAGE GetImage; 339 EFI_HII_SET_IMAGE SetImage; 340 EFI_HII_DRAW_IMAGE DrawImage; 341 EFI_HII_DRAW_IMAGE_ID DrawImageId; 342 }; 343 344 extern EFI_GUID gEfiHiiImageProtocolGuid; 345 346 #endif 347