bn::sprite_builder class

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 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 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_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_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.

sprite_ptr bn::sprite_builder::release_build()

Generates and returns a sprite_ptr releasing the acquired resources.

This method must be called once at most.

optional<sprite_ptr> bn::sprite_builder::release_build_optional()

Generates and returns a sprite_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.

This method must be called once at most.

sprite_tiles_ptr bn::sprite_builder::release_tiles()

Generates and returns a sprite_tiles_ptr releasing the acquired resources.

This method must be called once at most.

sprite_palette_ptr bn::sprite_builder::release_palette()

Generates and returns a sprite_palette_ptr releasing the acquired resources.

This method must be called once at most.

optional<sprite_tiles_ptr> bn::sprite_builder::release_tiles_optional()

Generates and returns a sprite_tiles_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.

This method must be called once at most.

optional<sprite_palette_ptr> bn::sprite_builder::release_palette_optional()

Generates and returns a sprite_palette_ptr releasing the acquired resources if it could be allocated; bn::nullopt otherwise.

This method must be called once at most.

sprite_builder& bn::sprite_builder::set_affine_mat(const sprite_affine_mat_ptr& affine_mat)

Sets the sprite_affine_mat_ptr to attach to the sprites to generate.

Parameters
affine_mat sprite_affine_mat_ptr to copy to the builder.
Returns Reference to this.

This method calls set_remove_affine_mat_when_not_needed(false).

sprite_builder& bn::sprite_builder::set_affine_mat(sprite_affine_mat_ptr&& affine_mat)

Sets the sprite_affine_mat_ptr to attach to the sprites to generate.

Parameters
affine_mat sprite_affine_mat_ptr to move to the builder.
Returns Reference to this.

This method calls set_remove_affine_mat_when_not_needed(false).

sprite_builder& bn::sprite_builder::set_affine_mat(const optional<sprite_affine_mat_ptr>& affine_mat)

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

Parameters
affine_mat Optional sprite_affine_mat_ptr to copy to the builder.
Returns Reference to this.

This method calls set_remove_affine_mat_when_not_needed(false) if the given sprite_affine_mat_ptr is not null.

sprite_builder& bn::sprite_builder::set_affine_mat(optional<sprite_affine_mat_ptr>&& affine_mat)

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

Parameters
affine_mat Optional sprite_affine_mat_ptr to move to the builder.
Returns Reference to this.

This method calls set_remove_affine_mat_when_not_needed(false) if the given sprite_affine_mat_ptr is not null.

sprite_builder& bn::sprite_builder::remove_affine_mat()

Removes the sprite_affine_mat_ptr to attach to the sprites to generate.

Returns Reference to this.

bool bn::sprite_builder::remove_affine_mat_when_not_needed() const

Indicates if the sprite_affine_mat_ptr attached to the sprites to generate (if any) must be removed when it is not needed anymore.

A sprite does not need an sprite_affine_mat_ptr when its flipped_identity() method returns true.

sprite_builder& bn::sprite_builder::set_remove_affine_mat_when_not_needed(bool remove_when_not_needed)

Sets if the sprite_affine_mat_ptr attached to the sprites to generate (if any) must be removed when it is not needed anymore.

Parameters
remove_when_not_needed true if the sprite_affine_mat_ptr must be removed when it is not needed anymore; false otherwise.
Returns Reference to this.

A sprite does not need an sprite_affine_mat_ptr when its flipped_identity() method returns true.