Contents

• Public Types
• Public Functions
• Static Public Members
• Protected Functions
• Protected Variables
• Related Non-Members
• Detailed Description
• Framebuffer Management
• Palette Management
• Drawing on Screen
• Properties
• Subclassing and Initial Values

Detailed Description

TheQScreen class is a base class for screen drivers in Qt for Embedded Linux.

Note that this class is only available inQt for Embedded Linux.

Qt for Embedded Linux provides ready-made drivers for several screen protocols, see thedisplay management documentation for details. Custom screen drivers can be implemented by subclassing theQScreen class and creating a screen driver plugin (derived fromQScreenDriverPlugin). The default implementation of theQScreenDriverFactory class will automatically detect the plugin, and load the driver into the server application at run-time using Qt'splugin system.

When rendering, the default behavior is for each client to render its widgets as well as its decorations into memory, while the server copies the memory content to the device's framebuffer using the screen driver. See theQt for Embedded Linux Architecture overview for details (note that it is possible for the clients to manipulate and control the underlying hardware directly as well).

Starting with Qt 4.2, it is also possible to add an accelerated graphics driver to take advantage of available hardware resources. See theAdding an Accelerated Graphics Driver to Qt for Embedded Linux documentation for details.

Framebuffer Management

When aQt for Embedded Linux application starts running, it calls the screen driver'sconnect() function to map the framebuffer and the accelerated drivers that the graphics card control registers. Theconnect() function should then read out the parameters of the framebuffer and use them as required to set this class's protected variables.

TheinitDevice() function can be reimplemented to initialize the graphics card. Note, however, thatconnect() is calledbefore theinitDevice() function, so, for some hardware configurations, some of the initialization that would normally be done in theinitDevice() function might have to be done in theconnect() function.

Likewise, just before aQt for Embedded Linux application exits, it calls the screen driver'sdisconnect() function. The server application will in addition call theshutdownDevice() function before it callsdisconnect(). Note that the default implementation of theshutdownDevice() function only hides the mouse cursor.

QScreen also provides thesave() andrestore() functions, making it possible to save and restore the state of the graphics card. Note that the default implementations do nothing. Hardware screen drivers should reimplement these functions to save (and restore) its registers, enabling switching between virtual consoles.

In addition, you can use thebase() function to retrieve a pointer to the beginning of the framebuffer, and theregion() function to retrieve the framebuffer's region. Use theonCard() function to determine whether the framebuffer is within the graphics card's memory, and thetotalSize() function to determine the size of the available graphics card memory (including the screen). Finally, you can use theoffset() function to retrieve the offset between the framebuffer's coordinates and the application's coordinate system.

Palette Management

QScreen provides several functions to retrieve information about the color palette: Theclut() function returns a pointer to the color lookup table (i.e. its color palette). Use thecolorCount() function to determine the number of entries in this table, and thealloc() function to retrieve the palette index of the color that is the closest match to a given RGB value.

To determine if the screen driver supports a given color depth, use thesupportsDepth() function that returns true of the specified depth is supported.

Drawing on Screen

When a screen update is required, theQt for Embedded Linux server runs through all the top-level windows that intersect with the region that is about to be updated, and ensures that the associated clients have updated their memory buffer. Then the server calls theexposeRegion() function that composes the window surfaces and copies the content of memory to screen by calling theblit() andsolidFill() functions.

Theblit() function copies a given region in a given image to a specified point using device coordinates, while thesolidFill() function fills the given region of the screen with the specified color. Note that normally there is no need to call either of these functions explicitly.

In addition,QScreen provides theblank() function that can be reimplemented to prevent any contents from being displayed on the screen, and thesetDirty() function that can be reimplemented to indicate that a given rectangle of the screen has been altered. Note that the default implementations of these functions do nothing.

Reimplement themapFromDevice() andmapToDevice() functions to map objects from the framebuffer coordinate system to the coordinate space used by the application, and vice versa. Be aware that the default implementations simply return the given objects as they are.

Properties

Subclassing and Initial Values

You need to set the following members when implementing a subclass ofQScreen:

The logical screen values are the same as the real screen values unless the screen is transformed in some way; e.g., rotated.

See also theAccelerated Graphics Driver Example for an example that shows how to initialize these values.

Member Type Documentation

enum QScreen::ClassId

This enum defines the class identifiers for the known screen subclasses.

See alsoclassId().

enum QScreen::PixelType

This enum describes the pixel storage format of the screen, i.e. the order of the red (R), green (G) and blue (B) components of a pixel.

See alsopixelType().

Member Function Documentation

QScreen::QScreen(int display_id,ClassId classId)

Constructs a new screen driver.

Thedisplay_id identifies theQt for Embedded Linux server to connect to. TheclassId specifies the class identifier.

This function was introduced in Qt 4.4.

QScreen::QScreen(int displayId)

Constructs a new screen driver.

ThedisplayId identifies theQt for Embedded Linux server to connect to.

[virtual]QScreen::~QScreen()

Destroys this screen driver.

[virtual]int QScreen::alloc(unsignedint red,unsignedint green,unsignedint blue)

Returns the index in the screen's palette which is the closest match to the given RGB value (red,green,blue).

Note that this function only apply in paletted modes like 8-bit, i.e. in modes where only the palette indexes (and not the actual color values) are stored in memory.

See alsoclut() andcolorCount().

uchar * QScreen::base() const

Returns a pointer to the beginning of the framebuffer.

See alsoonCard(),region(), andtotalSize().

[virtual]void QScreen::blank(bool on)

Prevents the screen driver form displaying any content on the screen.

Note that the default implementation does nothing.

Reimplement this function to prevent the screen driver from displaying any contents on the screen ifon is true; otherwise the contents is expected to be shown.

See alsoblit().

[virtual]void QScreen::blit(constQImage & image, constQPoint & topLeft, constQRegion & region)

Copies the givenregion in the givenimage to the point specified bytopLeft using device coordinates.

This function is called from theexposeRegion() function; it is not intended to be called explicitly.

Reimplement this function to make use ofaccelerated hardware. Note that this function must be reimplemented if the framebuffer format is not supported byQt for Embedded Linux (See theDisplay Management documentation for more details).

See alsoexposeRegion(),solidFill(), andblank().

ClassId QScreen::classId() const

Returns the class identifier for the screen object.

This function was introduced in Qt 4.4.

QRgb * QScreen::clut()

Returns a pointer to the screen's color lookup table (i.e. its color palette).

Note that this function only apply in paletted modes like 8-bit, i.e. in modes where only the palette indexes (and not the actual color values) are stored in memory.

See alsoalloc(),depth(), andcolorCount().

int QScreen::colorCount()

Returns the number of entries in the screen's color lookup table (i.e. its color palette). A pointer to the color table can be retrieved using theclut() function.

This function was introduced in Qt 4.6.

See alsoclut() andalloc().

[pure virtual]bool QScreen::connect(constQString & displaySpec)

This function is called by everyQt for Embedded Linux application on startup, and must be implemented to map in the framebuffer and the accelerated drivers that the graphics card control registers. Note that connect must be calledbefore theinitDevice() function.

Ensure that true is returned if a connection to the screen device is made. Otherwise, return false. Upon making the connection, the function should read out the parameters of the framebuffer and use them as required to set this class's protected variables.

ThedisplaySpec argument is passed by theQWS_DISPLAY environment variable or the -display command line parameter, and has the following syntax:

[screen driver][:driver specific options][:display number]

For example, to use the mach64 driver on fb1 as display 2:

Mach64:/dev/fb1:2

SeeQt for Embedded Linux Display Management for more details.

See alsodisconnect(),initDevice(), andRunning Qt for Embedded Linux Applications.

[virtual]QWSWindowSurface * QScreen::createSurface(constQString & key) const

Creates and returns a new window surface matching the givenkey.

The server application will call this function whenever it needs to create a server side representation of a window, e.g. when copying the content of memory to the screen using the screen driver.

Note that this function must be reimplemented when adding an accelerated graphics driver. See theAdding an Accelerated Graphics Driver documentation for details.

This function was introduced in Qt 4.2.

See alsoQt for Embedded Linux Architecture.

[virtual]QWSWindowSurface * QScreen::createSurface(QWidget * widget) const

This is an overloaded function.

Creates and returns a new window surface for the givenwidget.

int QScreen::depth() const

Returns the depth of the framebuffer, in bits per pixel.

Note that the returned depth is the number of bits each pixel fills rather than the number of significant bits, so 24bpp and 32bpp express the same range of colors (8 bits of red, green and blue).

See alsoclut() andpixmapDepth().

int QScreen::deviceHeight() const

Returns the full height of the framebuffer device in pixels.

Note that the returned height can differ from the height whichQt for Embedded Linux will actually use, that is if the display is centered within the framebuffer.

See alsoheight(),physicalHeight(), anddeviceWidth().

int QScreen::deviceWidth() const

Returns the physical width of the framebuffer device in pixels.

Note that the returned width can differ from the width whichQt for Embedded Linux will actually use, that is if the display is centered within the framebuffer.

See alsowidth(),physicalWidth(), anddeviceHeight().

[pure virtual]void QScreen::disconnect()

This function is called by everyQt for Embedded Linux application before exiting, and must be implemented to unmap the framebuffer. Note that a server application will call theshutdownDevice() function prior to this function.

See alsoconnect(),shutdownDevice(), andRunning Qt for Embedded Linux Applications.

[virtual]void QScreen::exposeRegion(QRegion region,int windowIndex)

This function is called by theQt for Embedded Linux server whenever a screen update is required.region is the area on the screen that must be updated, andwindowIndex is the index intoQWSServer::clientWindows() of the window that required the update.QWSWindow::state() gives more information about the cause.

The default implementation composes the affected windows and paints the givenregion on screen by calling theblit() andsolidFill() functions

This function can be reimplemented to perform composition in hardware, or to perform transition effects. For simpler hardware acceleration, or to interface with this is typically done by reimplementing theblit() andsolidFill() functions instead.

Note that there is no need to call this function explicitly.

See alsoblit(),solidFill(), andblank().

int QScreen::height() const

Returns the logical height of the framebuffer in pixels.

See alsodeviceHeight(),physicalHeight(), andwidth().

[pure virtual]bool QScreen::initDevice()

This function is called by theQt for Embedded Linux server to initialize the framebuffer. Note that a server application will call theconnect() function prior to this function.

Implement this function to make accelerated drivers set up the graphics card. Return true to indicate success and false to indicate failure.

See alsoshutdownDevice() andconnect().

[static]QScreen * QScreen::instance()

Returns a pointer to the application'sQScreen instance.

If this screen consists of several subscreens, operations to the returned instance will affect all its subscreens. Use the subscreens() function to retrieve access to a particular subscreen.

See alsosubScreens() andsubScreenIndexAt().

[virtual]bool QScreen::isInterlaced() const

Returns true if the display is interlaced (i.e. is displaying images progressively like a television screen); otherwise returns false.

If the display is interlaced, the drawing is altered to look better.

See alsoisTransformed() andlinestep().

[virtual]bool QScreen::isTransformed() const

Returns true if the screen is transformed (for instance, rotated 90 degrees); otherwise returns false.

See alsotransformOrientation() andisInterlaced().

int QScreen::linestep() const

Returns the length of each scanline of the framebuffer in bytes.

See alsoisInterlaced().

[virtual]QSize QScreen::mapFromDevice(constQSize & size) const

Maps the givensize from the framebuffer coordinate system to the coordinate space used by the application. Note that the default implementation simply returns the givensize as it is.

Reimplement this function to use the given device's coordinate system when mapping.

See alsomapToDevice().

[virtual]QPoint QScreen::mapFromDevice(constQPoint & point, constQSize & screenSize) const

This is an overloaded function.

Maps the givenpoint from the framebuffer coordinate system to the coordinate space used by the application, passing the device'sscreenSize as argument. Note that the default implementation simply returns the givenpoint as it is.

[virtual]QRect QScreen::mapFromDevice(constQRect & rectangle, constQSize & screenSize) const

This is an overloaded function.

Maps the givenrectangle from the framebuffer coordinate system to the coordinate space used by the application, passing the device'sscreenSize as argument. Note that the default implementation simply returns the givenrectangle as it is.

[virtual]QImage QScreen::mapFromDevice(constQImage & image) const

This is an overloaded function.

Maps the givenimage from the framebuffer coordinate system to the coordinate space used by the application. Note that the default implementation simply returns the givenimage as it is.

[virtual]QRegion QScreen::mapFromDevice(constQRegion & region, constQSize & screenSize) const

This is an overloaded function.

Maps the givenregion from the framebuffer coordinate system to the coordinate space used by the application, passing the device'sscreenSize as argument. Note that the default implementation simply returns the givenregion as it is.

[virtual]QSize QScreen::mapToDevice(constQSize & size) const

Maps the givensize from the coordinate space used by the application to the framebuffer coordinate system. Note that the default implementation simply returns the givensize as it is.

Reimplement this function to use the given device's coordinate system when mapping.

See alsomapFromDevice().

[virtual]QPoint QScreen::mapToDevice(constQPoint & point, constQSize & screenSize) const

This is an overloaded function.

Maps the givenpoint from the coordinate space used by the application to the framebuffer coordinate system, passing the device'sscreenSize as argument. Note that the default implementation returns the givenpoint as it is.

[virtual]QRect QScreen::mapToDevice(constQRect & rectangle, constQSize & screenSize) const

This is an overloaded function.

Maps the givenrectangle from the coordinate space used by the application to the framebuffer coordinate system, passing the device'sscreenSize as argument. Note that the default implementation returns the givenrectangle as it is.

[virtual]QImage QScreen::mapToDevice(constQImage & image) const

This is an overloaded function.

Maps the givenimage from the coordinate space used by the application to the framebuffer coordinate system. Note that the default implementation returns the givenimage as it is.

[virtual]QRegion QScreen::mapToDevice(constQRegion & region, constQSize & screenSize) const

This is an overloaded function.

Maps the givenregion from the coordinate space used by the application to the framebuffer coordinate system, passing the device'sscreenSize as argument. Note that the default implementation returns the givenregion as it is.

QPoint QScreen::offset() const

Returns the logical offset of the screen, i.e., the offset between (0,0) in screen coordinates and the application coordinate system.

This function was introduced in Qt 4.2.

[virtual]bool QScreen::onCard(constunsignedchar * buffer) const

Returns true if the specifiedbuffer is within the graphics card's memory; otherwise returns false (i.e. if it's in main RAM).

See alsobase() andtotalSize().

[virtual]bool QScreen::onCard(constunsignedchar * buffer,ulong & offset) const

This is an overloaded function.

If the specifiedbuffer is within the graphics card's memory, this function stores the offset from the start of graphics card memory (in bytes), in the location specified by theoffset parameter.

int QScreen::physicalHeight() const

Returns the physical height of the screen in millimeters.

This function was introduced in Qt 4.2.

See alsoheight(),deviceHeight(), andphysicalWidth().

int QScreen::physicalWidth() const

Returns the physical width of the screen in millimeters.

This function was introduced in Qt 4.2.

See alsowidth(),deviceWidth(), andphysicalHeight().

QImage::Format QScreen::pixelFormat() const

Returns the pixel format of the screen, orQImage::Format_Invalid if the pixel format is not a supported image format.

See alsosetPixelFormat().

PixelType QScreen::pixelType() const

Returns the pixel storage format of the screen.

[virtual]int QScreen::pixmapDepth() const

Returns the preferred depth for pixmaps, in bits per pixel.

See alsodepth().

[virtual]int QScreen::pixmapLinestepAlignment()

Returns the value (in bits) to which individual scanlines of pixmaps held in the graphics card's memory, should be aligned.

Note that the default implementation returns 64; reimplement this function to override the return value, e.g., when implementing an accelerated driver (see theAdding an Accelerated Graphics Driver documentation for details).

See alsopixmapOffsetAlignment().

[virtual]int QScreen::pixmapOffsetAlignment()

Returns the value (in bits) to which the start address of pixmaps held in the graphics card's memory, should be aligned.

Note that the default implementation returns 64; reimplement this function to override the return value, e.g., when implementing an accelerated driver (see theAdding an Accelerated Graphics Driver documentation for details).

See alsopixmapLinestepAlignment().

[virtual]QRegion QScreen::region() const

Returns the region covered by this screen driver.

This function was introduced in Qt 4.2.

See alsobase() andscreenSize().

[virtual]void QScreen::restore()

Restores the previously saved state of the graphics card.

For example, hardware screen drivers should reimplement thesave() and restore() functions to save and restore its registers, enabling swintching between virtual consoles.

Note that the default implementation does nothing.

See alsosave().

[virtual]void QScreen::save()

Saves the current state of the graphics card.

For example, hardware screen drivers should reimplement the save() andrestore() functions to save and restore its registers, enabling swintching between virtual consoles.

Note that the default implementation does nothing.

See alsorestore().

int QScreen::screenSize() const

Returns the size of the screen in bytes.

The screen size is always located at the beginning of framebuffer memory, i.e. it can also be retrieved using thebase() function.

See alsobase() andregion().

[virtual]void QScreen::setDirty(constQRect & rectangle)

Marks the givenrectangle as dirty.

Note that the default implementation does nothing; reimplement this function to indicate that the givenrectangle has been altered.

[pure virtual]void QScreen::setMode(int width,int height,int depth)

Implement this function to reset the framebuffer's resolution (width andheight) and bitdepth.

After the resolution has been set, existing paint engines will be invalid and the framebuffer should be completely redrawn. In a multiple-process situation, all other applications must be notified to reset their mode and update themselves accordingly.

[protected]void QScreen::setPixelFormat(QImage::Format format)

Sets the screen's pixel format toformat.

See alsopixelFormat().

[virtual]void QScreen::shutdownDevice()

This function is called by theQt for Embedded Linux server before it calls thedisconnect() function when exiting.

Note that the default implementation only hides the mouse cursor; reimplement this function to do the necessary graphics card specific cleanup.

See alsoinitDevice() anddisconnect().

[virtual]void QScreen::solidFill(constQColor & color, constQRegion & region)

Fills the givenregion of the screen with the specifiedcolor.

This function is called from theexposeRegion() function; it is not intended to be called explicitly.

Reimplement this function to make use ofaccelerated hardware. Note that this function must be reimplemented if the framebuffer format is not supported byQt for Embedded Linux (See theDisplay Management documentation for more details).

See alsoexposeRegion(),blit(), andblank().

int QScreen::subScreenIndexAt(constQPoint & position) const

Returns the index of the subscreen at the givenposition; returns -1 if no screen is found.

The index identifies the subscreen in the list of pointers returned by thesubScreens() function.

This function was introduced in Qt 4.2.

See alsoinstance() andsubScreens().

[virtual]QList<QScreen *> QScreen::subScreens() const

Returns a list of this screen's subscreens. Use thesubScreenIndexAt() function to retrieve the index of a screen at a given position.

Note that ifthis screen consists of several subscreens, operations tothis instance will affect all subscreens by default.

This function was introduced in Qt 4.2.

See alsoinstance() andsubScreenIndexAt().

[virtual]bool QScreen::supportsDepth(int depth) const

Returns true if the screen supports the specified colordepth; otherwise returns false.

See alsoclut().

int QScreen::totalSize() const

Returns the size of the available graphics card memory (including the screen) in bytes.

See alsoonCard().

[virtual]int QScreen::transformOrientation() const

Returns the current rotation as an integer value.

Note that the default implementation returns 0; reimplement this function to override this value.

See alsoisTransformed().

int QScreen::width() const

Returns the logical width of the framebuffer in pixels.

See alsodeviceWidth(),physicalWidth(), andheight().

Member Variable Documentation

int QScreen::d

This variable holds the pixel depth.

This is the number of significant bits used to set a pixel color. This variablemust be initialized by a subclass.

uchar * QScreen::data

This variable holds points to the first visible pixel in the frame buffer.

You must initialize this variable if you are using the default implementation of non-buffered paintingQt::WA_PaintOnScreen,QPixmap::grabWindow() orQDirectPainter::frameBuffer(). If you initialize this variable, you must also initializeQScreen::size andQScreen::mapsize.

See alsoQScreen::size andQScreen::mapsize.

int QScreen::dh

This variable holds the device height.

This is the number of pixels in a column of the physical screen. Itmust be initialized by a subclass. Normally, it should be set to the logical heightQScreen::h, but it might be different, e.g., if you are doing rotations in software.

See alsoQScreen::h.

int QScreen::dw

This variable holds the device width.

This is the number of pixels in a row of the physical screen. Itmust be initialized by a subclass. Normally, it should be set to the logical widthQScreen::w, but it might be different, e.g., if you are doing rotations in software.

See alsoQScreen::w.

bool QScreen::grayscale

This variable holds the gray scale screen mode flag.

Set this variable to true in a subclass, if you are using a grayscale screen mode. e.g., in an 8-bit mode where you don't want to use the palette, but you want to use the grayscales.

int QScreen::h

This variable holds the logical height of the screen.

This variablemust be initialized by a subclass.

int QScreen::lstep

This variable holds the number of bytes representing a line in the frame buffer.

i.e.,line step.data[lstep * 2] is the address of the first visible pixel in the third line of the frame buffer.

See alsodata.

int QScreen::mapsize

This variable holds the total number of bytes in the frame buffer.

This is the total number of bytes in the block pointed to by theQScreen::data pointer. You must initialize this variable if you initialize theQScreen::data pointer.

See alsoQScreen::data andQScreen::size.

int QScreen::physHeight

This variable holds the physical height of the screen in millimeters.

Currently, this variable is used when calculating the screen DPI, which in turn is used when deciding the actual font size Qt is using.

int QScreen::physWidth

This variable holds the physical width of the screen in millimeters.

Currently, this variable is used when calculating the screen DPI, which in turn is used when deciding the actual font size Qt is using.

PixelType QScreen::pixeltype

This variable holds set to BGRPixel.

Set this variable toBGRPixel in a subclass, if the screen pixel format is a BGR type and you have usedsetPixelFormat() to set the pixel format to the corresponding RGB format. e.g., you have set the pixel format toQImage::Format_RGB555, but your screen really uses BGR, not RGB.

QRgb QScreen::screenclut[256]

This variable holds the color table.

Initialize this variable in a subclass using a paletted screen mode, and initialize its partner,QScreen::screencols.

See alsoscreencols.

int QScreen::screencols

This variable holds the number of entries in the color table.

Initialize this variable in a subclass using a paletted screen mode, and initialize its partner,QScreen::screenclut.

See alsoscreenclut.

int QScreen::size

This variable holds the number of bytes in the visible region of the frame buffer.

This is the number of bytes in the visible part of the block pointed to by theQScreen::data pointer. You must initialize this variable if you initialize theQScreen::data pointer.

See alsoQScreen::data andQScreen::mapsize.

int QScreen::w

This variable holds the logical width of the screen.

This variablemust be initialized by a subclass.

Related Non-Members

[static]void QWSDisplay::setTransformation(int transformation,int screenNo = -1)

Here it is.transformation andscreenNo