iPXE
GraphicsOutput.h
Go to the documentation of this file.
00001 /** @file
00002   Graphics Output Protocol from the UEFI 2.0 specification.
00003 
00004   Abstraction of a very simple graphics device.
00005 
00006   Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
00007   This program and the accompanying materials
00008   are licensed and made available under the terms and conditions of the BSD License
00009   which accompanies this distribution.  The full text of the license may be found at
00010   http://opensource.org/licenses/bsd-license.php
00011 
00012   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00013   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00014 
00015 **/
00016 
00017 #ifndef __GRAPHICS_OUTPUT_H__
00018 #define __GRAPHICS_OUTPUT_H__
00019 
00020 FILE_LICENCE ( BSD3 );
00021 
00022 #define EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID \
00023   { \
00024     0x9042a9de, 0x23dc, 0x4a38, {0x96, 0xfb, 0x7a, 0xde, 0xd0, 0x80, 0x51, 0x6a } \
00025   }
00026 
00027 typedef struct _EFI_GRAPHICS_OUTPUT_PROTOCOL EFI_GRAPHICS_OUTPUT_PROTOCOL;
00028 
00029 typedef struct {
00030   UINT32            RedMask;
00031   UINT32            GreenMask;
00032   UINT32            BlueMask;
00033   UINT32            ReservedMask;
00034 } EFI_PIXEL_BITMASK;
00035 
00036 typedef enum {
00037   ///
00038   /// A pixel is 32-bits and byte zero represents red, byte one represents green,
00039   /// byte two represents blue, and byte three is reserved. This is the definition
00040   /// for the physical frame buffer. The byte values for the red, green, and blue
00041   /// components represent the color intensity. This color intensity value range
00042   /// from a minimum intensity of 0 to maximum intensity of 255.
00043   ///
00044   PixelRedGreenBlueReserved8BitPerColor,
00045   ///
00046   /// A pixel is 32-bits and byte zero represents blue, byte one represents green,
00047   /// byte two represents red, and byte three is reserved. This is the definition
00048   /// for the physical frame buffer. The byte values for the red, green, and blue
00049   /// components represent the color intensity. This color intensity value range
00050   /// from a minimum intensity of 0 to maximum intensity of 255.
00051   ///
00052   PixelBlueGreenRedReserved8BitPerColor,
00053   ///
00054   /// The Pixel definition of the physical frame buffer.
00055   ///
00056   PixelBitMask,
00057   ///
00058   /// This mode does not support a physical frame buffer.
00059   ///
00060   PixelBltOnly,
00061   ///
00062   /// Valid EFI_GRAPHICS_PIXEL_FORMAT enum values are less than this value.
00063   ///
00064   PixelFormatMax
00065 } EFI_GRAPHICS_PIXEL_FORMAT;
00066 
00067 typedef struct {
00068   ///
00069   /// The version of this data structure. A value of zero represents the
00070   /// EFI_GRAPHICS_OUTPUT_MODE_INFORMATION structure as defined in this specification.
00071   ///
00072   UINT32                     Version;
00073   ///
00074   /// The size of video screen in pixels in the X dimension.
00075   ///
00076   UINT32                     HorizontalResolution;
00077   ///
00078   /// The size of video screen in pixels in the Y dimension.
00079   ///
00080   UINT32                     VerticalResolution;
00081   ///
00082   /// Enumeration that defines the physical format of the pixel. A value of PixelBltOnly
00083   /// implies that a linear frame buffer is not available for this mode.
00084   ///
00085   EFI_GRAPHICS_PIXEL_FORMAT  PixelFormat;
00086   ///
00087   /// This bit-mask is only valid if PixelFormat is set to PixelPixelBitMask.
00088   /// A bit being set defines what bits are used for what purpose such as Red, Green, Blue, or Reserved.
00089   ///
00090   EFI_PIXEL_BITMASK          PixelInformation;
00091   ///
00092   /// Defines the number of pixel elements per video memory line.
00093   ///
00094   UINT32                     PixelsPerScanLine;
00095 } EFI_GRAPHICS_OUTPUT_MODE_INFORMATION;
00096 
00097 /**
00098   Returns information for an available graphics mode that the graphics device
00099   and the set of active video output devices supports.
00100 
00101   @param  This                  The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.
00102   @param  ModeNumber            The mode number to return information on.
00103   @param  SizeOfInfo            A pointer to the size, in bytes, of the Info buffer.
00104   @param  Info                  A pointer to callee allocated buffer that returns information about ModeNumber.
00105 
00106   @retval EFI_SUCCESS           Valid mode information was returned.
00107   @retval EFI_DEVICE_ERROR      A hardware error occurred trying to retrieve the video mode.
00108   @retval EFI_INVALID_PARAMETER ModeNumber is not valid.
00109 
00110 **/
00111 typedef
00112 EFI_STATUS
00113 (EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE)(
00114   IN  EFI_GRAPHICS_OUTPUT_PROTOCOL          *This,
00115   IN  UINT32                                ModeNumber,
00116   OUT UINTN                                 *SizeOfInfo,
00117   OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION  **Info
00118   );
00119 
00120 /**
00121   Set the video device into the specified mode and clears the visible portions of
00122   the output display to black.
00123 
00124   @param  This              The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.
00125   @param  ModeNumber        Abstraction that defines the current video mode.
00126 
00127   @retval EFI_SUCCESS       The graphics mode specified by ModeNumber was selected.
00128   @retval EFI_DEVICE_ERROR  The device had an error and could not complete the request.
00129   @retval EFI_UNSUPPORTED   ModeNumber is not supported by this device.
00130 
00131 **/
00132 typedef
00133 EFI_STATUS
00134 (EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE)(
00135   IN  EFI_GRAPHICS_OUTPUT_PROTOCOL *This,
00136   IN  UINT32                       ModeNumber
00137   );
00138 
00139 typedef struct {
00140   UINT8 Blue;
00141   UINT8 Green;
00142   UINT8 Red;
00143   UINT8 Reserved;
00144 } EFI_GRAPHICS_OUTPUT_BLT_PIXEL;
00145 
00146 typedef union {
00147   EFI_GRAPHICS_OUTPUT_BLT_PIXEL Pixel;
00148   UINT32                        Raw;
00149 } EFI_GRAPHICS_OUTPUT_BLT_PIXEL_UNION;
00150 
00151 ///
00152 /// actions for BltOperations
00153 ///
00154 typedef enum {
00155   ///
00156   /// Write data from the BltBuffer pixel (0, 0)
00157   /// directly to every pixel of the video display rectangle
00158   /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height).
00159   /// Only one pixel will be used from the BltBuffer. Delta is NOT used.
00160   ///
00161   EfiBltVideoFill,
00162 
00163   ///
00164   /// Read data from the video display rectangle
00165   /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) and place it in
00166   /// the BltBuffer rectangle (DestinationX, DestinationY )
00167   /// (DestinationX + Width, DestinationY + Height). If DestinationX or
00168   /// DestinationY is not zero then Delta must be set to the length in bytes
00169   /// of a row in the BltBuffer.
00170   ///
00171   EfiBltVideoToBltBuffer,
00172 
00173   ///
00174   /// Write data from the BltBuffer rectangle
00175   /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) directly to the
00176   /// video display rectangle (DestinationX, DestinationY)
00177   /// (DestinationX + Width, DestinationY + Height). If SourceX or SourceY is
00178   /// not zero then Delta must be set to the length in bytes of a row in the
00179   /// BltBuffer.
00180   ///
00181   EfiBltBufferToVideo,
00182 
00183   ///
00184   /// Copy from the video display rectangle (SourceX, SourceY)
00185   /// (SourceX + Width, SourceY + Height) to the video display rectangle
00186   /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height).
00187   /// The BltBuffer and Delta are not used in this mode.
00188   ///
00189   EfiBltVideoToVideo,
00190 
00191   EfiGraphicsOutputBltOperationMax
00192 } EFI_GRAPHICS_OUTPUT_BLT_OPERATION;
00193 
00194 /**
00195   Blt a rectangle of pixels on the graphics screen. Blt stands for BLock Transfer.
00196 
00197   @param  This         Protocol instance pointer.
00198   @param  BltBuffer    The data to transfer to the graphics screen.
00199                        Size is at least Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL).
00200   @param  BltOperation The operation to perform when copying BltBuffer on to the graphics screen.
00201   @param  SourceX      The X coordinate of source for the BltOperation.
00202   @param  SourceY      The Y coordinate of source for the BltOperation.
00203   @param  DestinationX The X coordinate of destination for the BltOperation.
00204   @param  DestinationY The Y coordinate of destination for the BltOperation.
00205   @param  Width        The width of a rectangle in the blt rectangle in pixels.
00206   @param  Height       The height of a rectangle in the blt rectangle in pixels.
00207   @param  Delta        Not used for EfiBltVideoFill or the EfiBltVideoToVideo operation.
00208                        If a Delta of zero is used, the entire BltBuffer is being operated on.
00209                        If a subrectangle of the BltBuffer is being used then Delta
00210                        represents the number of bytes in a row of the BltBuffer.
00211 
00212   @retval EFI_SUCCESS           BltBuffer was drawn to the graphics screen.
00213   @retval EFI_INVALID_PARAMETER BltOperation is not valid.
00214   @retval EFI_DEVICE_ERROR      The device had an error and could not complete the request.
00215 
00216 **/
00217 typedef
00218 EFI_STATUS
00219 (EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT)(
00220   IN  EFI_GRAPHICS_OUTPUT_PROTOCOL            *This,
00221   IN  EFI_GRAPHICS_OUTPUT_BLT_PIXEL           *BltBuffer,   OPTIONAL
00222   IN  EFI_GRAPHICS_OUTPUT_BLT_OPERATION       BltOperation,
00223   IN  UINTN                                   SourceX,
00224   IN  UINTN                                   SourceY,
00225   IN  UINTN                                   DestinationX,
00226   IN  UINTN                                   DestinationY,
00227   IN  UINTN                                   Width,
00228   IN  UINTN                                   Height,
00229   IN  UINTN                                   Delta         OPTIONAL
00230   );
00231 
00232 typedef struct {
00233   ///
00234   /// The number of modes supported by QueryMode() and SetMode().
00235   ///
00236   UINT32                                 MaxMode;
00237   ///
00238   /// Current Mode of the graphics device. Valid mode numbers are 0 to MaxMode -1.
00239   ///
00240   UINT32                                 Mode;
00241   ///
00242   /// Pointer to read-only EFI_GRAPHICS_OUTPUT_MODE_INFORMATION data.
00243   ///
00244   EFI_GRAPHICS_OUTPUT_MODE_INFORMATION   *Info;
00245   ///
00246   /// Size of Info structure in bytes.
00247   ///
00248   UINTN                                  SizeOfInfo;
00249   ///
00250   /// Base address of graphics linear frame buffer.
00251   /// Offset zero in FrameBufferBase represents the upper left pixel of the display.
00252   ///
00253   EFI_PHYSICAL_ADDRESS                   FrameBufferBase;
00254   ///
00255   /// Amount of frame buffer needed to support the active mode as defined by
00256   /// PixelsPerScanLine xVerticalResolution x PixelElementSize.
00257   ///
00258   UINTN                                  FrameBufferSize;
00259 } EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE;
00260 
00261 ///
00262 /// Provides a basic abstraction to set video modes and copy pixels to and from
00263 /// the graphics controller's frame buffer. The linear address of the hardware
00264 /// frame buffer is also exposed so software can write directly to the video hardware.
00265 ///
00266 struct _EFI_GRAPHICS_OUTPUT_PROTOCOL {
00267   EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE  QueryMode;
00268   EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE    SetMode;
00269   EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT         Blt;
00270   ///
00271   /// Pointer to EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE data.
00272   ///
00273   EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE        *Mode;
00274 };
00275 
00276 extern EFI_GUID gEfiGraphicsOutputProtocolGuid;
00277 
00278 #endif