EFI GRAPHICS OUTPUT PROTOCOL

From PhoenixWiki

Revision as of 00:06, 8 October 2009 by Tim Lewis (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Provides a basic abstraction to set video modes and copy pixels to and from the graphics controller’s frame buffer. The linear address of the hardware frame buffer is also exposed so software can write directly to the video hardware.

Contents

GUID

#define EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID \
  {0x9042a9de,0x23dc,0x4a38, \
  0x96,0xfb,0x7a,0xde,0xd0,0x80,0x51,0x6a}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(GraphicsOutput)

extern EFI_GUID gEfiGraphicsOutputProtocolGuid;
typedef struct EFI_GRAPHICS_OUTPUT_PROTCOL {
  EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE QueryMode;
  EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE   SetMode;
  EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT        Blt;
  EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE       *Mode;
} EFI_GRAPHICS_OUTPUT_PROTOCOL;

Members

Member Description
QueryMode Returns information for an available graphics mode that the graphics device and the set of active video output devices supports.
SetMode Set the video device into the specified mode and clears the visible portions of the output display to black.
Blt Software abstraction to draw on the video device’s frame buffer.
Mode Pointer to EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE data.

Description

The EFI_GRAPHICS_OUTPUT_PROTOCOL provides a software abstraction to allow pixels to be drawn directly to the frame buffer. The EFI_GRAPHICS_OUTPUT_PROTOCOL is designed to be lightweight and to support the basic needs of graphics output prior to Operating System boot.

QueryMode()

Returns information for an available graphics mode that the graphics device and the set of active video output devices supports.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_QUERY_MODE) (
  IN  EFI_GRAPHICS_OUTPUT_PROTOCOL         *This,
  IN  UINT32                               ModeNumber,
  OUT UINTN                                *SizeOfInfo
  OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION **Info
);

Parameters

Parameter Description
This The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.
ModeNumber The mode number to return information on. The current mode and valid modes are read-only values in the Mode structure of the EFI_GRAPHICS_OUTPUT_PROTOCOL.
SizeOfInfo A pointer to the size, in bytes, of the Info buffer.
Info A pointer to a callee allocated buffer that returns information about ModeNumber.

Description
The QueryMode() function returns information for an available graphics mode that the graphics device and the set of active video output devices supports. If ModeNumber is not between 0 and MaxMode – 1, then EFI_INVALID_PARAMETER is returned. MaxMode is available from the Mode structure of the EFI_GRAPHICS_OUTPUT_PROTOCOL.

The size of the Info structure should never be assumed and the value of SizeOfInfo is the only valid way to know the size of Info.

If the EFI_GRAPHICS_OUTPUT_PROTOCOL is installed on the handle that represents a single video output device, then the set of modes returned by this service is the subset of modes supported by both the graphics controller and the video output device.

If the EFI_GRAPHICS_OUTPUT_PROTOCOL is installed on the handle that represents a combination of video output devices, then the set of modes returned by this service is the subset of modes supported by the graphics controller and the all of the video output devices represented by the handle.

Status Codes Returned

Status Code Description
EFI_SUCCESS Valid mode information was returned.
EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the video mode.
EFI_INVALID_PARAMETER ModeNumber is not valid.

SetMode()

Set the video device into the specified mode and clears the visible portions of the output display to black.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_SET_MODE) (
  IN EFI_GRAPHICS_OUTPUT_PROTOCOL *This,
  IN UINT32                       ModeNumber
);

Parameters

Parameter Description
This The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.
ModeNumber Abstraction that defines the current video mode. The current mode and valid modes are read-only values in the Mode structure of the EFI_GRAPHICS_OUTPUT_PROTOCOL.

Description
This SetMode() function sets the graphics device and the set of active video output devices to the video mode specified by ModeNumber. If ModeNumber is not supported EFI_UNSUPPORTED is returned.

If a device error occurs while attempting to set the video mode, then EFI_DEVICE_ERROR is returned. Otherwise, the graphics device is set to the requested geometry, the set of active output devices are set to the requested geometry, the visible portion of the hardware frame buffer is cleared to black, and EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The graphics mode specified by ModeNumber was selected.
EFI_DEVICE_ERROR The device had an error and could not complete the request.
EFI_UNSUPPORTED ModeNumber is not supported by this device.

Blt()

Blt a rectangle of pixels on the graphics screen. Blt stands for BLock Transfer.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GRAPHICS_OUTPUT_PROTOCOL_BLT) (
  IN     EFI_GRAPHICS_OUTPUT_PROTOCOL      *This,
  IN OUT EFI_GRAPHICS_OUTPUT_BLT_PIXEL     *BltBuffer, OPTIONAL
  IN     EFI_GRAPHICS_OUTPUT_BLT_OPERATION BltOperation,
  IN     UINTN                             SourceX,
  IN     UINTN                             SourceY,
  IN     UINTN                             DestinationX,
  IN     UINTN                             DestinationY,
  IN     UINTN                             Width,
  IN     UINTN                             Height,
  IN     UINTN                             Delta OPTIONAL
);

Parameters

Parameter Description
This The EFI_GRAPHICS_OUTPUT_PROTOCOL instance.
BltBuffer The data to transfer to the graphics screen. Size is at least Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL).
BltOperation The operation to perform when copying BltBuffer on to the graphics screen.
SourceX The X coordinate of the source for the BltOperation. The origin of the screen is 0, 0 and that is the upper left-hand corner of the screen.
SourceY The Y coordinate of the source for the BltOperation. The origin of the screen is 0, 0 and that is the upper left-hand corner of the screen.
DestinationX The X coordinate of the destination for the BltOperation. The origin of the screen is 0, 0 and that is the upper left-hand corner of the screen.
DestinationY The Y coordinate of the destination for the BltOperation. The origin of the screen is 0, 0 and that is the upper left-hand corner of the screen.
Width The width of a rectangle in the blt rectangle in pixels. Each pixel is represented by an EFI_GRAPHICS_OUTPUT_BLT_PIXEL element.
Height The height of a rectangle in the blt rectangle in pixels. Each pixel is represented by an EFI_GRAPHICS_OUTPUT_BLT_PIXEL element.
Delta Not used for EfiBltVideoFill or the EfiBltVideoToVideo operation. If a Delta of zero is used, the entire BltBuffer is being operated on. If a subrectangle of the BltBuffer is being used then Delta represents the number of bytes in a row of the BltBuffer.

Description
The Blt() function is used to draw the BltBuffer rectangle onto the video screen.

The BltBuffer represents a rectangle of Height by Width pixels that will be drawn on the graphics screen using the operation specified by BltOperation. The Delta value can be used to enable the BltOperation to be performed on a sub-rectangle of the BltBuffer.

The table below describes the BltOperations that are supported on rectangles. Rectangles have coordinates (left, upper) (right, bottom):

Blt Operation Operation
EfiBltVideoFill Write data from the BltBuffer pixel (0,0) directly to every pixel of the video display rectangle (DestinationX, DestinationY)(DestinationX + Width, DestinationY + Height). Only one pixel will be used from the BltBuffer. Delta is NOT used.
EfiBltVideoToBltBuffer Read data from the video display rectangle (SourceX, SourceY)(SourceX + Width, SourceY + Height) and place it in the BltBuffer rectangle (DestinationX, DestinationY ) (DestinationX + Width, DestinationY + Height). If DestinationX or DestinationY is not zero then Delta must be set to the length in bytes of a row in the BltBuffer.
EfiBltBufferToVideo Write data from the BltBuffer rectangle (SourceX, SourceY)(SourceX + Width, SourceY + Height) directly to the video display rectangle (DestinationX, DestinationY)(DestinationX + Width, DestinationY + Height). If SourceX or SourceY is not zero then Delta must be set to the length in bytes of a row in the BltBuffer.
EfiBltVideoToVideo Copy from the video display rectangle (SourceX, SourceY)(SourceX + Width, SourceY + Height) to the video display rectangle (X, Y) (X + Width, Y + Height). The BltBuffer and Delta are not used in this mode. There is no limitation on the overlapping of the source and destination rectangles.

Status Codes Returned

Status Code Description
EFI_SUCCESS BltBuffer was drawn to the graphics screen.
EFI_INVALID_PARAMETER BltOperation is not valid.
EFI_DEVICE_ERROR The device had an error and could not complete the request.

Copyright (C) 2008-2009 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools