docs/user/game/DirectWindow.dox

   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 */