| CRM64Pro GDK v0.17.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
CRM64Pro::Screen
Core modules » Config

Screen Object class. More...

## Detailed Description

Screen Object class.

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request screen object information.
const string & | getName () const override
| Get the name.
Uint32 | getID () const override
| Get the ID.
bool | show ()
| Show the screen.
bool | hide ()
| Hide the screen.
eGeneralStatus | status () const
| Get the screen status.
bool | setIcon (SDL_Surface *suIcon)
| Set an icon.
bool | setDriver (eConfigRendererDriver eCRD)
| Set the renderer driver.
eConfigRendererDriver | getDriver () const
| Get the renderer driver.
eConfigRendererDriver | getDriverInUse () const
| Get the renderer driver in use.
bool | setVSync (bool bEnabled)
| Set the VSync mode.
bool | getVSync () const
| Get current VSync mode.
bool | setMode (eConfigScreenMode eCSM)
| Set the screen mode.
eConfigScreenMode | getMode () const
| Get the screen mode.
bool | setSize (Sint32 iWidth, Sint32 iHeight)
| Set the size of the screen.
Sint32 | getWidth () const
| Get the screen width.
Sint32 | getHeight () const
| Get the screen height.
bool | setLogicalPresentation (Sint32 iWidth, Sint32 iHeight, SDL_RendererLogicalPresentation eSDL_RLP=SDL_LOGICAL_PRESENTATION_DISABLED)
| Set the logical presentation size of the screen.
bool | getLogicalPresentation (Sint32 *iWidth=nullptr, Sint32 *iHeight=nullptr, SDL_RendererLogicalPresentation *eSDL_RLP=nullptr) const
| Get the logical presentation size of the screen.
bool | setPosition (Sint32 iX, Sint32 iY)
| Set the position.
Sint32 | getX () const
| Get the screen X position.
Sint32 | getY () const
| Get the screen Y position.
bool | setClipRect (SDL_Rect *rClip)
| Set clipping rect.
bool | getClipRect (SDL_Rect *rClip)
| Get clipping rect.
bool | isClipRectEnabled () const
| Check if clipping rect is enabled.
bool | setTitle (const string &sName)
| Set the title.
const string & | getTitle () const
| Get the title.
bool | setBorder (bool bEnabled)
| Set the border for the screen.
bool | getBorder () const
| Get the border for the screen.
SDL_Window * | getWindow ()
| Get the SDL_Window associated to this screen.
SDL_Renderer * | getRenderer ()
| Get the SDL_Renderer associated to this screen.
SDL_Surface * | getSnapshot ()
| Get a SDL_Surface with a screen snapshot.
bool | getSnapshot (const string &sFile)
| Save the screen snapshot to an external PNG file.
bool | clear (Uint8 iR=0, Uint8 iG=0, Uint8 iB=0, Uint8 iA=255)
| Clear the screen.
bool | setRenderCallback (Sint32(*myRenderFunc)(Sint32 iMode, void *pObj), void *pObj=nullptr)
| Set a callback function for rendering your graphics at Render Frame Rate.
bool | fadeToColor (Uint8 iR, Uint8 iG, Uint8 iB, Sint32 iTime, SDL_FRect *rDst=nullptr)
| Perform a fade effect of this screen to the given color.
bool | fadeToImage (Sint32 idImage, Sint32 iTime, SDL_FRect *rDst=nullptr, SDL_FRect *rSrc=nullptr)
| Perform a fade effect of this screen to the given Image handler.

## Member Function Documentation

## ◆ info()

bool CRM64Pro::Screen::info | ( | Sint32 | iMode = 0 | ) |
| override

Request screen object information.

Writes screen information to the default log.

Parameters

  iMode | unused for the time being.

Returns
  true on success or false on failure.

## ◆ getName()

const string & CRM64Pro::Screen::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Uint32 CRM64Pro::Screen::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ show()

bool CRM64Pro::Screen::show | ( |  | ) |

Show the screen.

Makes the associated window visible. If the screen was not previously shown, it creates all required internal attributes and initializes the screen. If the screen was hidden, it is shown again without altering existing attributes.

Returns
  true on success or false on failure.

## ◆ hide()

bool CRM64Pro::Screen::hide | ( |  | ) |

Hide the screen.

When hidden, the associated window is hidden but all attributes are kept. The screen can be shown again using show() or closed using ConfigMgr::close().

Returns
  true on success or false on failure.

## ◆ status()

eGeneralStatus CRM64Pro::Screen::status | ( |  | ) | const

Get the screen status.

Returns
  ::C64_STATUS_DISABLED if uninitialized, ::C64_STATUS_HIDDEN if initialized but hidden, or ::C64_STATUS_SHOWN if initialized and visible.

## ◆ setIcon()

bool CRM64Pro::Screen::setIcon | ( | SDL_Surface * | suIcon | ) |

Set an icon.

Sets the window icon. Once called, you can free the used surface as it is no longer needed. The screen can be initialized or not when calling this method.

Parameters

  suIcon | SDL_Surface pointer with the icon.

Returns
  true on success, or false on failure.

## ◆ setDriver()

bool CRM64Pro::Screen::setDriver | ( | eConfigRendererDriver | eCRD | ) |

Set the renderer driver.

Parameters

  eCRD | screen renderer driver. Check ::eConfigRendererDriver enum for details.

Returns
  true on success or false on failure.

Note
  If the screen was already initialized, it will be destroyed and re-created with the new driver. All associated resources (textures) will be lost/recreated.
  If the screen was not initialized, this method will just set the desired driver for the next initialization.

## ◆ getDriver()

eConfigRendererDriver CRM64Pro::Screen::getDriver | ( |  | ) | const

Get the renderer driver.

Returns the renderer driver set by default or by setDriver() method. Note that it could differ from the actual driver in use. For example, CRD_DEFAULT may resolve to CRD_SOFTWARE, CRD_OPENGL, etc. Use getDriverInUse() to get the actual driver in use.

Returns
  ::eConfigRendererDriver enum value on success or CRD_ERROR on failure.

## ◆ getDriverInUse()

eConfigRendererDriver CRM64Pro::Screen::getDriverInUse | ( |  | ) | const

Get the renderer driver in use.

Returns the renderer driver currently in use. The screen must be initialized. Use getDriver() to get the driver set by default or by setDriver().

Returns
  ::eConfigRendererDriver enum value on success or CRD_ERROR on failure.

## ◆ setVSync()

bool CRM64Pro::Screen::setVSync | ( | bool | bEnabled | ) |

Set the VSync mode.

Parameters

  bEnabled | false to disable, true to enable. Common monitor refresh rates are 60, 70, 75, 120 or 155.

Returns
  true on success or false on failure.

## ◆ getVSync()

bool CRM64Pro::Screen::getVSync | ( |  | ) | const

Get current VSync mode.

Returns
  false if VSync is disabled, true if it is enabled.

## ◆ setMode()

bool CRM64Pro::Screen::setMode | ( | eConfigScreenMode | eCSM | ) |

Set the screen mode.

Parameters

  eCSM | screen mode. Check ::eConfigScreenMode enum for details.

Returns
  true on success or false on failure.

Note
  Changing the mode will:
  - Destroy all created textures for this screen (auto-rebuilt when needed, or rebuild in advance with ImageMgr::optimize() or Screen::optimize())
  - Recreate the screen (window and renderer)
  - When entering fullscreen mode, if resolution differs from application size and no logical presentation mode is set, one is set automatically
  - When entering window mode, if resolution and logical size match, presentation mode is disabled

## ◆ getMode()

eConfigScreenMode CRM64Pro::Screen::getMode | ( |  | ) | const

Get the screen mode.

Returns
  ::eConfigScreenMode enum value on success.

## ◆ setSize()

bool CRM64Pro::Screen::setSize | ( | Sint32 | iWidth,
|  | Sint32 | iHeight )

Set the size of the screen.

Parameters

  iWidth | screen width.
  iHeight | screen height.

Returns
  true on success or false on failure.

Note
  The size cannot be changed in ::CSM_FULLSCREEN or ::CSM_FULLSCREENEXCLUSIVE modes.

## ◆ getWidth()

Sint32 CRM64Pro::Screen::getWidth | ( |  | ) | const

Get the screen width.

Returns
  The screen width in pixels.

## ◆ getHeight()

Sint32 CRM64Pro::Screen::getHeight | ( |  | ) | const

Get the screen height.

Returns
  The screen height in pixels.

## ◆ setLogicalPresentation()

bool CRM64Pro::Screen::setLogicalPresentation | ( | Sint32 | iWidth,
|  | Sint32 | iHeight,
|  | SDL_RendererLogicalPresentation | eSDL_RLP = SDL_LOGICAL_PRESENTATION_DISABLED )

Set the logical presentation size of the screen.

Allows a device independent resolution rendering.

Parameters

  iWidth | logical presentation width. A negative value for not modifying this value.
  iHeight | logical presentation height. A negative value for not modifying this value.
  eSDL_RLP | set the logical presentation mode. Check SDL_RendererLogicalPresentation for further information. By default, it is set to SDL_LOGICAL_PRESENTATION_DISABLED.

Returns
  true on success or false on failure.

## ◆ getLogicalPresentation()

bool CRM64Pro::Screen::getLogicalPresentation | ( | Sint32 * | iWidth = nullptr,
|  | Sint32 * | iHeight = nullptr,
|  | SDL_RendererLogicalPresentation * | eSDL_RLP = nullptr ) const

Get the logical presentation size of the screen.

Returns the logical presentation size and mode for this screen.

Parameters

  iWidth | an integer pointer filled in with logical presentation width. If nullptr, this value is not retrieved.
  iHeight | an integer pointer filled in with logical presentation height. If nullptr, this value is not retrieved.
  eSDL_RLP | a SDL_RendererLogicalPresentation enum pointer filled in with the logical presentation mode. If nullptr, this value is not retrieved.

Returns
  true on success, or false on failure.

## ◆ setPosition()

bool CRM64Pro::Screen::setPosition | ( | Sint32 | iX,
|  | Sint32 | iY )

Set the position.

Parameters

  iX | screen X position.
  iY | screen Y position.

Returns
  true on success or false on failure.

## ◆ getX()

Sint32 CRM64Pro::Screen::getX | ( |  | ) | const

Get the screen X position.

Returns
  The screen X position in pixels.

## ◆ getY()

Sint32 CRM64Pro::Screen::getY | ( |  | ) | const

Get the screen Y position.

Returns
  The screen Y position in pixels.

## ◆ setClipRect()

bool CRM64Pro::Screen::setClipRect | ( | SDL_Rect * | rClip | ) |

Set clipping rect.

Parameters

  rClip | pointer to SDL_Rect structure with the clipping area, or nullptr to disable clipping.

Returns
  true on success or false on failure.

## ◆ getClipRect()

bool CRM64Pro::Screen::getClipRect | ( | SDL_Rect * | rClip | ) |

Get clipping rect.

Parameters

  rClip | pointer to SDL_Rect structure filled in with current clipping area when clipping is enabled.

Returns
  true if clipping is enabled, or false if clipping is disabled.

See also
  isClipRectEnabled()

## ◆ isClipRectEnabled()

bool CRM64Pro::Screen::isClipRectEnabled | ( |  | ) | const

Check if clipping rect is enabled.

Returns
  true if clipping is enabled, false if it is disabled.

## ◆ setTitle()

bool CRM64Pro::Screen::setTitle | ( | const string & | sName | ) |

Set the title.

Sets the window title. The screen can be initialized or not when calling this method.

Parameters

  sName | title for the screen.

Returns
  true on success or false on failure.

## ◆ getTitle()

const string & CRM64Pro::Screen::getTitle | ( |  | ) | const

Get the title.

Returns
  The window title.

## ◆ setBorder()

bool CRM64Pro::Screen::setBorder | ( | bool | bEnabled | ) |

Set the border for the screen.

The screen border is only visible on ::CSM_WINDOW mode so it only has effect on this mode.

Parameters

  bEnabled | false for disabling and true for enabling it.

Returns
  true on success or false on failure.

## ◆ getBorder()

bool CRM64Pro::Screen::getBorder | ( |  | ) | const

Get the border for the screen.

Returns
  false if the border is disabled, true if it is enabled.

## ◆ getWindow()

SDL_Window * CRM64Pro::Screen::getWindow | ( |  | ) |

Get the SDL_Window associated to this screen.

Returns
  a pointer to the SDL_Window or nullptr on failure.

Warning
  Use carefully this method and in general, only for read-only checks.

## ◆ getRenderer()

SDL_Renderer * CRM64Pro::Screen::getRenderer | ( |  | ) |

Get the SDL_Renderer associated to this screen.

Returns
  a pointer to the SDL_Renderer or nullptr on failure.

Warning
  Use carefully this method and in general, only for read-only checks.

## ◆ getSnapshot() [1/2]

SDL_Surface * CRM64Pro::Screen::getSnapshot | ( |  | ) |

Get a SDL_Surface with a screen snapshot.

Returns
  a pointer to the SDL_Surface or nullptr on failure. The created surface must be freed by the user to avoid a resource leak.

Note
  Getting a screen snapshot is quite slow.

## ◆ getSnapshot() [2/2]

bool CRM64Pro::Screen::getSnapshot | ( | const string & | sFile | ) |

Save the screen snapshot to an external PNG file.

Parameters

  sFile | string containing the [directory]+filename+[extension].

Returns
  true on success or false on failure.

Note
  Getting a screen snapshot is quite slow.

## ◆ clear()

bool CRM64Pro::Screen::clear | ( | Uint8 | iR = 0,
|  | Uint8 | iG = 0,
|  | Uint8 | iB = 0,
|  | Uint8 | iA = 255 )

Clear the screen.

Parameters

  iR | The red color value. Default is 0.
  iG | The green color value. Default is 0.
  iB | The blue color value. Default is 0.
  iA | The alpha value. Default is 255.

Returns
  true on success or false on failure.

## ◆ setRenderCallback()

bool CRM64Pro::Screen::setRenderCallback | ( | Sint32(* | myRenderFunc )(Sint32 iMode, void *pObj),
|  | void * | pObj = nullptr )

Set a callback function for rendering your graphics at Render Frame Rate.

Parameters

  myRenderFunc | pointer to your graphics rendering function or nullptr to remove current assigned function. The iMode parameter of the callback is set to 1 right after a Logic Frame update.
  pObj | pointer to user data passed to the callback function. By default nullptr.

Returns
  true on success or false on failure.

Note
  There are alternative ways of rendering graphics at Render Frame Rate, but using a callback function is recommended. See Rendering your graphics: standard and advance methods for details.

## ◆ fadeToColor()

bool CRM64Pro::Screen::fadeToColor | ( | Uint8 | iR,
|  | Uint8 | iG,
|  | Uint8 | iB,
|  | Sint32 | iTime,
|  | SDL_FRect * | rDst = nullptr )

Perform a fade effect of this screen to the given color.

Parameters

  iR | The red color value.
  iG | The green color value.
  iB | The blue color value.
  iTime | duration in milliseconds (minimum 50ms, maximum 10000ms).
  rDst | the destination SDL_FRect structure or nullptr for whole screen (default).

Returns
  true on success or false on failure.

Note
  This method blocks execution until the effect completes. Best suited for short durations (up to 1000ms).

## ◆ fadeToImage()

bool CRM64Pro::Screen::fadeToImage | ( | Sint32 | idImage,
|  | Sint32 | iTime,
|  | SDL_FRect * | rDst = nullptr,
|  | SDL_FRect * | rSrc = nullptr )

Perform a fade effect of this screen to the given Image handler.

Parameters

  idImage | Image handler.
  iTime | duration in milliseconds (minimum 50ms, maximum 10000ms).
  rDst | the destination SDL_FRect structure or nullptr for whole screen (default).
  rSrc | the image source SDL_FRect structure or nullptr for whole image (default).

Returns
  true on success or false on failure.

Note
  This method blocks execution until the effect completes. Best suited for short durations (up to 1000ms).