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