ImagePixelDataBackupExtensions Class Reference

The methods on this interface allow clients of ImagePixelData to query and control the automatic-backup process from graphics memory to main memory, if this mechanism is relevant and supported. More...

#include <juce_Image.h>

Public Member Functions
virtual void	setBackupEnabled (bool)=0
	The automatic image backup mechanism can be disabled by passing false to this function, or enabled by passing true.
virtual bool	isBackupEnabled () const =0
virtual bool	backupNow ()=0
	This function will attempt to make the image resilient to graphics device disconnection by copying from graphics memory to main memory.
virtual bool	needsBackup () const =0
	Returns true if the main-memory copy of the image is out-of-date, false if it's up-to-date.
virtual bool	canBackup () const =0
	Returns if there is an up-to-date copy of this image in graphics memory, or false otherwise.

Protected Member Functions
	~ImagePixelDataBackupExtensions ()=default

Detailed Description

The methods on this interface allow clients of ImagePixelData to query and control the automatic-backup process from graphics memory to main memory, if this mechanism is relevant and supported.

Some image types (Direct2D, OpenGL) are backed by textures that live in graphics memory. Such textures are quick to display, but they will be lost if the graphics device goes away.

Normally, a backup of the texture will be kept in main memory, so that the image can still be used even if any graphics device goes away. While this has the benefit that programs are automatically resilient to graphics devices going away, it also incurs some performance overhead, because the texture content must be copied back to main memory after each modification.

For performance-sensitive applications it can be beneficial to disable the automatic sync behaviour, and to sync manually instead, which can be achieved using the methods of this type.

The following table shows how to interpret the results of this type's member functions.

needsBackup() | canBackup() | meaning

true | true | the main-memory copy of the image is outdated, but there's an | | up-to-date copy in graphics memory | | true | false | although main memory is out-of-date, the most recent copy of | | the image in graphics memory has been lost | | false | true | main memory is up-to-date with graphics memory; graphics | | memory is still available; | | false | false | main memory has an up-to-date copy of the image, but the most | | recent copy of the image in graphics memory has been lost

Constructor & Destructor Documentation

~ImagePixelDataBackupExtensions()

ImagePixelDataBackupExtensions::~ImagePixelDataBackupExtensions ( )

protecteddefault

Member Function Documentation

setBackupEnabled()

virtual void ImagePixelDataBackupExtensions::setBackupEnabled ( bool )

pure virtual

The automatic image backup mechanism can be disabled by passing false to this function, or enabled by passing true.

If you disable automatic backup for a particular image, make sure you test that your software behaves as expected when graphics devices are disconnected. One easy way to test this on Windows is to use your program over a remote desktop session, and to end and re-start the session while the image is being displayed.

The most common scenario where this flag is useful is when drawing single-use images. e.g. for a drop shadow or other effect, the following series of steps might be carried out on each paint call:

• Create a path that matches the shadowed component's outline
• Draw the path into a temporary image
• Blur the temporary image
• Draw the temporary image into some other context
• (destroy the temporary image)

In this case, where the image is created, modified, used, and destroyed in quick succession, there's no need to keep a resilient backup of the image around, so it's reasonable to call setBackupEnabled(false) after constructing the image.

See also

isBackupEnabled(), backupNow()

isBackupEnabled()

virtual bool ImagePixelDataBackupExtensions::isBackupEnabled ( ) const

pure virtual

See also

setBackupEnabled(), backupNow()

backupNow()

virtual bool ImagePixelDataBackupExtensions::backupNow ( )

pure virtual

This function will attempt to make the image resilient to graphics device disconnection by copying from graphics memory to main memory.

By default, backups happen automatically, so there's no need to call this function unless auto-backup has been disabled on this image.

Flushing may fail if the graphics device goes away before its memory can be read. If needsBackup() returns false, then backupNow() will always return true without doing any work.

Returns

true if the main-memory copy of the image is up-to-date, or false otherwise.

See also

setBackupEnabled(), isBackupEnabled()

needsBackup()

virtual bool ImagePixelDataBackupExtensions::needsBackup ( ) const

pure virtual

Returns true if the main-memory copy of the image is out-of-date, false if it's up-to-date.

See also

canBackup()

canBackup()

virtual bool ImagePixelDataBackupExtensions::canBackup ( ) const

pure virtual

Returns if there is an up-to-date copy of this image in graphics memory, or false otherwise.

See also

needsBackup()

---

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

• juce_Image.h