HaxeFlixel / HaxeFlixel/flixel

[ENHANCEMENT] Support FlxGraphic.dump() to allow for GPU-only textures

Open
#3,034 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Haxe
Stars
2.2k
Forks
522
Avg merge
34m
Merged PRs (30d)
1

Description

OpenFL has functionality available which flags image data as dumped and removes the contents of BitmapData from RAM (while still holding a reference to the texture that has been uploaded to VRAM). This GREATLY reduces memory usage at the expense of being unable to draw on the graphic, which is still fine in a wide variety of use cases. Depending on the type of graphic I think this should probably even be the default in many cases, requiring the graphic to be explicitly "undumped" to be drawn on.

Doing this would involve calling disposeBitmap() on the underlying BitmapData. The next time the BitmapData is rendered, BitmapData.getTexture() is called; when this happens, OpenFL instantiates the hardware texture (__texture) and calls __uploadFromImage to populate it. Once this is done, OpenFL will use __texture when rendering and the BitmapData.image is no longer necessary. If disposeBitmap() has been called, image is set to null after the texture is instantiated so the array can be garbage collected.

The above functionality only works on a hardware renderer (such as a native build supporting OpenGL). When using a software renderer (i.e. Flash Player, or desktop targets without OpenGL), OpenFL is not capable of uploading the texture to VRAM this way; disposeImage() will not cause image to dispose and thus nothing should break.

I do not know what happens when disposeImage() is used on the HTML5 target, it could use a texture provided by WebGL or it could use the software rendering functionality.

The above functionality has been experimented with somewhat in FNF mod projects (resulting in massive decreases in memory), but having it available in the main branch would be a major improvement and at this point in time it is probably the most important change I want to see come to Flixel 6.

Note also that disposeImage() is flagged as Beta in the documentation but has existed for about 8 years so I assume it's mostly fine.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at FlxGraphic.dump() and trace the underlying BitmapData.disposeBitmap(), getTexture(), and __uploadFromImage flow described in the issue. Determine the expected behavior for hardware, software, and HTML5 renderers, including whether dumping should be opt-in or a default. Done means GPU-only textures work without breaking rendering on unsupported targets.

Written by the indexing model from the issue text.

Assessment

Domain
game-dev, performance
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.