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