Why does a Bevy sprite preview image stay blank when used as a camera target?

Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.

A Bevy image used as a camera target must support render attachment usage. If the same image is later displayed by a Sprite, it also needs texture binding usage. A preview can remain blank even though its handle exists and its PNG sources loaded. The Bevy 0.17.2 pixel-grid example shows the producer camera and displayed canvas.

Key Takeaways

World-retention flags and GPU texture usages are separate settings.

Render the preview before the camera that displays its image.

Keep the preview camera from drawing its own output sprite.

Create an image for the target role

An ordinary imported sprite image is not automatically the right render destination. Start with a purpose-built target of known dimensions and an explicit format supported by your rendering path.

Bevy 0.17.2 provides a helper for that role:

// Configuration fragment, not executed here. let canvas = Image::new_target_texture( 256, 256, TextureFormat::Bgra8UnormSrgb, ); let canvas_handle = images.add(canvas);

The Bevy Image helper implementation sets texture binding, copy destination and render attachment usages. If you construct the descriptor manually, preserve the capabilities required by your use instead of copying only its size and format.

Do not confuse those flags with RenderAssetUsages. The latter controls main-world/render-world retention, as defined in the asset usage source. Retaining a CPU image does not give a GPU texture permission to act as a render attachment.

Separate producer and consumer

The preview camera produces the image. A second view displays a Sprite using that handle. Give the producer an earlier render order than the consumer and assign appropriate layers to both views.

Inspect the pinned example's Camera.order and RenderTarget::Image configuration rather than assuming startup system order determines rendering order. A source sprite may exist before both cameras while the cameras still need an explicit rendering relationship.

Keep the canvas Sprite outside the preview camera's selected layers. Otherwise the preview may sample the image it is currently producing or form an unintended recursive display. The intended result is the isolated character, not an image of its own monitor.

Diagnose with a solid clear color

Use a conspicuous preview clear color and one simple source Sprite. If the displayed image shows only the clear color, the target may be working while the source sprite is excluded or outside the camera view. If it stays unchanged after the clear color changes, inspect the target handle, consumer Sprite and camera execution.

Result	Next boundary
Target creation reports a validation error	Texture descriptor and format capabilities
Clear color visible, character absent	Layers, framing, image readiness and visibility
Previous preview persists	Producer execution or target/handle replacement
Scene appears inside its own preview	Producer/consumer layer separation

The Bevy loading guide covers source readiness. The mobile texture-budget guide helps bound target dimensions; a larger preview is not a free fix.

Acceptance after resize and replacement

Open and close the preview repeatedly, replace the character, and resize the target deliberately. Confirm both camera target and displayed Sprite use the intended handle after a replacement. Keep export/readback as a separate requirement.

Record the target size, camera order and layer policy in the handoff checklist. This is a source-grounded Bevy 0.17.2 recipe. No GPU validation or rendering run was performed here.

Keep a replacement target coherent

If resizing creates a new image handle, treat the camera target and the displayed canvas as one small replacement set. Updating only one makes the producer write into an image the consumer no longer displays. Keep the old valid pair until the new pair is ready, then publish both references through the same transition owner. Include any export or thumbnail consumer in that inventory. This recommendation concerns handle coordination; it does not assert that creating an image synchronously means every downstream GPU operation has already completed.