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