OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::VulkanAndroidWindow Class Referencefinal

#include <OgreVulkanAndroidWindow.h>

+ Inheritance diagram for Ogre::VulkanAndroidWindow:

Public Types

enum  FramePacingSwappyModes { PipelineForcedOn , AutoVSyncInterval_PipelineForcedOn , AutoVSyncInterval_AutoPipeline }
- Public Types inherited from Ogre::VulkanWindowSwapChainBased
enum  Backend { BackendX11 = 1u << 0u }
enum  SwapchainStatus { SwapchainAcquired , SwapchainUsedInRendering , SwapchainPendingSwap , SwapchainReleased }

Public Member Functions

 VulkanAndroidWindow (const String &title, uint32 width, uint32 height, bool fullscreenMode)
 ~VulkanAndroidWindow () override
void _initialize (TextureGpuManager *textureGpuManager, const NameValuePairList *miscParams) override
void _setVisible (bool visible) override
 Internal method to notify the window it has been obscured or minimized. More...
void destroy () override
void getCustomAttribute (IdString name, void *pData) override
bool isHidden () const override
 Indicates whether the window was set to hidden (not displayed) More...
bool isVisible () const override
void reposition (int32 left, int32 top) override
void requestResolution (uint32 width, uint32 height) override
 Requests a change in resolution. More...
void setHidden (bool hidden) override
 Hide (or show) the window. More...
void setJniProvider (AndroidJniProvider *provider)
 User must call this function before initializing if built with OGRE_VULKAN_USE_SWAPPY. More...
void setNativeWindow (ANativeWindow *nativeWindow)
 If the ANativeWindow changes, allows to set a new one. More...
void setVSync (bool vSync, uint32 vSyncInterval) override
 Turns VSync on/off. More...
void windowMovedOrResized () override
 Notify that the window has been resized. More...
- Public Member Functions inherited from Ogre::VulkanWindowSwapChainBased
 VulkanWindowSwapChainBased (const String &title, uint32 width, uint32 height, bool fullscreenMode)
 ~VulkanWindowSwapChainBased () override
void _swapBuffers (VkSemaphore queueFinishSemaphore)
 Actually performs present. More...
void acquireNextSwapchain ()
bool canDownloadData () const override
 Returns true if you can download to CPU (i.e. More...
PixelFormatGpu chooseSurfaceFormat (bool hwGamma)
VkSemaphore getImageAcquiredSemaphore ()
 Returns null if getImageAcquiredSemaphore has already been called during this frame. More...
size_t getNumSwapchains () const
VkImage getSwapchainImage (size_t idx) const
bool isClosed () const override
 Indicates whether the window has been closed by the user. More...
void parseSharedParams (const NameValuePairList *miscParams)
void setWantsToDownload (bool bWantsToDownload) override
 On Metal you must call this function and set it to true in order to take pictures. More...
void swapBuffers () override
 Tells our VulkanDevice that the next commitAndNextCommandBuffer call should present us Calling swapBuffers during the command buffer that is rendering to us is key for good performance; otherwise Ogre may split the commands that render to this window and the command that presents this window into two queue submissions. More...
- Public Member Functions inherited from Ogre::VulkanWindow
 VulkanWindow (const String &title, uint32 width, uint32 height, bool fullscreenMode)
void _initialize (TextureGpuManager *textureGpuManager) override
virtual void _initialize (TextureGpuManager *textureGpuManager, const NameValuePairList *ogre_nullable miscParams)=0
void _setDevice (VulkanDevice *device)
- Public Member Functions inherited from Ogre::Window
 Window (const String &title, uint32 widthPt, uint32 heightPt, bool fullscreenMode)
virtual ~Window ()
void _setPrimary ()
 Indicates that this is the primary window. More...
bool getBorderless () const
TextureGpu *ogre_nullable getDepthBuffer () const
uint32 getFrequencyDenominator () const
uint32 getFrequencyNumerator () const
uint32 getHeight () const
virtual void getMetrics (uint32 &width, uint32 &height, int32 &left, int32 &top) const
 Overloaded version of getMetrics from RenderTarget, including extra details specific to windowing systems. More...
PixelFormatGpu getPixelFormat () const
uint32 getRequestedHeightPt () const
uint32 getRequestedWidthPt () const
SampleDescription getSampleDescription () const
TextureGpu *ogre_nullable getStencilBuffer () const
TextureGpu *ogre_nullable getTexture () const
 WARNING: Attempting to change the TextureGpu (e.g. More...
const StringgetTitle () const
virtual float getViewPointToPixelScale () const
 Many windowing systems that support HiDPI displays use special points to specify size of the windows and controls, so that windows and controls with hardcoded sizes does not become too small on HiDPI displays. More...
bool getVSync () const
uint32 getVSyncInterval () const
uint32 getWidth () const
bool isFocused () const
bool isFullscreen () const
 Returns true if we are currently in fullscreen mode. More...
virtual bool isManualSwapRelease () const
 Returns the value set by setManualSwapRelease when supported. More...
bool isMultisample () const
bool isPrimary () const
virtual void performManualRelease ()
 See Window::setManualSwapRelease. More...
virtual void requestFullscreenSwitch (bool goFullscreen, bool borderless, uint32 monitorIdx, uint32 widthPt, uint32 heightPt, uint32 frequencyNumerator, uint32 frequencyDenominator)
 Requests to toggle between fullscreen and windowed mode. More...
virtual void setBorderless (bool borderless)
virtual void setFocused (bool focused)
virtual void setFsaa (const String &fsaa)
 Set the FSAA mode to be used if hardware support it. More...
virtual void setManualSwapRelease (bool bManualRelease)
 Metal doesn't want us to hold on to a drawable after presenting. More...
virtual void setTitle (const String &title)
bool wantsToGoFullscreen () const
 Returns true if we are in windowed mode right now, but want to go fullscreen. More...
bool wantsToGoWindowed () const
 Returns true if we are in fullscreen mode right now, but want to go windowed mode. More...

Static Public Member Functions

static const char * getRequiredExtensionName ()
static void setFramePacingSwappyAutoMode (FramePacingSwappyModes mode)
 Sets Swappy auto swap interval and auto pipeline modes. More...

Additional Inherited Members

- Public Attributes inherited from Ogre::VulkanWindowSwapChainBased
bool mCanDownloadData
bool mClosed
bool mEnablePreTransform
bool mLowestLatencyVSync
bool mRebuildingSwapchain
bool mSuboptimal
VkSurfaceKHR mSurfaceKHR
VkSwapchainKHR mSwapchain
FastArray< VkImage > mSwapchainImages
VkSemaphore mSwapchainSemaphore
 Note: We need a semaphore per frame, not per swapchain. More...
SwapchainStatus mSwapchainStatus

Member Enumeration Documentation

◆ FramePacingSwappyModes


Try to honour the vSyncInterval set via Window::setVSync.

Pipelining is always on. This is the same behavior as Desktop APIs (e.g. D3D11, Vulkan & GL on Windows and Linux).


Autocalculate vSyncInterval (see Window::setVSync).

The autocalculated vSyncInterval should be in the range [vSyncInterval; inf) where vSyncInterval is the value passed to Window::setVSync.

While this sounds convenient, beware that Swappy will often downgrade vSyncInterval until it finds something that can be met & sustained. That means if your game runs between 40fps and 60fps on a 60hz screen, after some time swappy will downgrade vSyncInterval to 2 so that the game render at perfect 30fps.

This may result in a better experience considering framerates jump a lot due to thermal throttling on phones. But it may also cause undesired or unexplainable "locked to 30fps for no aparent reason for a considerable time".

Pipelining is always on.


Autocalculate vSyncInterval (see Window::setVSync).

See AutoSwapInterval_PipelineForcedOn documentation.

Use this mode when you know you have extremely fast render times (e.g. CPU + GPU time is below half the monitor's refresh time, e.g. it takes <= 8ms to render in a 60hz screen) which means Swappy will eventually disable pipelining.

A disabled pipeline minimizes latency because the whole thing presented is ASAP by the time the next VBLANK interval arrives.

Constructor & Destructor Documentation

◆ VulkanAndroidWindow()

Ogre::VulkanAndroidWindow::VulkanAndroidWindow ( const String title,
uint32  width,
uint32  height,
bool  fullscreenMode 

◆ ~VulkanAndroidWindow()

Ogre::VulkanAndroidWindow::~VulkanAndroidWindow ( )

Member Function Documentation

◆ _initialize()

void Ogre::VulkanAndroidWindow::_initialize ( TextureGpuManager textureGpuManager,
const NameValuePairList miscParams 

◆ _setVisible()

void Ogre::VulkanAndroidWindow::_setVisible ( bool  visible)

Internal method to notify the window it has been obscured or minimized.

Implements Ogre::Window.

◆ destroy()

void Ogre::VulkanAndroidWindow::destroy ( )

Reimplemented from Ogre::VulkanWindowSwapChainBased.

◆ getCustomAttribute()

void Ogre::VulkanAndroidWindow::getCustomAttribute ( IdString  name,
void *  pData 

Reimplemented from Ogre::VulkanWindowSwapChainBased.

◆ getRequiredExtensionName()

static const char* Ogre::VulkanAndroidWindow::getRequiredExtensionName ( )

◆ isHidden()

bool Ogre::VulkanAndroidWindow::isHidden ( ) const

Indicates whether the window was set to hidden (not displayed)

Implements Ogre::Window.

◆ isVisible()

bool Ogre::VulkanAndroidWindow::isVisible ( ) const

Implements Ogre::Window.

◆ reposition()

void Ogre::VulkanAndroidWindow::reposition ( int32  left,
int32  top 

Implements Ogre::Window.

◆ requestResolution()

void Ogre::VulkanAndroidWindow::requestResolution ( uint32  widthPt,
uint32  heightPt 

Requests a change in resolution.

Change is not immediate. Use getRequestedWidthPt & getRequestedHeightPt if you need to know what you've requested, but beware you may not get that resolution, and once we get word from the OS, getRequested{Width/Height}Pt will change again so that getWidth == getRequestedWidthPt * getViewPointToPixelScale.

Reimplemented from Ogre::Window.

◆ setFramePacingSwappyAutoMode()

static void Ogre::VulkanAndroidWindow::setFramePacingSwappyAutoMode ( FramePacingSwappyModes  mode)

Sets Swappy auto swap interval and auto pipeline modes.

See https://developer.android.com/games/sdk/frame-pacing

This function is static, because it affects all Windows.
bAutoSwapIntervalSet to let Swappy autocalculate the vSyncInterval. i.e. See Window::setVSync. False to always try to honour the vSyncInterval set in Window::setVSync.

◆ setHidden()

void Ogre::VulkanAndroidWindow::setHidden ( bool  hidden)

Hide (or show) the window.

If called with hidden=true, this will make the window completely invisible to the user.

Setting a window to hidden is useful to create a dummy primary RenderWindow hidden from the user so that you can create and recreate your actual RenderWindows without having to recreate all your resources.

Implements Ogre::Window.

◆ setJniProvider()

void Ogre::VulkanAndroidWindow::setJniProvider ( AndroidJniProvider provider)

User must call this function before initializing if built with OGRE_VULKAN_USE_SWAPPY.

We don't ask for the JNIEnv directly (but rather through the provider) because the dev user may chose to call DetachCurrentThread often instead of keeping the JNIEnv around.

We only need to call AndroidJniProvider::get when recreating the swapchain.

◆ setNativeWindow()

void Ogre::VulkanAndroidWindow::setNativeWindow ( ANativeWindow *  nativeWindow)

If the ANativeWindow changes, allows to set a new one.

◆ setVSync()

void Ogre::VulkanAndroidWindow::setVSync ( bool  vSync,
uint32  vSyncInterval 

Turns VSync on/off.

vSyncIntervalWhen true, specifies how often the screen should be updated. e.g. at 60hz: vSyncInterval = 1 then update at 60hz vSyncInterval = 2 then update at 30hz vSyncInterval = 3 then update at 15hz vSyncInterval = 4 then update at 7.5hz

If the 31st bit is set, i.e. 0x80000000, then lowest latency mode, aka mailbox, will be used (which doesn't limit the framerate)

Reimplemented from Ogre::VulkanWindowSwapChainBased.

◆ windowMovedOrResized()

void Ogre::VulkanAndroidWindow::windowMovedOrResized ( )

Notify that the window has been resized.

You don't need to call this unless you created the window externally.

Reimplemented from Ogre::Window.

The documentation for this class was generated from the following file: