Loading...
Searching...
No Matches
juce::ImagePixelDataBackupExtensions Class Referenceabstract

## 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

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

- juce_graphics/images/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

## Constructors and Destructors

## ~ImagePixelDataBackupExtensions()

juce::ImagePixelDataBackupExtensions::~ImagePixelDataBackupExtensions | ( |  | ) |

protected default

## Member Functions

## setBackupEnabled()

virtual void juce::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 juce::ImagePixelDataBackupExtensions::isBackupEnabled | ( |  | ) | const

pure virtual

See also
  setBackupEnabled(), backupNow()

## backupNow()

virtual bool juce::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 juce::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 juce::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()

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited