📄 framebuf.html
字号:
<!-- Copyright (C) 2009 Free Software Foundation, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Overview</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="Framebuffer Support"
HREF="io-framebuf.html"><LINK
REL="PREVIOUS"
TITLE="Framebuffer Support"
HREF="io-framebuf.html"><LINK
REL="NEXT"
TITLE="Framebuffer Parameters"
HREF="framebuf-parameters.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="io-framebuf.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="framebuf-parameters.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="FRAMEBUF"
></A
>Overview</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9975"
></A
><H2
>Name</H2
>Overview -- eCos Support for Framebuffer Devices</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-DESCRIPTION"
></A
><H2
>Description</H2
><P
>Framebuffer devices are the most common way for a computer system to
display graphical output to users. There are immense variations in the
implementations of such devices. <CODE
CLASS="VARNAME"
>CYGPKG_IO_FRAMEBUF</CODE
>
provides an abstraction layer for use by application code and other
packages. It defines an API for manipulating framebuffers, mapping
this API on to functionality provided by the appropriate device
driver. It also defines the interface which such device drivers should
implement. For simple hardware it provides default implementations of
much of this interface, greatly reducing the effort needed to write a
device driver.
</P
><P
>This package does not constitute a graphics library. It does not
implement functionality like drawing text or arbitrary lines, let
alone any kind of windowing system. Instead it operates at the lower
level of individual pixels and blocks of pixels, in addition to
control operations such as hardware initialization. Some applications
may use the framebuffer API directly. Others will instead use a
higher-level graphics library, and it is that library which uses the
framebuffer API.
</P
><P
>It is assumed that users are already familiar with the fundamentals of
computer graphics, and no attempt is made here to explain terms like
display depth, palette or pixel.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>This package is work-in-progress. The support for 1bpp, 2bpp and 4bpp
display depths is incomplete. For double-buffered displays the code
does not yet maintain a bounding box of the updated parts of the
display. The package has also been designed to allow for
<A
HREF="framebuf-porting.html#FRAMEBUF-PORTING-EXPANSION"
>expansion</A
> with new
functionality.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-CONFIGURATION"
></A
><H2
>Configuration</H2
><P
><CODE
CLASS="VARNAME"
>CYGPKG_IO_FRAMEBUF</CODE
> only contains
hardware-independent code. It should be complemented by one or more
framebuffer device drivers appropriate for the target platform. These
drivers may be specific to the platform, or they may be more generic
with platform-specific details such as the framebuffer memory base
address provided by the platform HAL. When creating a configuration
for a given target the device driver(s) will always be included
automatically (assuming one has been written or ported). However by
default this driver will be inactive and will not get built, so does
not add any unnecessary size overhead for applications which do not
require graphics. To activate the device driver
<CODE
CLASS="VARNAME"
>CYGPKG_IO_FRAMEBUF</CODE
> must be added explicitly to the
configuration, for example using
<B
CLASS="COMMAND"
>ecosconfig add framebuf</B
>. After this the
full framebuffer API will be available to other packages and to
application code.
</P
><P
>This package contains very few configuration options. Instead it is
left to device drivers or higher-level code to provide appropriate
configurability. One option,
<CODE
CLASS="VARNAME"
>CYGFUN_IO_FRAMEBUF_INSTALL_DEFAULT_PALETTE</CODE
>, relates
to the initialization of <A
HREF="framebuf-colour.html#FRAMEBUF-COLOUR-PALETTE"
>paletted displays</A
>.
</P
><P
>There are a number of calculated and inferred configuration options
and a number of interfaces. These provide information such as whether
or not there is a backlight. The most important one is
<CODE
CLASS="VARNAME"
>CYGDAT_IO_FRAMEBUF_DEVICES</CODE
>, which holds a list of
framebuffer identifiers for use with the <A
HREF="framebuf.html#FRAMEBUF-API"
>macro-based API</A
>. If there is a single
framebuffer device driver which supports one display in either
landscape or portrait mode, the configuration option may hold a value
like <TT
CLASS="LITERAL"
> 240x320x8 320x240x8r90</TT
>.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-API"
></A
><H2
>Application Programmer Interfaces</H2
><P
>Framebuffer devices require a difficult choice between flexibility and
performance. On the one hand the API should be able to support
multiple devices driving separate displays, or a single device
operating in different modes at different times. On the other hand
graphics tends to involve very large amounts of I/O: even something as
simple as drawing a background image can involve setting many
thousands of pixels. Efficiency requires avoiding all possible
overheads including function calls. Instead the API should make
extensive use of macros or inline functions. Ideally details of the
framebuffer device such as the stride would be known constants at
compile-time, giving the compiler as much opportunity as possible to
optimize the code. Clearly this is difficult if multiple framebuffer
devices are in use or if the device mode may get changed at run-time.
</P
><P
>To meet the conflicting requirements the generic framebuffer package
provides two APIs: a fast macro API which requires selecting a single
framebuffer device at compile or configure time; and a slower function
API without this limitation. The two are very similar, for example:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#include <cyg/io/framebuf.h>
void
clear_screen(cyg_fb* fb, cyg_fb_colour colour)
{
cyg_fb_fill_block(fb, 0, 0,
fb->fb_width, fb->fb_height,
colour);
}
</PRE
></TD
></TR
></TABLE
><P
>or the equivalent macro version:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#include <cyg/io/framebuf.h>
#define FRAMEBUF 240x320x8
void
clear_screen(cyg_fb_colour colour)
{
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
colour);
}
</PRE
></TD
></TR
></TABLE
><P
>The function-based API works in terms of
<CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structures, containing all the
information needed to manipulate the device. Each framebuffer device
driver will export one or more of these structures, for example
<CODE
CLASS="VARNAME"
>cyg_alaia_fb_240x320x8</CODE
>, and the driver
documentation should list the variable names. The macro API works in
terms of identifiers such as <TT
CLASS="LITERAL"
>240x320x8</TT
>, and by a
series of substitutions the main macro gets expanded to the
appropriate device-specific code, usually inline. Again the device
driver documentation should list the supported identifiers. In
addition the configuration option
<CODE
CLASS="VARNAME"
>CYGDAT_IO_FRAMEBUF_DEVICES</CODE
> will contain the full
list. By convention the identifier will be specified by a
<TT
CLASS="LITERAL"
>#define</TT
>'d symbol such as
<CODE
CLASS="VARNAME"
>FRAMEBUF</CODE
>, or in the case of graphics libraries by a
configuration option.
</P
><P
>If a platform has multiple framebuffer devices connected to different
displays then there will be separate <CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
>
structures and macro identifiers for each one. In addition some
devices can operate in multiple modes. For example a PC VGA card can
operate in a monochome 640x480 mode, an 8bpp 320x200 mode, and many
other modes, but only one of these can be active at a time. The
different modes are also represented by different
<CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structures and identifiers,
effectively treating the modes as separate devices. It is the
responsibility of higher-level code to ensure that only one mode is in
use at a time.
</P
><P
>It is possible to use the macro API with more than one device,
basically by compiling the code twice with different values of
<CODE
CLASS="VARNAME"
>FRAMEBUF</CODE
>, taking appropriate care to avoid
identifier name clashes. This gives the higher performance of the
macros at the cost of increased code size.
</P
><P
>All of the framebuffer API, including exports of the device-specific
<CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structures, is available through a
single header file <TT
CLASS="FILENAME"
><cyg/io/framebuf.h></TT
>. The
API follows a number of conventions. Coordinates (0,0) correspond to
the top-left corner of the display. All functions and macros which
take a pair of coordinates have x first, y second. For block
operations these coordinates are followed by width, then height.
Coordinates and dimensions use <SPAN
CLASS="TYPE"
>cyg_ucount16</SPAN
> variables,
which for any processor should be the most efficient unsigned data
type with at least 16 bits - usually plain unsigned integers. Colours
are identified by <SPAN
CLASS="TYPE"
>cyg_fb_colour</SPAN
> variables, again usually
unsigned integers.
</P
><P
>To allow for the different variants of the English language, the API
allows for a number of alternate spellings. Colour and color can be
used interchangeably, so there are data types
<SPAN
CLASS="TYPE"
>cyg_fb_colour</SPAN
> and <SPAN
CLASS="TYPE"
>cyg_fb_color</SPAN
>, and
functions <CODE
CLASS="FUNCTION"
>cyg_fb_make_colour</CODE
> and
<CODE
CLASS="FUNCTION"
>cyg_fb_make_color</CODE
>. Similarly gray is accepted as
a variant of grey so the predefined colours
<TT
CLASS="LITERAL"
>CYG_FB_DEFAULT_PALETTE_LIGHTGREY</TT
> and
<TT
CLASS="LITERAL"
>CYG_FB_DEFAULT_PALETTE_LIGHTGRAY</TT
> are equivalent.
</P
><P
>The API is split into the following categories:
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><A
HREF="framebuf-parameters.html"
>parameters</A
></DT
><DD
><P
>getting information about a given framebuffer device such as width,
height and depth. Colours management is complicated so has its own
<A
HREF="framebuf-colour.html"
>category</A
>.
</P
></DD
><DT
><A
HREF="framebuf-control.html"
>control</A
></DT
><DD
><P
>operations such as switching the display on and off, and more
device-specific ones such as manipulating the backlight.
</P
></DD
><DT
><A
HREF="framebuf-colour.html"
>colours</A
></DT
><DD
><P
>determining the colour format (monochrome, paletted, …),
manipulating the palette, or constructing true colours.
</P
></DD
><DT
><A
HREF="framebuf-drawing.html"
>drawing</A
></DT
><DD
><P
>primitives for manipulating pixels and blocks of pixels.
</P
></DD
><DT
><A
HREF="framebuf-iterating.html"
>iteration</A
></DT
><DD
><P
>efficiently iterating over blocks of pixels.
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-THREADS"
></A
><H2
>Thread Safety</H2
><P
>The framebuffer API never performs any locking so is not thread-safe.
Instead it assumes that higher-level code such as a graphics library
performs any locking that may be needed. Adding a mutex lock and
unlock around every drawing primitive, including pixel writes, would
be prohibitively expensive.
</P
><P
>It is also assumed that the framebuffer will only be updated from
thread context. With most hardware it will also be possible to access
a framebuffer from DSR or ISR context, but this should be avoided in
portable code.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="io-framebuf.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="framebuf-parameters.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Framebuffer Support</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-framebuf.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Framebuffer Parameters</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -