Macro Definition Documentation

Allocates the memory with malloc_routine. Returns NULL upon allocation failure.

data_size is the maximum predicted/calculated size of the sprite data (excuding the width and height bytes) that will be stored in the allocated sprite. Sprite data size could be up to (width + 1) * height * 3 / 2 bytes in the worst case, in which pixels horizontally alternate between non-transparent and transparent and each row begins with a non-transparent pixel. But if the average length of a horizontal transparent run is at least 2, then the sprite data will be no larger than (width + 1) * height bytes. The exact data size necessary is 2 * num_horizontal_transparent_runs + num_non_transparent_pixels + num_rows_beginning_with_non_transparent_pixel - num_rows_ending_with_transparent_pixel bytes.

Note

If not used in a dynamic context and data_size is static, consider statically allocating the sprite instead with gfx_UninitedRLETSprite() or gfx_TempRLETSprite().

Due to width and height being set, the memory will be allocated in the initialized data segment. If the compiled program is not compressed, then this could be a serious source of bloat and gfx_UninitedSprite() should be preferred.

If used outside of a function body, the memory will be allocated in the global unitialized data segment (BSS). If used inside a function body, the memory will be allocated on the stack. If the sprite is sufficiently large, usage inside a function body will overflow the stack, so it is recommended that this normally be used outside of a function body.

Declares a gfx_sprite_t * with the given name pointing to the allocated memory. width and height will not be set in the sprite, unlike gfx_TempSprite().

Warning

If used outside of a function body, the memory will be allocated in the global unitialized data segment (BSS). If used inside a function body, the memory will be allocated on the stack. If the sprite is sufficiently large, usage inside a function body will overflow the stack, so it is recommended that this normally be used outside of a function body.

The output sprite must have been allocated with a large enough data field to hold the converted sprite data; see gfx_AllocRLETSprite() for information.

Note

To avoid needing to predict the output size and risking either the prediction being too high and wasting space, or being too low and corrupting memory, gfx_ConvertMallocRLETSprite() can be used instead to allocate the exact amount of necessary space for the converted sprite.

The output sprite is updated with the dimensions required for the implemented scaling factor. You must make sure that sprite_out has enough memory to store the needed output sprite. This can be found with the following formula: size = (max_scale / 64) * width * height + 2;

Does not wait for the old screen buffer to finish being displayed. Instead, the next invocation of a graphx drawing function will block, waiting for this event. To block and wait explicitly, use gfx_Wait().

The LCD driver maintains its own screen buffer pointer for the duration of a refresh. The swap performed by this function will only be picked up at a point between refreshes.

Remarks

In practice, this function should be invoked immediately after finishing drawing a frame to the drawing buffer, and invocation of the first graphx drawing function for the next frame should be scheduled as late as possible relative to non-drawing logic. Non-drawing logic can execute during time when a drawing function may otherwise block.

Waits for the screen buffer to finish being displayed after gfx_SwapDraw().

Remarks

In practice, this function should not need to be invoked by user code. It should be invoked by custom drawing functions (as late as reasonably possible) before writing to the drawing buffer, gfx_vbuffer.