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