framebuffer.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_FRAMEBUFFER_H
#define _ULTIBO_FRAMEBUFFER_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/devices.h"

#define FRAMEBUFFER_NAME_PREFIX "Framebuffer" 

#define FRAMEBUFFER_TYPE_NONE   0
#define FRAMEBUFFER_TYPE_HARDWARE   1
#define FRAMEBUFFER_TYPE_VIRTUAL    2
 
#define FRAMEBUFFER_TYPE_MAX    2

#define FRAMEBUFFER_STATE_DISABLED  0
#define FRAMEBUFFER_STATE_ENABLED   1
 
#define FRAMEBUFFER_STATE_MAX   1

#define FRAMEBUFFER_CURSOR_DISABLED 0
#define FRAMEBUFFER_CURSOR_ENABLED  1

#define FRAMEBUFFER_FLAG_NONE   0x00000000
#define FRAMEBUFFER_FLAG_DMA    0x00000001 
#define FRAMEBUFFER_FLAG_MARK   0x00000002 
#define FRAMEBUFFER_FLAG_COMMIT 0x00000004 
#define FRAMEBUFFER_FLAG_BLANK  0x00000008 
#define FRAMEBUFFER_FLAG_CACHED 0x00000010 
#define FRAMEBUFFER_FLAG_SWAP   0x00000020 
#define FRAMEBUFFER_FLAG_BACKLIGHT  0x00000040 
#define FRAMEBUFFER_FLAG_VIRTUAL    0x00000080 
#define FRAMEBUFFER_FLAG_OFFSETX    0x00000100 
#define FRAMEBUFFER_FLAG_OFFSETY    0x00000200 
#define FRAMEBUFFER_FLAG_SYNC   0x00000400 
#define FRAMEBUFFER_FLAG_CURSOR 0x00000800 

#define FRAMEBUFFER_TRANSFER_NONE   0x00000000
#define FRAMEBUFFER_TRANSFER_DMA    0x00000001 

typedef struct _FRAMEBUFFER_PALETTE FRAMEBUFFER_PALETTE;
struct _FRAMEBUFFER_PALETTE
{
    uint32_t start; 
    uint32_t count; 
    uint32_t entries[256]; 
};
 
typedef struct _FRAMEBUFFER_PROPERTIES FRAMEBUFFER_PROPERTIES;
struct _FRAMEBUFFER_PROPERTIES
{
    uint32_t flags; 
    size_t address; 
    uint32_t size; 
    uint32_t pitch; 
    uint32_t depth; 
    uint32_t order; 
    uint32_t mode; 
    uint32_t format; 
    uint32_t physicalwidth; 
    uint32_t physicalheight; 
    uint32_t virtualwidth; 
    uint32_t virtualheight; 
    uint32_t offsetx; 
    uint32_t offsety; 
    uint32_t overscantop; 
    uint32_t overscanbottom; 
    uint32_t overscanleft; 
    uint32_t overscanright; 
    uint32_t rotation; 
    uint32_t cursorx; 
    uint32_t cursory; 
    uint32_t cursorstate; 
};
 
typedef struct _FRAMEBUFFER_DEVICE FRAMEBUFFER_DEVICE;

typedef uint32_t STDCALL (*framebuffer_enumerate_cb)(FRAMEBUFFER_DEVICE *framebuffer, void *data);
typedef uint32_t STDCALL (*framebuffer_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*framebuffer_device_allocate_proc)(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);
typedef uint32_t STDCALL (*framebuffer_device_release_proc)(FRAMEBUFFER_DEVICE *framebuffer);
 
typedef uint32_t STDCALL (*framebuffer_device_blank_proc)(FRAMEBUFFER_DEVICE *framebuffer, BOOL blank);
 
typedef uint32_t STDCALL (*framebuffer_device_read_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t len, uint32_t flags);
typedef uint32_t STDCALL (*framebuffer_device_write_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t len, uint32_t flags);
 
typedef uint32_t STDCALL (*framebuffer_device_mark_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, uint32_t width, uint32_t height, uint32_t flags);
typedef uint32_t STDCALL (*framebuffer_device_commit_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t address, uint32_t size, uint32_t flags);
 
typedef uint32_t STDCALL (*framebuffer_device_get_rect_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t width, uint32_t height, uint32_t skip, uint32_t flags);
typedef uint32_t STDCALL (*framebuffer_device_put_rect_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t width, uint32_t height, uint32_t skip, uint32_t flags);
typedef uint32_t STDCALL (*framebuffer_device_copy_rect_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x1, uint32_t y1, uint32_t x2, uint32_t y2, uint32_t width, uint32_t height, uint32_t flags);
typedef uint32_t STDCALL (*framebuffer_device_fill_rect_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, uint32_t width, uint32_t height, uint32_t color, uint32_t flags);
 
typedef void * STDCALL (*framebuffer_device_get_line_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t y);
typedef void * STDCALL (*framebuffer_device_get_point_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y);
 
typedef uint32_t STDCALL (*framebuffer_device_wait_sync_proc)(FRAMEBUFFER_DEVICE *framebuffer);
 
typedef uint32_t STDCALL (*framebuffer_device_get_offset_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t *x, uint32_t *y);
typedef uint32_t STDCALL (*framebuffer_device_set_offset_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, BOOL pan);
typedef uint32_t STDCALL (*framebuffer_device_set_offset_ex_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, BOOL pan, BOOL _switch);
 
typedef uint32_t STDCALL (*framebuffer_device_get_palette_proc)(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PALETTE *palette);
typedef uint32_t STDCALL (*framebuffer_device_set_palette_proc)(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PALETTE *palette);
 
typedef uint32_t STDCALL (*framebuffer_device_set_backlight_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t brightness);
 
typedef uint32_t STDCALL (*framebuffer_device_set_cursor_proc)(FRAMEBUFFER_DEVICE *framebuffer, uint32_t width, uint32_t height, uint32_t hotspotx, uint32_t hotspoty, void *image, uint32_t len);
typedef uint32_t STDCALL (*framebuffer_device_update_cursor_proc)(FRAMEBUFFER_DEVICE *framebuffer, BOOL enabled, int32_t x, int32_t y, BOOL relative);
 
typedef uint32_t STDCALL (*framebuffer_device_get_properties_proc)(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);
typedef uint32_t STDCALL (*framebuffer_device_set_properties_proc)(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);

struct _FRAMEBUFFER_DEVICE
{
    // Device Properties
    DEVICE device; 
    // Framebuffer Properties
    uint32_t framebufferid; 
    uint32_t framebufferstate; 
    framebuffer_device_allocate_proc deviceallocate; 
    framebuffer_device_release_proc devicerelease; 
    framebuffer_device_blank_proc deviceblank; 
    framebuffer_device_read_proc deviceread; 
    framebuffer_device_write_proc devicewrite; 
    framebuffer_device_mark_proc devicemark; 
    framebuffer_device_commit_proc devicecommit; 
    framebuffer_device_get_rect_proc devicegetrect; 
    framebuffer_device_put_rect_proc deviceputrect; 
    framebuffer_device_copy_rect_proc devicecopyrect; 
    framebuffer_device_fill_rect_proc devicefillrect; 
    framebuffer_device_get_line_proc devicegetline; 
    framebuffer_device_get_point_proc devicegetpoint; 
    framebuffer_device_wait_sync_proc devicewaitsync; 
    framebuffer_device_get_offset_proc devicegetoffset; 
    framebuffer_device_set_offset_proc devicesetoffset; 
    framebuffer_device_set_offset_ex_proc devicesetoffsetex; 
    framebuffer_device_get_palette_proc devicegetpalette; 
    framebuffer_device_set_palette_proc devicesetpalette; 
    framebuffer_device_set_backlight_proc devicesetbacklight; 
    framebuffer_device_set_cursor_proc devicesetcursor; 
    framebuffer_device_update_cursor_proc deviceupdatecursor; 
    framebuffer_device_get_properties_proc devicegetproperties; 
    framebuffer_device_set_properties_proc devicesetproperties; 
    // Statistics Properties
    uint32_t allocatecount;
    uint32_t releasecount;
    uint32_t readcount;
    uint32_t writecount;
    uint32_t getcount;
    uint32_t putcount;
    uint32_t copycount;
    uint32_t fillcount;
    // Driver Properties
    MUTEX_HANDLE lock; 
    size_t address; 
    uint32_t size; 
    uint32_t pitch; 
    uint32_t depth; 
    uint32_t order; 
    uint32_t mode; 
    uint32_t format; 
    uint32_t physicalwidth; 
    uint32_t physicalheight; 
    uint32_t virtualwidth; 
    uint32_t virtualheight; 
    uint32_t offsetx; 
    uint32_t offsety; 
    uint32_t overscantop; 
    uint32_t overscanbottom; 
    uint32_t overscanleft; 
    uint32_t overscanright; 
    uint32_t rotation; 
    uint32_t cursorx; 
    uint32_t cursory; 
    uint32_t cursorstate; 
    // Buffer Properties
    void *linebuffer; 
    void *copybuffer; 
    // Cursor Properties
    LONGBOOL cursorupdate; 
    void *cursorimage; 
    void *cursorinput; 
    void *cursorbuffer; 
    void *cursoroutput; 
    uint32_t cursorwidth; 
    uint32_t cursorheight; 
    uint32_t cursorhotspotx; 
    uint32_t cursorhotspoty; 
    // Internal Properties
    FRAMEBUFFER_DEVICE *prev; 
    FRAMEBUFFER_DEVICE *next; 
};


uint32_t STDCALL framebuffer_device_allocate(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);

uint32_t STDCALL framebuffer_device_release(FRAMEBUFFER_DEVICE *framebuffer);

uint32_t STDCALL framebuffer_device_blank(FRAMEBUFFER_DEVICE *framebuffer, BOOL blank);

uint32_t STDCALL framebuffer_device_read(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t len, uint32_t flags);

uint32_t STDCALL framebuffer_device_write(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t len, uint32_t flags);

uint32_t STDCALL framebuffer_device_mark(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, uint32_t width, uint32_t height, uint32_t flags);

uint32_t STDCALL framebuffer_device_commit(FRAMEBUFFER_DEVICE *framebuffer, size_t address, uint32_t size, uint32_t flags);

uint32_t STDCALL framebuffer_device_get_rect(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t width, uint32_t height, uint32_t skip, uint32_t flags);

uint32_t STDCALL framebuffer_device_put_rect(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, void *buffer, uint32_t width, uint32_t height, uint32_t skip, uint32_t flags);

uint32_t STDCALL framebuffer_device_copy_rect(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x1, uint32_t y1, uint32_t x2, uint32_t y2, uint32_t width, uint32_t height, uint32_t flags);

uint32_t STDCALL framebuffer_device_fill_rect(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, uint32_t width, uint32_t height, uint32_t color, uint32_t flags);

void * STDCALL framebuffer_device_get_line(FRAMEBUFFER_DEVICE *framebuffer, uint32_t y);

void * STDCALL framebuffer_device_get_point(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y);

uint32_t STDCALL framebuffer_device_wait_sync(FRAMEBUFFER_DEVICE *framebuffer);

uint32_t STDCALL framebuffer_device_get_offset(FRAMEBUFFER_DEVICE *framebuffer, uint32_t *x, uint32_t *y);

uint32_t STDCALL framebuffer_device_set_offset(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, BOOL pan);

uint32_t STDCALL framebuffer_device_set_offset_ex(FRAMEBUFFER_DEVICE *framebuffer, uint32_t x, uint32_t y, BOOL pan, BOOL _switch);

uint32_t STDCALL framebuffer_device_get_palette(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PALETTE *palette);

uint32_t STDCALL framebuffer_device_set_palette(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PALETTE *palette);

uint32_t STDCALL framebuffer_device_set_backlight(FRAMEBUFFER_DEVICE *framebuffer, uint32_t brightness);

uint32_t STDCALL framebuffer_device_set_cursor(FRAMEBUFFER_DEVICE *framebuffer, uint32_t width, uint32_t height, uint32_t hotspotx, uint32_t hotspoty, void *image, uint32_t len);

uint32_t STDCALL framebuffer_device_update_cursor(FRAMEBUFFER_DEVICE *framebuffer, BOOL enabled, int32_t x, int32_t y, BOOL relative);

uint32_t STDCALL framebuffer_device_get_properties(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);

uint32_t STDCALL framebuffer_device_set_properties(FRAMEBUFFER_DEVICE *framebuffer, FRAMEBUFFER_PROPERTIES *properties);

BOOL STDCALL framebuffer_device_check_flag(FRAMEBUFFER_DEVICE *framebuffer, uint32_t flag);

uint32_t STDCALL framebuffer_device_get_format(FRAMEBUFFER_DEVICE *framebuffer);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_create(void);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_create_ex(uint32_t size);

uint32_t STDCALL framebuffer_device_destroy(FRAMEBUFFER_DEVICE *framebuffer);

uint32_t STDCALL framebuffer_device_register(FRAMEBUFFER_DEVICE *framebuffer);

uint32_t STDCALL framebuffer_device_deregister(FRAMEBUFFER_DEVICE *framebuffer);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_find(uint32_t framebufferid);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_find_by_name(const char *name);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_find_by_description(const char *description);

uint32_t STDCALL framebuffer_device_enumerate(framebuffer_enumerate_cb callback, void *data);

uint32_t STDCALL framebuffer_device_notification(FRAMEBUFFER_DEVICE *framebuffer, framebuffer_notification_cb callback, void *data, uint32_t notification, uint32_t flags);


uint32_t STDCALL framebuffer_device_get_count(void);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_get_default(void);

uint32_t STDCALL framebuffer_device_set_default(FRAMEBUFFER_DEVICE *framebuffer);

FRAMEBUFFER_DEVICE * STDCALL framebuffer_device_check(FRAMEBUFFER_DEVICE *framebuffer);

uint32_t STDCALL framebuffer_device_swap(uint32_t value);

uint32_t STDCALL framebuffer_type_to_string(uint32_t framebuffertype, char *string, uint32_t len);

uint32_t STDCALL framebuffer_state_to_string(uint32_t framebufferstate, char *string, uint32_t len);

void STDCALL framebuffer_device_hide_cursor(FRAMEBUFFER_DEVICE *framebuffer);

void STDCALL framebuffer_device_show_cursor(FRAMEBUFFER_DEVICE *framebuffer);
 
uint32_t STDCALL framebuffer_cursor_to_string(uint32_t state, char *string, uint32_t len);
 
uint32_t STDCALL framebuffer_depth_to_string(uint32_t depth, char *string, uint32_t len);
uint32_t STDCALL framebuffer_order_to_string(uint32_t order, char *string, uint32_t len);
uint32_t STDCALL framebuffer_mode_to_string(uint32_t mode, char *string, uint32_t len);
uint32_t STDCALL framebuffer_rotation_to_string(uint32_t rotation, char *string, uint32_t len);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_FRAMEBUFFER_H