Viewport

# 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;

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 CYG_FB_FLAGS0_VIEWPORT flag set. The viewport dimensions are available as additional parameters to the normal framebuffer width and height.

The current position of the viewport can be obtained using an CYG_FB_IOCTL_VIEWPORT_GET_POSITION ioctl operation. The data argument should be a pointer to a cyg_fb_ioctl_viewport structure. On return the fbvp_x and fbvp_y fields will be filled in. To move the viewport use CYG_FB_IOCTL_VIEWPORT_SET_POSITION with fbvp_x and fbvp_y set to the top left corner of the new viewport within the framebuffer, and fbvp_when set to either CYG_FB_UPDATE_NOW or CYG_FB_UPDATE_VERTICAL_RETRACE. If the device driver cannot easily synchronize to a vertical retrace period then this last field is ignored.

void
move_viewport(cyg_fb* fb, int dx, int dy)
{
#ifdef CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT
    cyg_fb_ioctl_viewport viewport;
    int len = sizeof(cyg_fb_ioctl_viewport);
    int result;

    result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_VIEWPORT_GET_POSITION,
                        &viewport, &len);
    if (result != 0) {
        …
    }
    if (((int)viewport.fbvp_x + dx) < 0) {
        viewport.fbvp_x = 0;
    } else if ((viewport.fbvp_x + dx + fb->fb_viewport_width) > fb->fb_width) {
        viewport.fbvp_x = fb->fb_width - fb->fb_viewport_width;
    } else {
        viewport.fbvp_x += dx;
    }
    if (((int)viewport.fbvp_y + dy) < 0) {
        viewport.fbvp_y = 0;
    } else if ((viewport.fbvp_y + dy + fb->fb_viewport_height) > fb->fb_height) {
        viewport.fbvp_y = fb->fb_height - fb->fb_viewport_height;
    } else {
        viewport.fbvp_y += dy;
    }
    result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_VIEWPORT_SET_POSITION,
                          &viewport, &len);
    if (result != 0) {
        …
    }
#else
    CYG_UNUSED_PARAM(cyg_fb*, fb);
    CYG_UNUSED_PARAM(int, dx);
    CYG_UNUSED_PARAM(int, dy);
#endif
}

If an attempt is made to move the viewport beyond the boundaries of the framebuffer then the resulting behaviour is undefined. Some hardware may behave reasonably, wrapping around as appropriate, but portable code cannot assume this. The above code fragment is careful to clip the viewport to the framebuffer dimensions.

Page Flipping

# define CYG_FB_IOCTL_PAGE_FLIPPING_GET_PAGES   0x0200
# define CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES   0x0201

typedef struct cyg_fb_ioctl_page_flip {
    cyg_uint32      fbpf_number_pages;
    cyg_uint32      fbpf_visible_page;
    cyg_uint32      fbpf_drawable_page;
    cyg_ucount16    fbpf_when;  // set-only, now or vert retrace
} cyg_fb_ioctl_page_flip;

On some targets the framebuffer has enough memory for several pages, only one of which is visible at a time. This allows the application to draw into one page while displaying another. Once drawing is complete the display is flipped to the newly drawn page, and the previously displayed page is now available for updating. This technique is used for smooth animation, especially in games. The flag CYG_FB_FLAGS0_PAGE_FLIPPING indicates support for this functionality.

CYG_FB_IOCTL_PAGE_FLIPPING_GET_PAGES can be used to get the current settings of the page flipping support. The data argument should be a pointer to a cyg_fb_ioctl_page_flip structure. The resulting fbpf_number_pages field indicates the total number of pages available: 2 is common, but more pages are possible. fbpf_visible_page gives the page that is currently visible to the user, and will be between 0 and (fbpf_number_pages - 1). Similarly fbpf_drawable_page gives the page that is currently visible. It is implementation-defined whether or not the visible and drawable page can be the same one.

CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES can be used to change the visible and drawable page. The fbpf_number_pages field is ignored. fbpf_visible_page and fbpf_drawable_page give the new settings. fbpf_when should be one of CYG_FB_UPDATE_NOW or CYG_FB_UPDATE_VERTICAL_RETRACE, but may be ignored by some device drivers.

#if !(CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_PAGE_FLIPPING)
# error Current framebuffer device does not support page flipping
#endif

static cyg_uint32 current_visible = 0;

static void
page_flip_init(cyg_fb_colour background)
{
    cyg_fb_ioctl_page_flip flip;
    size_t len = sizeof(cyg_fb_ioctl_page_flip);

    flip.fbpf_visible_page  = current_visible;
    flip.fbpf_drawable_page = 1 - current_visible;
    flip.fbpf_when          = CYG_FB_UPDATE_NOW;
    CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
                 &flip, &len);
    CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
                      CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
                      background);
    flip.fbpf_visible_page  = 1 - current_visible;
    flip.fbpf_drawable_page = current_visible;
    CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
                 &flip, &len);
    CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
                      CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
                      background);
    current_visible = 1 - current_visible;
}

static void
page_flip_toggle(void)
{
    cyg_fb_ioctl_page_flip flip;
    size_t len = sizeof(cyg_fb_ioctl_page_flip);

    flip.fbpf_visible_page  = 1 - current_visible;
    flip.fbpf_drawable_page = current_visible;
    CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
                 &flip, &len);
    current_visible = 1 - current_visible;
}

A page flip typically just changes a couple of pointers within the hardware and device driver. No attempt is made to synchronize the contents of the pages, that is left to higher-level code.

Blanking the Screen

# define CYG_FB_IOCTL_BLANK_GET                 0x0300
# define CYG_FB_IOCTL_BLANK_SET                 0x0301

typedef struct cyg_fb_ioctl_blank {
    cyg_bool        fbbl_on;
} cyg_fb_ioctl_blank;

Some hardware allows the display to be switched off or blanked without shutting down the entire framebuffer device, greatly reducing power consumption. The current blanking state can be obtained using CYG_FB_IOCTL_BLANK_GET and the state can be updated using CYG_FB_IOCTL_BLANK_SET. The data argument should be a pointer to a cyg_fb_ioctl_blank structure. Support for this functionality is indicated by the CYG_FB_FLAGS0_BLANK flag.

static cyg_bool
display_blanked(cyg_fb_* fb)
{
    cyg_fb_ioctl_blank blank;
    size_t len = sizeof(cyg_fb_ioctl_blank);

    if (! (fb->fb_flags0 & CYG_FB_FLAGS0_BLANK)) {
        return false;
    }
    (void) cyg_fb_ioctl(fb, CYG_FB_IOCTL_BLANK_GET, &blank, &len);
    return !blank.fbbl_on;
}

Controlling the Backlight

# define CYG_FB_IOCTL_BACKLIGHT_GET             0x0400
# define CYG_FB_IOCTL_BACKLIGHT_SET             0x0401

typedef struct cyg_fb_ioctl_backlight {
    cyg_ucount32    fbbl_current;
    cyg_ucount32    fbbl_max;
} cyg_fb_ioctl_backlight;

Many LCD panels provide some sort of backlight, making the display easier to read at the cost of increased power consumption. Support for this is indicated by the CYG_FB_FLAGS0_BACKLIGHT flag. CYG_FB_IOCTL_BACKLIGHT_GET can be used to get both the current setting and the maximum value. If the maximum is 1 then the backlight can only be switched on or off. Otherwise it is possible to control the intensity.

static void
set_backlight_50_percent(void)
{
#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_BACKLIGHT)
    cyg_fb_ioctl_backlight backlight;
    size_t len = sizeof(cyg_fb_ioctl_backlight);

    CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_BACKLIGHT_GET, &backlight, &len);
    backlight.fbbl_current = (backlight.fbbl_max + 1) >> 1;
    CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_BACKLIGHT_SET, &backlight, &len);
#endif
}