Ticket #7994: Screen.dox

File Screen.dox, 16.6 KB (added by jscipione, 8 years ago)

BScreen class documentation taking into account proper underscore method style.

Line 
1/*
2 * Copyright 2011, Haiku inc.
3 * Distributed under the terms of the MIT Licence.
4 *
5 * Documentation by:
6 * Stefano Ceccherini, burton666@libero.it
7 * Axel Dörfler, axeld@pinc-software.de
8 * John Scipione, jscipione@gmail.com
9 * Corresponds to:
10 * /trunk/headers/os/interface/Screen.h rev 42759
11 * /trunk/src/kits/interface/Screen.cpp rev 42759
12 */
13
14
15/*!
16 \file Screen.h
17 \brief Defines the BScreen class and support structures.
18*/
19
20
21/*!
22 \class BScreen
23 \ingroup interface
24 \brief The BScreen class provides methods to retrieve and change display
25 settings.
26
27 Each BScreen object describes one display connected to the computer.
28 Multiple BScreen objects can represent the same physical display.
29
30 \attention Haiku currently supports only a single display. The main
31 screen with id \c B_MAIN_SCREEN_ID contains the origin in its top left
32 corner. Additional displays, when they become supported, will extend
33 the coordinates of the main screen.
34
35 Some utility methods provided by this class are ColorSpace() to get the
36 color space of the screen, Frame() to get the frame rectangle, and ID()
37 to get the identifier of the screen.
38
39 Methods to convert between 8-bit and 32-bit colors are provided by
40 IndexForColor() and ColorForIndex().
41
42 You can also use this class to take a screenshot of the entire screen or
43 a particular portion of it. To take a screenshot use either the GetBitmap()
44 or ReadBitmap() method.
45
46 Furthermore, you can use this class get and set the background color of a
47 workspace. To get the background color call DesktopColor() or to set the
48 background color use SetDesktopColor().
49
50 This class provides methods to get and set the resolution, pixel depth,
51 and color map of a display. To get a list of the display modes supported
52 by the graphics card use the GetModeList() method. You can get and set
53 the screen resolution by calling the GetMode() and SetMode() methods.
54 The color map of the display can be retrieved by calling the ColorMap()
55 method.
56
57 You can use this class to get information about the graphics card and
58 monitor connected to the computer by calling the GetDeviceInfo() and
59 GetMonitorInfo() methods.
60
61 VESA Display Power Management Signaling support allow you to put the
62 monitor into a low-power mode. Call DPMSCapabilites() to check what
63 modes are supported by your monitor. DPMSState() tells you what state
64 your monitor is currently in and SetDPMS() allows you to change it.
65*/
66
67
68/*!
69 \fn BScreen::BScreen(screen_id id)
70 \brief Creates a BScreen object which represents the display
71 connected to the computer with the given screen_id.
72
73 In the current implementation, there is only one display
74 (\c B_MAIN_SCREEN_ID). To be sure that the object was constructed
75 correctly, call IsValid().
76
77 \param id The screen_id of the screen to create a BScreen object from.
78*/
79
80
81/*!
82 \fn BScreen::BScreen(BWindow* window)
83 \brief Creates a BScreen object which represents the display that
84 contains \a window.
85
86 In the current implementation, there is only one display
87 (\c B_MAIN_SCREEN_ID). To be sure that the object was constructed
88 correctly, call IsValid().
89
90 \param window A BWindow object.
91*/
92
93
94/*!
95 \fn BScreen::~BScreen()
96 \brief Frees the resources used by the BScreen object and unlocks the
97 screen.
98
99 \note The main screen object will never go away, even if you disconnect
100 all monitors.
101*/
102
103
104/*!
105 \name Utility Methods
106*/
107
108
109//! @{
110
111
112/*!
113 \fn bool BScreen::IsValid()
114 \brief Checks that the BScreen object represents a real display that is
115 connected to the computer.
116
117 \return \c true if the BScreen object is valid, \c false otherwise.
118*/
119
120
121/*!
122 \fn status_t BScreen::SetToNext()
123 \brief Sets the BScreen object to the next display in the screen list.
124
125 \return \c B_OK if successful, otherwise \c B_ERROR.
126*/
127
128
129/*! \fn color_space BScreen::ColorSpace()
130 \brief Gets the color_space of the display.
131
132 \return \c B_CMAP8, \c B_RGB15, \c B_RGB32, or \c B_NO_COLOR_SPACE
133 if the BScreen object is invalid.
134*/
135
136
137/*!
138 \fn BRect BScreen::Frame()
139 \brief Gets the frame of the screen in the screen's coordinate system.
140
141 For example if the BScreen object points to the main screen with a
142 resolution of 1,366x768 then this method returns
143 BRect(0.0, 0.0, 1365.0, 767.0). If the BScreen object is invalid then
144 this method returns an empty rectangle i.e. BRect(0.0, 0.0, 0.0, 0.0)
145
146 You can set the frame programmatically by calling the SetMode() method.
147
148 \return a BRect frame of the screen in the screen's coordinate system.
149*/
150
151
152/*!
153 \fn screen_id BScreen::ID()
154 \brief Gets the identifier of the display.
155
156 In the current implementation this method returns \c B_MAIN_SCREEN_ID
157 even if the object is invalid.
158
159 \return A screen_id that identifies the screen.
160*/
161
162
163/*!
164 \fn status_t BScreen::WaitForRetrace()
165 \brief Blocks until the monitor has finished its current vertical retrace.
166
167 \return \c B_OK or \c B_ERROR if the screen object is invalid.
168*/
169
170
171/*!
172 \fn status_t BScreen::WaitForRetrace(bigtime_t timeout)
173 \brief Blocks until the monitor has finished its current vertical retrace
174 or until \a timeout has expired.
175
176 \param timeout The amount of time to wait before returning.
177
178 \return \c B_OK if the monitor has retraced in the given \a timeout
179 duration, \c B_ERROR otherwise.
180*/
181
182
183//! @}
184
185
186/*!
187 \name Color Methods
188*/
189
190
191//! @{
192
193
194/*!
195 \fn inline uint8 BScreen::IndexForColor(rgb_color color)
196 \brief Gets the 8-bit color index that most closely matches a
197 32-bit \a color.
198
199 \param color The 32-bit \a color to get the 8-bit index of.
200
201 \return An 8-bit color index in the screen's color_map.
202*/
203
204
205/*!
206 \fn uint8 BScreen::IndexForColor(uint8 red, uint8 green, uint8 blue,
207 uint8 alpha)
208 \brief Gets the 8-bit color index that most closely matches a set of
209 \a red, \a green, \a blue, and \a alpha values.
210
211 \param red The \a red value.
212 \param green The \a green value.
213 \param blue The \a blue value.
214 \param alpha The \a alpha value.
215
216 \return An 8-bit color index in the screen's color_map.
217*/
218
219
220/*!
221 \fn rgb_color BScreen::ColorForIndex(const uint8 index)
222 \brief Gets the 32-bit color representation of an 8-bit color \a index.
223
224 \param index The 8-bit color \a index to convert to a 32-bit color.
225
226 \return A 32-bit rgb_color structure.
227*/
228
229
230/*!
231 \fn uint8 BScreen::InvertIndex(uint8 index)
232 \brief Gets the "Inversion" of an 8-bit color \a index.
233
234 Inverted colors are useful for highlighting.
235
236 \param index The 8-bit color \a index.
237
238 \return An 8-bit color \a index that represents the "Inversion" of the
239 given color in the screen's color_map.
240*/
241
242
243/*!
244 \fn const color_map* BScreen::ColorMap()
245 \brief Gets the color_map of the BScreen.
246
247 \return A pointer to the BScreen object's color_map.
248*/
249
250
251//! @}
252
253
254/*!
255 \name Bitmap Methods
256*/
257
258
259//! @{
260
261
262/*!
263 \fn status_t BScreen::GetBitmap(BBitmap** _bitmap, bool drawCursor,
264 BRect* bounds)
265 \brief Allocates a BBitmap and copies the contents of the screen into it.
266
267 \note GetBitmap() will allocate a BBitmap object for you while
268 ReadBitmap() requires you to pre-allocate a BBitmap object first.
269
270 \note The caller is responsible for freeing the BBitmap object.
271
272 \param _bitmap A pointer to a BBitmap pointer where this method will
273 store the contents of the display.
274 \param drawCursor Specifies whether or not to draw the cursor.
275 \param bounds Specifies the screen area that you want copied. If
276 \a bounds is \c NULL then the entire screen is copied.
277
278 \return \c B_OK if the operation was successful, \c B_ERROR otherwise.
279*/
280
281
282/*!
283 \fn status_t BScreen::ReadBitmap(BBitmap* bitmap, bool drawCursor,
284 BRect* bounds)
285 \brief Copies the contents of the screen into a BBitmap.
286
287 \note ReadBitmap() requires you to pre-allocate a BBitmap object first,
288 while GetBitmap() will allocate a BBitmap object for you.
289
290 \param bitmap A pointer to a pre-allocated BBitmap where this
291 method will store the contents of the display.
292 \param drawCursor Specifies whether or not to draw the cursor.
293 \param bounds Specifies the screen area that you want copied. If
294 \a bounds is \c NULL then the entire screen is copied.
295
296 \return \c B_OK if the operation was successful, \c B_ERROR otherwise.
297*/
298
299
300//! @}
301
302
303/*!
304 \name Desktop Color Methods
305*/
306
307
308//! @{
309
310
311/*!
312 \fn rgb_color BScreen::DesktopColor()
313 \brief Gets the background color of the current workspace.
314
315 \return A 32-bit rgb_color structure containing the background color
316 of the current workspace.
317*/
318
319
320/*!
321 \fn rgb_color BScreen::DesktopColor(uint32 workspace)
322 \brief Gets the background color of the specified \a workspace.
323
324 \param workspace The \a workspace index to get the desktop background
325 color of.
326
327 \return An 32-bit rgb_color structure containing the background color
328 of the specified \a workspace.
329*/
330
331
332/*!
333 \fn void BScreen::SetDesktopColor(rgb_color color, bool stick)
334 \brief Set the background \a color of the current workspace.
335
336 \param color The 32-bit \a color to paint the desktop background.
337 \param stick Whether or not the \a color will stay after a reboot.
338*/
339
340
341/*!
342 \fn void BScreen::SetDesktopColor(rgb_color color, uint32 workspace,
343 bool stick)
344 \brief Set the background \a color of the specified \a workspace.
345
346 \param color The 32-bit \a color to paint the desktop background.
347 \param workspace The \a workspace index to update.
348 \param stick Whether or not the \a color will stay after a reboot.
349*/
350
351
352//! @}
353
354
355/*!
356 \name Display Mode Methods
357
358 The following methods retrieve and alter the display_mode structure
359 of a screen. The display_mode structure contains screen size,
360 pixel depth, and display timings settings.
361*/
362
363
364//! @{
365
366
367/*!
368 \fn status_t BScreen::ProposeMode(display_mode* target,
369 const display_mode* low,
370 const display_mode* high)
371 \brief Adjust the \a target mode to make it a supported mode.
372
373 The list of supported modes for the graphics card is supplied by
374 the GetModeList() method.
375
376 \param target The mode you want adjust.
377 \param low The lower display mode limit.
378 \param high The higher display mode limit.
379
380 \retval B_OK if \a target is supported and falls within the
381 \a low and \a high limits.
382 \retval B_BAD_VALUE if \a target is supported but does not
383 fall within the \a low and \a high limits.
384 \retval B_ERROR if the target mode isn't supported.
385*/
386
387
388/*!
389 \fn status_t BScreen::GetModeList(display_mode** _modeList, uint32* _count)
390 \brief Allocates and returns a list of the display modes supported by the
391 graphics card into \a _modeList.
392
393 \warning The monitor may not be able to display all of the modes that
394 GetModeList() retrieves.
395
396 \note The caller is responsible for freeing the display_mode object.
397
398 \param _modeList A pointer to a display_mode pointer, where the function
399 will allocate an array of display_mode structures.
400 \param _count A pointer to an integer used to store the count of
401 available display modes.
402
403 \retval B_OK if the operation was successful.
404 \retval B_ERROR if \a modeList or \a count is invalid.
405 \retval B_ERROR for all other errors.
406*/
407
408
409/*!
410 \fn status_t BScreen::GetMode(display_mode* mode)
411 \brief Fills out the display_mode struct from the current workspace.
412
413 \param mode A pointer to a display_mode struct to copy into.
414
415 \retval B_OK if the operation was successful.
416 \retval B_BAD_VALUE if \a mode is invalid.
417 \retval B_ERROR for all other errors.
418*/
419
420
421/*!
422 \fn status_t BScreen::GetMode(uint32 workspace, display_mode* mode)
423 \brief Fills out the display_mode struct from the specified
424 \a workspace.
425
426 \param workspace The index of the \a workspace to query.
427 \param mode A pointer to a display_mode structure to copy into.
428
429 \retval B_OK if the operation was successful
430 \retval B_BAD_VALUE if \a mode is invalid.
431 \retval B_ERROR for all other errors.
432*/
433
434
435/*!
436 \fn status_t BScreen::SetMode(display_mode* mode, bool makeDefault)
437 \brief Sets the screen in the current workspace to the given \a mode.
438
439 \param mode A pointer to a display_mode struct.
440 \param makeDefault Whether or not \a mode is set as the default.
441
442 \return \c B_OK if the operation was successful, \c B_ERROR otherwise.
443*/
444
445
446/*!
447 \fn status_t BScreen::SetMode(uint32 workspace, display_mode* mode,
448 bool makeDefault)
449 \brief Set the screen in the specified \a workspace to the given \a mode.
450
451 \param workspace The index of the workspace to set the \a mode of.
452 \param mode A pointer to a display_mode struct.
453 \param makeDefault Whether or not the \a mode is set as the default
454 for the specified \a workspace.
455
456 \return \c B_OK if the operation was successful, \c B_ERROR otherwise.
457*/
458
459
460//! @}
461
462
463/*!
464 \name Display and Graphics Card Info Methods
465*/
466
467
468//! @{
469
470
471/*!
472 \fn status_t BScreen::GetDeviceInfo(accelerant_device_info* info)
473 \brief Fills out the \a info struct with information about a graphics card.
474
475 \param info An accelerant_device_info struct to store the device
476 \a info.
477
478 \retval B_OK if the operation was successful.
479 \retval B_BAD_VALUE if \a info is invalid.
480 \retval B_ERROR for all other errors.
481*/
482
483
484/*!
485 \fn status_t BScreen::GetMonitorInfo(monitor_info* info)
486 \brief Fills out the \a info struct with information about a monitor.
487
488 \param info A monitor_info struct to store the monitor \a info.
489
490 \retval B_OK if the operation was successful.
491 \retval B_BAD_VALUE if \a info is invalid.
492 \retval B_ERROR for all other errors.
493*/
494
495
496/*!
497 \fn status_t BScreen::GetPixelClockLimits(display_mode* mode,
498 uint32* _low, uint32* _high)
499 \brief Gets the minimum and maximum pixel clock rates that are possible
500 for the specified \a mode.
501
502 \param mode A pointer to a display_mode structure.
503 \param _low A pointer to a uint32 where the method stores the lowest
504 available pixel clock.
505 \param _high A pointer to a uint32 where the method stores the highest
506 available pixel clock.
507
508 \retval B_OK if the operation was successful.
509 \retval B_BAD_VALUE if \a mode, \a low, or \a high is invalid.
510 \retval B_ERROR for all other errors.
511*/
512
513
514/*!
515 \fn status_t BScreen::GetTimingConstraints(display_timing_constraints*
516 constraints)
517 \brief Fills out the \a constraints structure with the timing constraints
518 of the current display mode.
519
520 \param constraints A pointer to a display_timing_constraints structure
521 to store the timing constraints.
522
523 \retval B_OK if the operation was successful.
524 \retval B_BAD_VALUE if \a constraints is invalid.
525 \retval B_ERROR for all other errors.
526*/
527
528
529//! @}
530
531
532/*!
533 \name VESA Display Power Management Signaling Settings
534
535 VESA Display Power Management Signaling (or DPMS) is a standard from the
536 VESA consortium for managing the power usage of displays through the
537 graphics card. DPMS allows you to shut off the display after the computer
538 has been unused for some time to save power.
539
540 DPMS states include:
541 - \c B_DPMS_ON Normal display operation.
542 - \c B_DPMS_STAND_BY Image not visible normal operation and returns to
543 normal after ~1 second.
544 - \c B_DPMS_SUSPEND Image not visible, returns to normal after ~5
545 seconds.
546 - \c B_DPMS_OFF Image not visible, display is off except for power to
547 monitoring circuitry. Returns to normal after ~8-20 seconds.
548
549 Power usage in each of the above states depends on the monitor used. CRT
550 monitors typically receive larger power savings than LCD monitors in
551 low-power states.
552*/
553
554
555//! @{
556
557
558/*!
559 \fn status_t BScreen::SetDPMS(uint32 dpmsState)
560 \brief Sets the VESA Display Power Management Signaling (DPMS) state for
561 the display.
562
563 \param dpmsState The DPMS state to set.
564 valid values are:
565 - \c B_DPMS_ON
566 - \c B_DPMS_STAND_BY
567 - \c B_DPMS_SUSPEND
568 - \c B_DPMS_OFF
569
570 \return \c B_OK if the operation was successful, otherwise an error code.
571*/
572
573
574/*!
575 \fn uint32 BScreen::DPMSState()
576 \brief Gets the current VESA Display Power Management Signaling (DPMS)
577 state of the screen.
578
579 \return The current VESA Display Power Management Signaling (DPMS) state
580 of the display or 0 in the case of an error.
581*/
582
583
584
585/*!
586 \fn uint32 BScreen::DPMSCapabilites()
587 \brief Gets the VESA Display Power Management Signaling (DPMS)
588 modes that the display supports as a bit mask.
589
590 - \c B_DPMS_ON is worth 1
591 - \c B_DPMS_STAND_BY is worth 2
592 - \c B_DPMS_SUSPEND is worth 4
593 - \c B_DPMS_OFF is worth 8
594
595 \return A bit mask of the VESA Display Power Management Signaling (DPMS)
596 modes that the display supports or 0 in the case of an error.
597*/
598
599
600//! @}
601
602
603/*!
604 \name Deprecated methods
605*/
606
607
608//! @{
609
610
611/*!
612 \fn BPrivate::BPrivateScreen* BScreen::private_screen()
613 \brief Returns the BPrivateScreen used by the BScreen object.
614
615 \return A pointer to the BPrivateScreen class internally used by the BScreen
616 object.
617*/
618
619
620/*!
621 \fn status_t BScreen::ProposeDisplayMode(display_mode* target,
622 const display_mode* low,
623 const display_mode* high)
624 \brief Deprecated, use ProposeMode() instead.
625*/
626
627
628/*!
629 \fn void* BScreen::BaseAddress()
630 \brief Returns the base address of the frame buffer.
631*/
632
633
634/*!
635 \fn uint32 BScreen::BytesPerRow()
636 \brief Returns the bytes per row of the frame buffer.
637*/
638
639
640//! @}