Examples of usage of copyFBRegionToMemory()

[scottSD]

Does anyone know if there is there an example somewhere of usage of the method copyFBRegionToMemory()?

The documentation says that the buffer can be a dynamic bitmap and I am having issues getting my code to compile.

[Martin KJELDSEN]

Hi @scottSD​,

Let's start with the documentation:

/**
 * @fn virtual uint16_t* HAL::copyFBRegionToMemory(Rect meAbs);
 *
 * @brief Copies a region of the currently displayed frame buffer to memory.
 *
 * Copies a region of the currently displayed frame buffer to memory. Used for e.g.
 * SlideTransition and for displaying pre-rendered drawables
 * e.g. in animations where redrawing the drawable is not necessary.
 *
 * @note Requires animation storage to be present.
 *
 * @param meAbs The frame buffer region to copy.
 *
 * @return A pointer to the memory address containing the copy of the frame buffer.
 */
 virtual uint16_t* copyFBRegionToMemory(Rect meAbs);
 
 /**
 * @fn virtual uint16_t* HAL::copyFBRegionToMemory(Rect meAbs, uint16_t* dst, uint32_t stride);
 *
 * @brief Copies a region of the currently displayed frame buffer to memory.
 *
 * Copies a region of the currently displayed frame buffer
 * to a buffer. Used for e.g. SlideTransition and for
 * displaying pre-rendered drawables e.g. in animations
 * where redrawing the drawable is not necessary. The
 * buffer can e.g. be a dynamic bitmap.
 *
 * @note Requires animation storage to be present.
 *
 * @param meAbs The frame buffer region to copy.
 * @param dst Address of the buffer to store the copy in.
 * @param stride The width of the target buffer (row length).
 *
 * @return A pointer to the memory address containing the copy of the frame buffer.
 */
 virtual uint16_t* copyFBRegionToMemory(Rect meAbs, uint16_t* dst, uint32_t stride);

What these methods can do is copy an area of the currently displayed framebuffer and into a different area of your memory, using DMA2D.

If you use the first option that takes just a Rect as argument, then the "animation storage" will be used. This buffer is allocated after the regular framebuffers and is used for things like animated transitions and SnapShotWidget (which also uses copyFBRegionToMemory).

/**
 * @fn virtual void HAL::setFrameBufferStartAddress(void* adr, uint16_t depth = 16, bool useDoubleBuffering = true, bool useAnimationStorage = true)
 *
 * @brief Sets the address used for frame buffers, usually located in external memory.
 *
 * Sets the address used for frame buffers, usually located in external memory. Will
 * reserve memory for one or two frame buffers based on display size. Will optionally
 * also reserve memory for a third frame buffer used for animationStorage.
 *
 * @param [in] adr Starting address to use for frame buffers.
 * @param depth (Optional) Depth of each pixel in bits, default is 16.
 * @param useDoubleBuffering (Optional) If true, reserve memory for an extra frame buffer.
 * @param useAnimationStorage (Optional) If true, reserve memory for animation storage.
 *
 * @deprecated Use the setFramaBufferStartAddress with 'format' parameter instead of 'depth'
 */
 virtual void setFrameBufferStartAddress(void* adr, uint16_t depth = 16, bool useDoubleBuffering = true, bool useAnimationStorage = true)

If you use the second version of copyFBRegionToMemory, you can decide where in memory to copy the data to. You could then feed this memory area to a DynamicBitmap to create an image based on the current contents of the framebuffer.

So the uses are generally:

• SnapShotWidget (built in)
• Screen Transitions (built in)
• If you want to copy part of (using Rect) the current frame and wish to story this in memory. Use with DynamicBitmap to turn this into an actual image that can do everything a normal image can (drag, etc).

  

Best regards,

/Martin

[scottSD]

Thanks for your reply Martin.

I have seen this documentation (reason I was wondering if there was an example).

Also, I did see the utilization of the copyFBRegionToMemory() in the file PreRenderable.hpp.

I have tried both methods and both appear to crash the simulator. I setup a very simple project for the STM32H750-Discovery board. All it has on it is one screen with a black box.

I placed the following code in the screen's setupScreen() method:

void Screen1View::setupScreen()
{
 Screen1ViewBase::setupScreen();
 touchgfx::Rect r(0, 0, 10, 10);
 uint16_t* adr;
 touchgfx_printf("before copyFBRegionToMemory()\n");
 adr = HAL::getInstance()->copyFBRegionToMemory(r);
 touchgfx_printf("after copyFBRegionToMemory() adr: %0x\n", adr);
}
 

The console output never prints before "copyFBRegionToMemory()" but appears to crash because the simulator screen remains white and the console window never prints "after copyFBRegionToMemory()".

Am I doing something wrong?