1/* 2 * Copyright 2012 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * src/kits/game/DirectWindow.cpp hrev45044 10 * src/kits/game/DirectWindow.h hrev45044 11 */ 12 13 14/*! 15 \file DirectWindow.h 16 \ingroup game 17 \ingroup libbe 18 \brief Provides the BDirectWindow class. 19*/ 20 21 22/*! 23 \enum direct_buffer_state 24 25 Direct buffer state constants 26*/ 27 28 29/*! 30 \enum direct_driver_state 31 32 Direct driver state constants 33*/ 34 35 36/*! 37 \struct direct_buffer_info 38 \ingroup game 39 \ingroup libbe 40 41 Direct butter info struct 42*/ 43 44 45/*! 46 \var direct_buffer_info::buffer_state 47 48 State of the direct buffer access privileges. 49 It can have one of the following values: 50 - \c B_DIRECT_MODE_MASK 51 - \c B_DIRECT_START 52 - \c B_DIRECT_MODIFY 53 - \c B_DIRECT_STOP 54 - \c B_BUFFER_MOVED 55 - \c B_BUFFER_RESET 56 - \c B_BUFFER_RESIZED 57 - \c B_CLIPPING_MODIFIED 58*/ 59 60 61/*! 62 \var direct_buffer_info::driver_state 63 64 State of the graphics card on which your direct window is displayed. 65 There are two possible values: 66 - \c B_MODE_CHANGED The resolution or color depth has changed. 67 - \c B_DRIVER_CHANGED The window was moved onto another monitor. 68*/ 69 70 71/*! 72 \var direct_buffer_info::bits 73 74 Pointer to the frame buffer in your team's memory space. 75*/ 76 77 78/*! 79 \var direct_buffer_info::pci_bits 80 81 Pointer to the frame buffer in the PCI memory space. This value is 82 typically needed to control DMA. 83*/ 84 85/*! 86 \var direct_buffer_info::bytes_per_row 87 88 Number of bytes used to represent a single row of pixels in the frame buffer. 89*/ 90 91 92/*! 93 \var direct_buffer_info::bits_per_pixel 94 95 Number of bits actually used to store a single pixel, including reserved, 96 unused, or alpha channel bits. This value is usually a multiple of eight. 97*/ 98 99 100/*! 101 \var direct_buffer_info::pixel_format 102 103 The format used to encode a pixel as defined by the \c color_space type. 104*/ 105 106 107/*! 108 \var direct_buffer_info::layout 109 110 Reserved for future use. 111*/ 112 113 114/*! 115 \var direct_buffer_info::orientation 116 117 Reserved for future use. 118*/ 119 120 121/*! 122 \var direct_buffer_info::_reserved[9] 123 124 Reserved for future use. 125*/ 126 127 128/*! 129 \var direct_buffer_info::_dd_type_ 130 131 Reserved for future use. 132*/ 133 134 135/*! 136 \var direct_buffer_info::_dd_token_ 137 138 Reserved for future use. 139*/ 140 141 142/*! 143 \var direct_buffer_info::clip_list_count 144 145 Number of rectangles in \c clip_list. 146*/ 147 148 149/*! 150 \var direct_buffer_info::window_bounds 151 152 Rectangle that defines the full content area of the window in screen 153 coordinates. 154*/ 155 156 157/*! 158 \var direct_buffer_info::clip_bounds 159 160 Bounding rectangle of the visible part of the content area of the window 161 in screen coordinates. 162*/ 163 164 165/*! 166 \var direct_buffer_info::clip_list 167 168 List of rectangles that together define the visible region of the content 169 area of the window in screen coordinates. 170*/ 171 172 173/*! 174 \class BDirectWindow 175 \ingroup game 176 \ingroup libbe 177 \brief Provides direct access to the video card graphics frame buffer. 178*/ 179 180 181/*! 182 \fn BDirectWindow::BDirectWindow(BRect frame, const char *title, 183 window_type type, uint32 flags, uint32 workspace) 184 \brief Creates and initializes a BDirectWindow object. 185 186 \param frame The initial frame rectangle of the window. 187 \param title The title of the Window. 188 \param type Window type (see BWindow). 189 \param flags Window flags (see BWindow). 190 \param workspace Workspace of the direct window (see BWindow). 191*/ 192 193 194/*! 195 \fn BDirectWindow::BDirectWindow(BRect frame, const char *title, 196 window_look look, window_feel feel, uint32 flags, uint32 workspace) 197 \brief Creates and initializes a BDirectWindow object. 198 199 \param frame The initial frame rectangle of the window. 200 \param title The title of the Window. 201 \param look Window look (see BWindow). 202 \param feel Window feel (see BWindow). 203 \param flags Window flags (see BWindow). 204 \param workspace Workspace of the direct window (see BWindow). 205*/ 206 207 208/*! 209 \fn BDirectWindow::~BDirectWindow() 210 \brief Destroys the BDirectWindow and frees all memory used by it. 211 212 Do not delete a BDirectWindow object directly, call Quit() instead. 213 214 Destroying a BDirectWindow involves a few steps to make sure that it 215 is disconnected and cleaned up. 216 217 Set the fConnectionDisabled flag to \c true to prevent DirectConnected() 218 from attempting to reconnect while it's being destroyed. 219 220 next call Hide() and finally Sync() to force the direct window to 221 disconnect from direct access. 222 223 Once these steps are complete you may do your usual destructor work. 224*/ 225 226 227/*! 228 \fn BArchivable* BDirectWindow::Instantiate(BMessage *data) 229 \brief Instantiate window from message \a data. Not implemented. 230*/ 231 232 233/*! 234 \fn status_t BDirectWindow::Archive(BMessage *data, bool deep) const 235 \brief Archive window into message \a data. Not implemented. 236*/ 237 238 239/*! 240 \fn void BDirectWindow::DirectConnected(direct_buffer_info *info) 241 \brief hook function called when your application learns about the state 242 of the graphics display and changes occur. 243 244 This is the heart of BDirectWindow. 245 246 \param info The \c direct_buffer_info struct 247*/ 248 249 250/*! 251 \fn status_t BDirectWindow::GetClippingRegion(BRegion *region, 252 BPoint *origin) const 253 \brief Sets \a region to the current clipping region of the direct window. 254 255 If \a origin is not \c NULL, the \a region is offset by \a origin. 256 257 \warning GetClippingRegion() should only be called from within the 258 DirectConnected() method. If called outside GetClippingRegion() will 259 return \c B_ERROR. 260 261 \param region The clipping region to fill out. 262 \param origin An origin to offset the region by. 263 264 \returns A status code. 265 \retval B_OK Everything went as expected. 266 \retval B_BAD_VALUE \a region was NULL. 267 \retval B_ERROR Window not locked or not in DirectConnected() method. 268 \retval B_NO_MEMORY Not enough memory to fill \a region 269*/ 270 271 272/*! 273 \fn status_t BDirectWindow::SetFullScreen(bool enable) 274 \brief Enables or disables full-screen mode. 275 276 The SupportsWindowMode() method determines whether or not the video card 277 is capable of supporting windowed mode. 278 279 When the window is in full screen mode it will always have the focus and 280 no other window can be in front of it. 281 282 \param enable \c true to enable fullscreen mode, \c false for windowed mode. 283 284 \returns A status code. 285 \retval B_OK Everything went as expected. 286 \retval B_ERROR An error occurred while trying to switch between full screen 287 and windowed mode. 288 289 \see BDirectWindow::SupportsWindowMode() 290*/ 291 292 293/*! 294 \fn bool BDirectWindow::IsFullScreen() const 295 \brief Returns whether the window is in full-screen or windowed mode. 296 297 \returns \c true if in full-screen mode, \c false if in windowed mode. 298*/ 299 300 301/*! 302 \fn static bool BDirectWindow::SupportsWindowMode(screen_id id) 303 \brief Returns whether or not the specified screen supports windowed mode. 304 305 Because this is a static function you don't have to construct a 306 BDirectWindow object to call it. 307 308 \param id The id of the screen you want to check, \c B_MAIN_SCREEN_ID by 309 default. 310 311 \returns \c true if the screen support windowed mode, \c false otherwise. 312*/ 313