1 /* Copyright (C)2004 Landmark Graphics Corporation 2 * Copyright (C)2005, 2006 Sun Microsystems, Inc. 3 * Copyright (C)2011, 2017-2018 D. R. Commander 4 * 5 * This library is free software and may be redistributed and/or modified under 6 * the terms of the wxWindows Library License, Version 3.1 or (at your option) 7 * any later version. The full license is in the LICENSE.txt file included 8 * with this distribution. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * wxWindows Library License for more details. 14 */ 15 16 /* 17 FBX -- the fast Frame Buffer eXchange library 18 This library is designed to facilitate transferring pixels to/from the 19 framebuffer using fast 2D O/S-native methods that do not rely on OpenGL 20 acceleration 21 */ 22 23 #ifndef __FBX_H__ 24 #define __FBX_H__ 25 26 #define USESHM 27 28 #include <stdio.h> 29 #include "pf.h" 30 31 #ifdef _WIN32 32 33 #include <windows.h> 34 typedef HDC fbx_gc; 35 typedef HWND fbx_wh; 36 37 #else 38 39 #include <X11/Xlib.h> 40 41 #ifdef USESHM 42 #include <sys/ipc.h> 43 #include <sys/shm.h> 44 #include <X11/extensions/XShm.h> 45 #endif 46 47 #include <X11/Xutil.h> 48 49 typedef GC fbx_gc; 50 typedef struct 51 { 52 Display *dpy; Drawable d; Visual *v; 53 } fbx_wh; 54 55 #endif /* _WIN32 */ 56 57 58 typedef struct _fbx_struct 59 { 60 int width, height, pitch; 61 char *bits; 62 PF *pf; 63 fbx_wh wh; 64 int shm; 65 66 #ifdef _WIN32 67 HDC hmdc; HBITMAP hdib; 68 #else 69 #ifdef USESHM 70 XShmSegmentInfo shminfo; int xattach; 71 #endif 72 GC xgc; 73 XImage *xi; 74 Pixmap pm; 75 int pixmap; 76 #endif 77 } fbx_struct; 78 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 /* 85 All of these methods return -1 on failure or 0 on success. 86 */ 87 88 89 /* 90 fbx_init 91 (fbx_struct *fb, fbx_wh wh, int width, int height, int useShm) 92 93 fb = Address of fbx_struct (must be pre-allocated by user) 94 wh = Handle to the window that you wish to read from or write to. On 95 Windows, this is the same as the HWND. On Unix, this is a struct 96 (see above) that describes the X11 display and drawable you wish to use. 97 If wh.v is non-NULL, then FBX assumes that the drawable is a Pixmap. 98 width = Width of buffer (in pixels) that you wish to create. 0 = use width 99 of window 100 height = Height of buffer (in pixels) that you wish to create. 0 = use 101 height of window 102 useShm = Use MIT-SHM extension, if available (Unix only.) 103 104 NOTES: 105 -- fbx_init() is idempotent. If you call it multiple times, it will 106 re-initialize the buffer only when it is necessary to do so (such as when 107 the window size has changed.) 108 -- On Windows, fbx_init() will return a buffer configured with the same pixel 109 format as the screen, unless the screen depth is < 24 bits, in which case 110 it will always return a 32-bit BGRA buffer. 111 112 On return, fbx_init() fills in the following relevant information in the 113 fbx_struct that you passed to it: 114 115 fb->pf = pixel format of the buffer 116 fb->width, fb->height = dimensions of the buffer 117 fb->pitch = bytes in each scanline of the buffer 118 fb->bits = address of the start of the buffer 119 */ 120 int fbx_init(fbx_struct *fb, fbx_wh wh, int width, int height, int useShm); 121 122 123 /* 124 fbx_read 125 (fbx_struct *fb, int x, int y) 126 127 This routine copies pixels from the framebuffer into the memory buffer 128 specified by fb. 129 130 fb = Address of fbx_struct previously initialized by a call to fbx_init() 131 x = Horizontal offset (from left of drawable) of rectangle to read 132 y = Vertical offset (from top of drawable) of rectangle to read 133 134 NOTE: width and height of rectangle are not adjustable without re-calling 135 fbx_init() 136 137 On return, fb->bits contains a facsimile of the window's pixels 138 */ 139 int fbx_read(fbx_struct *fb, int x, int y); 140 141 142 /* 143 fbx_write 144 (fbx_struct *fb, int srcX, int srcY, int dstX, int dstY, int width, 145 int height) 146 147 This routine copies pixels from the memory buffer specified by fb to the 148 framebuffer. 149 150 fb = Address of fbx_struct previously initialized by a call to fbx_init() 151 fb->bits should contain the pixels you wish to blit 152 srcX = left offset of the region you wish to blit (relative to the memory 153 buffer) 154 srcY = top offset of the region you wish to blit (relative to the memory 155 buffer) 156 dstX = left offset of where you want the pixels to end up (relative to 157 drawable area) 158 dstY = top offset of where you want the pixels to end up (relative to 159 drawable area) 160 width = width of region you wish to blit (0 = whole bitmap) 161 height = height of region you wish to blit (0 = whole bitmap) 162 */ 163 int fbx_write(fbx_struct *fb, int srcX, int srcY, int dstX, int dstY, 164 int width, int height); 165 166 167 /* 168 fbx_awrite 169 (fbx_struct *fb, int srcX, int srcY, int dstX, int dstY, int width, 170 int height) 171 172 Same as fbx_write, but asynchronous. The write isn't guaranteed to complete 173 until fbx_sync() is called. On Windows, fbx_awrite is the same as fbx_write. 174 */ 175 #ifdef _WIN32 176 #define fbx_awrite fbx_write 177 #else 178 int fbx_awrite(fbx_struct *fb, int srcX, int srcY, int dstX, int dstY, 179 int width, int height); 180 #endif 181 182 183 /* 184 fbx_flip 185 (fbx_struct *fb, int srcX, int srcY, int width, int height) 186 187 This routine performs an in-place vertical flip of the region of interest 188 specified by srcX, srcY, width, and height in the memory buffer specified by 189 fb. 190 191 fb = Address of fbx_struct previously initialized by a call to fbx_init() 192 fb->bits should contain the pixels you wish to flip 193 srcX = left offset of the region you wish to flip (relative to the memory 194 buffer) 195 srcY = top offset of the region you wish to flip (relative to the memory 196 buffer) 197 width = width of region you wish to flip (0 = whole bitmap) 198 height = height of region you wish to flip (0 = whole bitmap) 199 */ 200 int fbx_flip(fbx_struct *fb, int srcX, int srcY, int width, int height); 201 202 203 /* 204 fbx_sync 205 (fbx_struct *fb) 206 207 Complete a previous asynchronous write. On Windows, this does nothing. 208 */ 209 int fbx_sync(fbx_struct *fb); 210 211 212 /* 213 fbx_term 214 (fbx_struct *fb) 215 216 Free the memory buffers pointed to by structure fb. 217 218 NOTE: this routine is idempotent. It only frees stuff that needs freeing. 219 */ 220 int fbx_term(fbx_struct *fb); 221 222 223 /* 224 fbx_geterrmsg 225 226 This returns a string containing the reason why the last command failed. 227 */ 228 char *fbx_geterrmsg(void); 229 230 231 /* 232 fbx_geterrline 233 234 This returns the line (within fbx.c) of the last failure. 235 */ 236 int fbx_geterrline(void); 237 238 239 /* 240 fbx_printwarnings 241 (FILE *output_stream) 242 243 By default, FBX will not print warning messages (such as messages related to 244 its automatic selection of a particular drawing method.) These messages are 245 sometimes useful when diagnosing performance issues. Passing a stream 246 pointer (such as stdout, stderr, or a pointer returned from a previous call 247 to fopen()) to this function will enable warning messages and will cause them 248 to be printed to the specified stream. Passing an argument of NULL to this 249 function will disable warnings. 250 */ 251 void fbx_printwarnings(FILE *output_stream); 252 253 254 #ifdef __cplusplus 255 } 256 #endif 257 258 #endif /* __FBX_H__ */ 259