bn::sprite_builder class
#include <bn_sprite_builder.h>

Creates sprite_ptr objects with custom attributes.

If some of the attributes of the sprite to create differs from the default ones, using this class improves performance.

Constructors, destructors, conversion operators

sprite_builder(const sprite_item& item) explicit: Constructor.
sprite_builder(const sprite_item& item, int graphics_index): Constructor.
sprite_builder(const sprite_shape_size& shape_size, sprite_tiles_ptr tiles, sprite_palette_ptr palette): Constructor.

Public functions

auto item() const -> const optional<sprite_item>&: Returns the sprite_item containing the required information to generate sprites if it has one; bn::nullopt otherwise.
auto graphics_index() const -> int: Index of the tile set to reference in item.tiles_item() to generate sprites.
auto shape_size() const -> const sprite_shape_size&: Returns the shape and size of the sprites to generate.
auto x() const -> fixed: Returns the horizontal position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_x(fixed x) -> sprite_builder&: Sets the horizontal position of the sprites to generate (relative to their camera, if they are going to have one).
auto y() const -> fixed: Returns the vertical position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_y(fixed y) -> sprite_builder&: Sets the vertical position of the sprites to generate (relative to their camera, if they are going to have one).
auto position() const -> const fixed_point&: Returns the position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_position(fixed x, fixed y) -> sprite_builder&: Sets the position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_position(const fixed_point& position) -> sprite_builder&: Sets the position of the sprites to generate (relative to their camera, if they are going to have one).
auto top_left_x() const -> fixed: Returns the horizontal top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_top_left_x(fixed top_left_x) -> sprite_builder&: Sets the horizontal top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto top_left_y() const -> fixed: Returns the vertical top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_top_left_y(fixed top_left_y) -> sprite_builder&: Sets the vertical top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto top_left_position() const -> fixed_point: Returns the top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_top_left_position(fixed top_left_x, fixed top_left_y) -> sprite_builder&: Sets the top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto set_top_left_position(const fixed_point& top_left_position) -> sprite_builder&: Sets the top-left position of the sprites to generate (relative to their camera, if they are going to have one).
auto rotation_angle() const -> fixed: Returns the rotation angle in degrees of the sprites to generate.
auto set_rotation_angle(fixed rotation_angle) -> sprite_builder&: Sets the rotation angle in degrees of the sprites to generate.
auto set_rotation_angle_safe(fixed rotation_angle) -> sprite_builder&: Sets the rotation angle in degrees of the sprites to generate.
auto horizontal_scale() const -> fixed: Returns the horizontal scale of the sprites to generate.
auto set_horizontal_scale(fixed horizontal_scale) -> sprite_builder&: Sets the horizontal scale of the sprites to generate.
auto vertical_scale() const -> fixed: Returns the vertical scale of the sprites to generate.
auto set_vertical_scale(fixed vertical_scale) -> sprite_builder&: Sets the vertical scale of the sprites to generate.
auto set_scale(fixed scale) -> sprite_builder&: Sets the scale of the sprites to generate.
auto set_scale(fixed horizontal_scale, fixed vertical_scale) -> sprite_builder&: Sets the scale of the sprites to generate.
auto horizontal_shear() const -> fixed: Returns the horizontal shear of the sprites to generate.
auto set_horizontal_shear(fixed horizontal_shear) -> sprite_builder&: Sets the horizontal shear of the sprites to generate.
auto vertical_shear() const -> fixed: Returns the vertical shear of the sprites to generate.
auto set_vertical_shear(fixed vertical_shear) -> sprite_builder&: Sets the vertical shear of the sprites to generate.
auto set_shear(fixed shear) -> sprite_builder&: Sets the shear of the sprites to generate.
auto set_shear(fixed horizontal_shear, fixed vertical_shear) -> sprite_builder&: Sets the shear of the sprites to generate.
auto bg_priority() const -> int: Returns the priority of the sprites to generate relative to backgrounds.
auto set_bg_priority(int bg_priority) -> sprite_builder&: Sets the priority of the sprites to generate relative to backgrounds.
auto z_order() const -> int: Returns the priority of the sprites to generate relative to other ones.
auto set_z_order(int z_order) -> sprite_builder&: Sets the priority of the sprites to generate relative to other ones.
auto horizontal_flip() const -> bool: Indicates if the sprites to generate are flipped in the horizontal axis or not.
auto set_horizontal_flip(bool horizontal_flip) -> sprite_builder&: Sets if the sprites to generate must be flipped in the horizontal axis or not.
auto vertical_flip() const -> bool: Indicates if the sprites to generate are flipped in the vertical axis or not.
auto set_vertical_flip(bool vertical_flip) -> sprite_builder&: Sets if the sprites to generate must be flipped in the vertical axis or not.
auto mosaic_enabled() const -> bool: Indicates if the mosaic effect must be applied to the sprites to generate or not.
auto set_mosaic_enabled(bool mosaic_enabled) -> sprite_builder&: Sets if the mosaic effect must be applied to the sprites to generate or not.
auto blending_enabled() const -> bool: Indicates if blending must be applied to the sprites to generate or not.
auto set_blending_enabled(bool blending_enabled) -> sprite_builder&: Sets if blending must be applied to the sprites to generate or not.
auto window_enabled() const -> bool: Indicates if the sprites to generate must be part of the silhouette of the sprite window or not.
auto set_window_enabled(bool window_enabled) -> sprite_builder&: Sets if the sprites to generate must be part of the silhouette of the sprite window or not.
auto double_size_mode() const -> sprite_double_size_mode: Returns the area the sprites to generate use to be drawn when they have an attached sprite_affine_mat_ptr.
auto set_double_size_mode(sprite_double_size_mode double_size_mode) -> sprite_builder&: Specifies the area the sprites to generate use to be drawn when they have an attached sprite_affine_mat_ptr.
auto visible() const -> bool: Indicates if the sprites to generate must be committed to the GBA or not.
auto set_visible(bool visible) -> sprite_builder&: Sets if the sprites to generate must be committed to the GBA or not.
auto camera() const -> const optional<camera_ptr>&: Returns the camera_ptr to attach to the sprites to generate (if any).
auto set_camera(const camera_ptr& camera) -> sprite_builder&: Sets the camera_ptr to attach to the sprites to generate.
auto set_camera(camera_ptr&& camera) -> sprite_builder&: Sets the camera_ptr to attach to the sprites to generate.
auto set_camera(const optional<camera_ptr>& camera) -> sprite_builder&: Sets or removes the camera_ptr to attach to the sprites to generate.
auto set_camera(optional<camera_ptr>&& camera) -> sprite_builder&: Sets or removes the camera_ptr to attach to the sprites to generate.
auto remove_camera() -> sprite_builder&: Removes the camera_ptr to attach to the sprites to generate.
auto release_camera() -> optional<camera_ptr>: Releases and returns the camera_ptr to attach to the sprites to generate (if any).
auto build() const -> sprite_ptr: Generates and returns a sprite_ptr without releasing the acquired resources.
auto release_build() -> sprite_ptr: Generates and returns a sprite_ptr releasing the acquired resources.
auto build_optional() const -> optional<sprite_ptr>: Generates and returns a sprite_ptr without releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto release_build_optional() -> optional<sprite_ptr>: Generates and returns a sprite_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto tiles() const -> sprite_tiles_ptr: Generates and returns a sprite_tiles_ptr without releasing the acquired resources.
auto palette() const -> sprite_palette_ptr: Generates and returns a sprite_palette_ptr without releasing the acquired resources.
auto tiles_optional() const -> optional<sprite_tiles_ptr>: Generates and returns a sprite_tiles_ptr without releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto palette_optional() const -> optional<sprite_palette_ptr>: Generates and returns a sprite_palette_ptr without releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto release_tiles() -> sprite_tiles_ptr: Generates and returns a sprite_tiles_ptr releasing the acquired resources.
auto release_palette() -> sprite_palette_ptr: Generates and returns a sprite_palette_ptr releasing the acquired resources.
auto release_tiles_optional() -> optional<sprite_tiles_ptr>: Generates and returns a sprite_tiles_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto release_palette_optional() -> optional<sprite_palette_ptr>: Generates and returns a sprite_palette_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.
auto affine_mat() const -> const optional<sprite_affine_mat_ptr>&: Returns the sprite_affine_mat_ptr to attach to the sprites to generate (if any).
auto set_affine_mat(const sprite_affine_mat_ptr& affine_mat) -> sprite_builder&: Sets the sprite_affine_mat_ptr to attach to the sprites to generate.
auto set_affine_mat(sprite_affine_mat_ptr&& affine_mat) -> sprite_builder&: Sets the sprite_affine_mat_ptr to attach to the sprites to generate.
auto set_affine_mat(const optional<sprite_affine_mat_ptr>& affine_mat) -> sprite_builder&: Sets or removes the sprite_affine_mat_ptr to attach to the sprites to generate.
auto set_affine_mat(optional<sprite_affine_mat_ptr>&& affine_mat) -> sprite_builder&: Sets or removes the sprite_affine_mat_ptr to attach to the sprites to generate.
auto remove_affine_mat() -> sprite_builder&: Removes the sprite_affine_mat_ptr to attach to the sprites to generate.
auto release_affine_mat() -> optional<sprite_affine_mat_ptr>: Releases and returns the sprite_affine_mat_ptr to attach to the sprites to generate (if any).
auto remove_affine_mat_when_not_needed() const -> bool: Indicates if the sprite_affine_mat_ptr attached to the sprites to generate (if any) must be removed when it is not needed anymore.
auto set_remove_affine_mat_when_not_needed(bool remove_when_not_needed) -> sprite_builder&: Sets if the sprite_affine_mat_ptr attached to the sprites to generate (if any) must be removed when it is not needed anymore.

Function documentation

bn::sprite_builder::sprite_builder(const sprite_item& item) explicit

Constructor.

Parameters
item	sprite_item containing the required information to generate sprites.

bn::sprite_builder::sprite_builder(const sprite_item& item, int graphics_index)

Constructor.

Parameters
item	sprite_item containing the required information to generate sprites.
graphics_index	Index of the tile set to reference in item.tiles_item() to generate sprites.

bn::sprite_builder::sprite_builder(const sprite_shape_size& shape_size, sprite_tiles_ptr tiles, sprite_palette_ptr palette)

Constructor.

Parameters
shape_size	Shape and size of the sprites to generate.
tiles	Smart pointer to the sprite tile set used to generate sprites.
palette	Smart pointer to the sprite color palette used to generate sprites.

sprite_builder& bn::sprite_builder::set_x(fixed x)

Sets the horizontal position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
x	Horizontal position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_y(fixed y)

Sets the vertical position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
y	Vertical position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_position(fixed x, fixed y)

Sets the position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
x	Horizontal position of the sprites to generate.
y	Vertical position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_position(const fixed_point& position)

Sets the position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
position	Position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_top_left_x(fixed top_left_x)

Sets the horizontal top-left position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
top_left_x	Horizontal top-left position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_top_left_y(fixed top_left_y)

Sets the vertical top-left position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
top_left_y	Vertical top-left position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_top_left_position(fixed top_left_x, fixed top_left_y)

Sets the top-left position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
top_left_x	Horizontal top-left position of the sprites to generate.
top_left_y	Vertical top-left position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_top_left_position(const fixed_point& top_left_position)

Sets the top-left position of the sprites to generate (relative to their camera, if they are going to have one).

Parameters
top_left_position	Top-left position of the sprites to generate.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_rotation_angle(fixed rotation_angle)

Sets the rotation angle in degrees of the sprites to generate.

Parameters
rotation_angle	Rotation angle in degrees, in the range [0..360].
Returns	Reference to this.

If the rotation angle is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given rotation angle is attached to it.

sprite_builder& bn::sprite_builder::set_rotation_angle_safe(fixed rotation_angle)

Sets the rotation angle in degrees of the sprites to generate.

Parameters
rotation_angle	Rotation angle in degrees, in any range.
Returns	Reference to this.

If the rotation angle is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given rotation angle is attached to it.

sprite_builder& bn::sprite_builder::set_horizontal_scale(fixed horizontal_scale)

Sets the horizontal scale of the sprites to generate.

Parameters
horizontal_scale	Horizontal scale of the sprites to generate.
Returns	Reference to this.

If the horizontal scale is != 1 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given horizontal scale is attached to it.

sprite_builder& bn::sprite_builder::set_vertical_scale(fixed vertical_scale)

Sets the vertical scale of the sprites to generate.

Parameters
vertical_scale	Vertical scale of the sprites to generate.
Returns	Reference to this.

If the vertical scale is != 1 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical scale is attached to it.

sprite_builder& bn::sprite_builder::set_scale(fixed scale)

Sets the scale of the sprites to generate.

Parameters
scale	Scale of the sprites to generate.
Returns	Reference to this.

If the scale is != 1 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical scale is attached to it.

sprite_builder& bn::sprite_builder::set_scale(fixed horizontal_scale, fixed vertical_scale)

Sets the scale of the sprites to generate.

Parameters
horizontal_scale	Horizontal scale of the sprites to generate.
vertical_scale	Vertical scale of the sprites to generate.
Returns	Reference to this.

If the horizontal or the vertical scale is != 1 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical scale is attached to it.

sprite_builder& bn::sprite_builder::set_horizontal_shear(fixed horizontal_shear)

Sets the horizontal shear of the sprites to generate.

Parameters
horizontal_shear	Horizontal shear of the sprites to generate.
Returns	Reference to this.

If the horizontal shear is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given horizontal shear is attached to it.

sprite_builder& bn::sprite_builder::set_vertical_shear(fixed vertical_shear)

Sets the vertical shear of the sprites to generate.

Parameters
vertical_shear	Vertical shear of the sprites to generate.
Returns	Reference to this.

If the vertical shear is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical shear is attached to it.

sprite_builder& bn::sprite_builder::set_shear(fixed shear)

Sets the shear of the sprites to generate.

Parameters
shear	Shear of the sprites to generate.
Returns	Reference to this.

If the shear is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical shear is attached to it.

sprite_builder& bn::sprite_builder::set_shear(fixed horizontal_shear, fixed vertical_shear)

Sets the shear of the sprites to generate.

Parameters
horizontal_shear	Horizontal shear of the sprites to generate.
vertical_shear	Vertical shear of the sprites to generate.
Returns	Reference to this.

If the horizontal or the vertical shear is != 0 and the builder doesn't have an attached sprite_affine_mat_ptr, a new one with the given vertical shear is attached to it.

int bn::sprite_builder::bg_priority() const

Returns the priority of the sprites to generate relative to backgrounds.

Sprites with higher priority are drawn first (and therefore can be covered by later sprites and backgrounds). Sprites cover backgrounds of the same priority.

sprite_builder& bn::sprite_builder::set_bg_priority(int bg_priority)

Sets the priority of the sprites to generate relative to backgrounds.

Parameters
bg_priority	Priority relative to backgrounds in the range [0..3].
Returns	Reference to this.

Sprites with higher priority are drawn first (and therefore can be covered by later sprites and backgrounds). Sprites cover backgrounds of the same priority.

int bn::sprite_builder::z_order() const

Returns the priority of the sprites to generate relative to other ones.

Sprites with higher z orders are drawn first (and therefore can be covered by later sprites).

Sprites are grouped in layers depending of their background priority and z order, so to reduce memory usage and improve performance, please use as less unique z orders as possible.

sprite_builder& bn::sprite_builder::set_z_order(int z_order)

Sets the priority of the sprites to generate relative to other ones.

Parameters
z_order	Priority relative to other sprites in the range [-32767..32767].
Returns	Reference to this.

Sprites with higher z orders are drawn first (and therefore can be covered by later sprites).

Sprites are grouped in layers depending of their background priority and z order, so to reduce memory usage and improve performance, please use as less unique z orders as possible.

sprite_builder& bn::sprite_builder::set_horizontal_flip(bool horizontal_flip)

Sets if the sprites to generate must be flipped in the horizontal axis or not.

Parameters
horizontal_flip	`true` if the sprites must be flipped in the horizontal axis; `false` otherwise.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_vertical_flip(bool vertical_flip)

Sets if the sprites to generate must be flipped in the vertical axis or not.

Parameters
vertical_flip	`true` if the sprites must be flipped in the vertical axis; `false` otherwise.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_mosaic_enabled(bool mosaic_enabled)

Sets if the mosaic effect must be applied to the sprites to generate or not.

Parameters
mosaic_enabled	`true` if the mosaic effect must be applied; `false` otherwise.
Returns	Reference to this.

bool bn::sprite_builder::blending_enabled() const

Indicates if blending must be applied to the sprites to generate or not.

Keep in mind that blending and window attributes can't be enabled on a sprite at the same time.

sprite_builder& bn::sprite_builder::set_blending_enabled(bool blending_enabled)

Sets if blending must be applied to the sprites to generate or not.

Parameters
blending_enabled	`true` if blending must be applied; `false` otherwise.
Returns	Reference to this.

Keep in mind that blending and window attributes can't be enabled on a sprite at the same time.

bool bn::sprite_builder::window_enabled() const

Indicates if the sprites to generate must be part of the silhouette of the sprite window or not.

Keep in mind that blending and window attributes can't be enabled on a sprite at the same time.

sprite_builder& bn::sprite_builder::set_window_enabled(bool window_enabled)

Sets if the sprites to generate must be part of the silhouette of the sprite window or not.

Parameters
window_enabled	`true` if the sprites must be part of the silhouette of the sprite window; `false` otherwise.
Returns	Reference to this.

Keep in mind that blending and window attributes can't be enabled on a sprite at the same time.

sprite_builder& bn::sprite_builder::set_double_size_mode(sprite_double_size_mode double_size_mode)

Specifies the area the sprites to generate use to be drawn when they have an attached sprite_affine_mat_ptr.

Parameters
double_size_mode	sprite_double_size_mode enum value.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_visible(bool visible)

Sets if the sprites to generate must be committed to the GBA or not.

Parameters
visible	`true` if the sprites must be committed to the GBA; `false` otherwise.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_camera(const camera_ptr& camera)

Sets the camera_ptr to attach to the sprites to generate.

Parameters
camera	camera_ptr to copy to the builder.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_camera(camera_ptr&& camera)

Sets the camera_ptr to attach to the sprites to generate.

Parameters
camera	camera_ptr to move to the builder.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_camera(const optional<camera_ptr>& camera)

Sets or removes the camera_ptr to attach to the sprites to generate.

Parameters
camera	Optional camera_ptr to copy to the builder.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::set_camera(optional<camera_ptr>&& camera)

Sets or removes the camera_ptr to attach to the sprites to generate.

Parameters
camera	Optional camera_ptr to move to the builder.
Returns	Reference to this.

sprite_builder& bn::sprite_builder::remove_camera()

Removes the camera_ptr to attach to the sprites to generate.

Returns	Reference to this.