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

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

Screen Object class. More...

## Detailed Description

Screen Object class.

## Public Types
using | RenderCallback = function<Sint32(Sint32 iMode)>
| Callback used by Screen::setRenderCallback().

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request screen object information.
const string & | getName () const override
| Get the name.
Sint32 | getID () const override
| Get the ID.
Sint32 | show ()
| Show the screen.
bool | hide ()
| Hide the screen.
eGeneralStatus | status () const
| Get the screen status.
Sint32 | setIcon (SDL_Surface *pIcon)
| Set an icon.
Sint32 | 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.
Sint32 | setMode (eConfigScreenMode eCSM)
| Set the screen mode.
eConfigScreenMode | getMode () const
| Get the screen mode.
Sint32 | 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=0, Sint32 iHeight=0, 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 *pClipRect)
| Set clipping rect.
bool | getClipRect (SDL_Rect *pClipRect) const
| 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.
Sint32 | saveSnapshot (const string &sFile)
| Save a 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 (RenderCallback fnCallback)
| Set a callback function for rendering graphics at Render Frame Rate.
bool | fadeToColor (Uint8 iR, Uint8 iG, Uint8 iB, Sint32 iTime, SDL_FRect *pDst=nullptr)
| Perform a fade effect of this screen to the given color.
bool | fadeToImage (Sint32 idImage, Sint32 iTime, SDL_FRect *pDst=nullptr, SDL_FRect *pSrc=nullptr)
| Perform a fade effect of this screen to the given Image handle.

## Member Typedef Documentation

## ◆ RenderCallback

using CRM64Pro::Screen::RenderCallback = function<Sint32(Sint32 iMode)>

Callback used by Screen::setRenderCallback().

The iMode parameter is set to 1 right after a Logic Frame update.

## 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 | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ getName()

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

Get the name.

Returns
  The object name.

## ◆ getID()

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

Get the ID.

Returns
  Object ID.

## ◆ show()

Sint32 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
  0 on success, or a negative error code 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
  ::GS_DISABLED if uninitialized, ::GS_HIDDEN if initialized but hidden, or ::GS_SHOWN if initialized and visible.

## ◆ setIcon()

Sint32 CRM64Pro::Screen::setIcon | ( | SDL_Surface * | pIcon | ) |

Set an icon.

Sets the window icon. After this method returns successfully, the caller may release the source surface. The screen may be initialized or uninitialized when this method is called.

Parameters

  pIcon | SDL_Surface pointer with the icon.

Returns
  0 on success, or a negative error code on failure.

## ◆ setDriver()

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

Set the renderer driver.

Parameters

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

Returns
  0 on success, or a negative error code 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 stores the requested 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()

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

Set the screen mode.

Parameters

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

Returns
  0 on success, or a negative error code 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 Image::optimize())
  - Recreate the screen (window and renderer)
  - When entering fullscreen mode, if resolution differs from application size and no logical presentation mode is set, a default logical presentation mode 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()

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

Set the size of the screen.

Parameters

  iWidth | screen width.
  iHeight | screen height.

Returns
  0 on success, or a negative error code 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 = 0,
|  | Sint32 | iHeight = 0,
|  | 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. Use 0 to keep the current width.
  iHeight | Logical presentation height. Use 0 to keep the current height.
  eSDL_RLP | set the logical presentation mode. Check SDL_RendererLogicalPresentation for further information. By default, it is set to SDL_LOGICAL_PRESENTATION_DISABLED.

Note
  Negative width or height values are invalid.

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 * | pClipRect | ) |

Set clipping rect.

Parameters

  pClipRect | 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 * | pClipRect | ) | const

Get clipping rect.

Parameters

  pClipRect | 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
  Borrowed pointer to the SDL_Window, or nullptr on failure.

Note
  The returned pointer must not be destroyed. It remains valid while the Screen exists.

Warning
  The returned pointer is mutable and is provided for SDL interop only.

## ◆ getRenderer()

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

Get the SDL_Renderer associated to this screen.

Returns
  Borrowed pointer to the SDL_Renderer, or nullptr on failure.

Note
  The returned pointer must not be destroyed. It remains valid while the Screen exists.

Warning
  The returned pointer is mutable and is provided for SDL interop only.

## ◆ getSnapshot()

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

Get a SDL_Surface with a screen snapshot.

Returns
  Owned pointer to the SDL_Surface, or nullptr on failure.

Note
  The returned surface must be released with SDL_DestroySurface().
  Getting a screen snapshot is quite slow.

## ◆ saveSnapshot()

Sint32 CRM64Pro::Screen::saveSnapshot | ( | const string & | sFile | ) |

Save a screen snapshot to an external PNG file.

Parameters

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

Returns
  0 on success, or a negative error code 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 | ( | RenderCallback | fnCallback | ) |

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

Parameters

  fnCallback | Callback invoked at Render Frame Rate, or an empty callback to remove the current callback. The iMode parameter is set to 1 right after a Logic Frame update.

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 advanced methods for details.

## ◆ fadeToColor()

bool CRM64Pro::Screen::fadeToColor | ( | Uint8 | iR,
|  | Uint8 | iG,
|  | Uint8 | iB,
|  | Sint32 | iTime,
|  | SDL_FRect * | pDst = 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).
  pDst | 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 * | pDst = nullptr,
|  | SDL_FRect * | pSrc = nullptr )

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

Parameters

  idImage | Image handle.
  iTime | duration in milliseconds (minimum 50ms, maximum 10000ms).
  pDst | the destination SDL_FRect structure or nullptr for whole screen (default).
  pSrc | 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).