framebuf-control.html
来自「ecos3.0 beta 的官方文档,html格式」· HTML 代码 · 共 918 行 · 第 1/2 页
HTML
918 行
<!-- 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
>Framebuffer Control Operations</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 Parameters"
HREF="framebuf-parameters.html"><LINK
REL="NEXT"
TITLE="Framebuffer Colours"
HREF="framebuf-colour.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="framebuf-parameters.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="framebuf-colour.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="FRAMEBUF-CONTROL"
></A
>Framebuffer Control Operations</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN10266"
></A
><H2
>Name</H2
>Control Operations -- managing a framebuffer</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN10269"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN10270"
></A
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <cyg/io/framebuf.h>
</PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int cyg_fb_on</CODE
>(cyg_fb* fbdev);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int cyg_fb_off</CODE
>(cyg_fb* fbdev);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int cyg_fb_ioctl</CODE
>(cyg_fb* fbdev, cyg_uint16 key, void* data, size_t* len);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int CYG_FB_ON</CODE
>(FRAMEBUF);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int CYG_FB_OFF</CODE
>(FRAMEBUF);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int CYG_FB_IOCTL</CODE
>(FRAMEBUF, cyg_uint16 key, void* data, size_t* len);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-CONTROL-DESCRIPTION"
></A
><H2
>Description</H2
><P
>The main operations on a framebuffer are drawing and colour
management. However on most hardware it is also necessary to switch
the display <A
HREF="framebuf-control.html#FRAMEBUF-CONTROL-ONOFF"
>on</A
> before the
user can see anything, and application code should be able to control
when this happens. There are also miscellaneous operations such as
manipulating the backlight or moving the viewpoint. These do not
warrant dedicated functions, especially since the functionality will
only be available on some hardware, so an <A
HREF="framebuf-control.html#FRAMEBUF-CONTROL-IOCTL"
><CODE
CLASS="FUNCTION"
>ioctl</CODE
></A
>
interface is used.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-CONTROL-ONOFF"
></A
><H2
>Switching the Display On or Off</H2
><P
>With most hardware nothing will be visible until there is a call to
<CODE
CLASS="FUNCTION"
>cyg_fb_on</CODE
> or an invocation of the
<CODE
CLASS="FUNCTION"
>CYG_FB_ON</CODE
> macro. This will initialize the
framebuffer control circuitry, start sending the data signals to the
display unit, and switch on the display if necessary. The exact
initialization semantics are left to the framebuffer device driver. In
some cases the hardware may already be partially or fully initialized
by a static constructor or by boot code that ran before eCos.
</P
><P
>There are some circumstances in which initialization can fail, and
this is indicated by a POSIX error code such as
<TT
CLASS="LITERAL"
>ENODEV</TT
>. An example would be plug and play hardware
where the framebuffer device is not detected at run-time. Another
example is hardware which can operate in several modes, with separate
<CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structures for each mode, if the
hardware is already in use for a different mode. A return value of 0
indicates success.
</P
><P
>Some but not all hardware allows the framebuffer memory and, if
present, the palette to be manipulated before the device is switched
on. That way the user does not see random noise on the screen during
system startup. The flag <TT
CLASS="LITERAL"
>CYG_FB_FLAGS0_MUST_BE_ON</TT
>
should be checked:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
init_screen(cyg_fb_colour background)
{
int result;
#if (! (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON))
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
background);
#endif
result = CYG_FB_ON(FRAMEBUF);
if (0 != result) {
<handle unusual error condition>
}
#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON)
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
background);
#endif
}
</PRE
></TD
></TR
></TABLE
><P
>Obviously if the application has already manipulated framebuffer
memory or the palette but then the <CODE
CLASS="FUNCTION"
>cyg_fb_on</CODE
>
operation fails, the system is left in an undefined state.
</P
><P
>It is also possible to switch a framebuffer device off, using the
function <CODE
CLASS="FUNCTION"
>cyg_fb_off</CODE
> or the macro
<CODE
CLASS="FUNCTION"
>CYG_FB_OFF</CODE
>, although this functionality is rarely
used in embedded systems. The exact semantics of switching a device
off are implementation-defined, but typically it involves shutting
down the display, stopping the data signals to the display, and
halting the control circuitry. The framebuffer memory and the palette
are left in an undefined state, and application code should assume
that both need full reinitializing when the device is switched back
on. Some hardware may also provide a <A
HREF="framebuf-control.html#FRAMEBUF-CONTROL-IOCTL-BLANK"
>blank</A
> operation which
typically just manipulates the display, not the whole framebuffer
device. Normally <CODE
CLASS="FUNCTION"
>cyg_fb_on</CODE
> returns 0. The API
allows for a POSIX error code as with <CODE
CLASS="FUNCTION"
>cyg_fb_on</CODE
>,
but switching a device off is not an operation that is likely to fail.
</P
><P
>If a framebuffer device can operate in several modes, represented by
several <CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structures and macro
identifiers, then switching modes requires turning the current device
off before turning the next one one.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="FRAMEBUF-CONTROL-IOCTL"
></A
><H2
>Miscellaneous Control Operations</H2
><P
>Some hardware functionality such as an LCD panel backlight is common
but not universal. Supporting these does not warrant dedicated
functions. Instead a catch-all <CODE
CLASS="FUNCTION"
>ioctl</CODE
> interface is
provided, with the arguments just passed straight to the device
driver. This approach also allows for future expansion and for
device-specific operations. <CODE
CLASS="FUNCTION"
>cyg_fb_ioctl</CODE
> and
<CODE
CLASS="FUNCTION"
>CYG_FB_IOCTL</CODE
> take four arguments: a
<CODE
CLASS="STRUCTNAME"
>cyg_fb</CODE
> structure or framebuffer identifier; a
key that specifies the operation to be performed; an arbitrary
pointer, which should usually be a pointer to a data structure
specific to the key; and a length field. Key values from 0 to 0x7fff
are generic. Key values from 0x8000 onwards are reserved for the
individual framebuffer device drivers, for device-specific
functionality. The length field should be set to the size of the data
structure, and may get updated by the device driver.
</P
><P
>With most ioctl operations the device can indicate whether or not it
supports the functionality by one of the flags, for example:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void
backlight_off(cyg_fb* fb)
{
if (fb->fb_flags0 & CYG_FB_FLAGS0_BACKLIGHT) {
cyg_fb_ioctl_backlight new_setting;
size_t len = sizeof(cyg_fb_ioctl_backlight);
int result;
new_setting.fbbl_current = 0;
result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_BACKLIGHT_SET,
&new_setting, &len);
if (0 != result) {
…
}
}
}
</PRE
></TD
></TR
></TABLE
><P
>The operation returns zero for success or a POSIX error code on
failure, for example <TT
CLASS="LITERAL"
>ENOSYS</TT
> if the device driver
does not implement the requested functionality.
</P
><DIV
CLASS="REFSECT2"
><A
NAME="FRAMEBUF-CONTROL-IOCTL-VIEWPORT"
></A
><H3
>Viewport</H3
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># define CYG_FB_IOCTL_VIEWPORT_GET_POSITION 0x0100
# define CYG_FB_IOCTL_VIEWPORT_SET_POSITION 0x0101
typedef struct cyg_fb_ioctl_viewport {
cyg_ucount16 fbvp_x; // position of top-left corner of the viewport within
cyg_ucount16 fbvp_y; // the framebuffer
cyg_ucount16 fbvp_when; // set-only, now or vert retrace
} cyg_fb_ioctl_viewport;
</PRE
></TD
></TR
></TABLE
><P
>On some targets the framebuffer device has a higher resolution than
the display. Only a subset of the pixels, the viewport, is currently
visible. Application code can exploit this functionality to achieve
certain effects, for example smooth scrolling. Framebuffers which
support this functionality will have the
<TT
CLASS="LITERAL"
>CYG_FB_FLAGS0_VIEWPORT</TT
> flag set. The viewport
dimensions are available as additional <A
HREF="framebuf-parameters.html"
>parameters</A
> to the normal
framebuffer width and height.
</P
><P
>The current position of the viewport can be obtained using an
<TT
CLASS="LITERAL"
>CYG_FB_IOCTL_VIEWPORT_GET_POSITION</TT
> ioctl operation.
The data argument should be a pointer to a
<CODE
CLASS="STRUCTNAME"
>cyg_fb_ioctl_viewport</CODE
> structure. On return
the <CODE
CLASS="STRUCTFIELD"
>fbvp_x</CODE
> and
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?