bn::regular_bg_ptr class
#include <bn_regular_bg_ptr.h>

std::shared_ptr like smart pointer that retains shared ownership of a regular background.

Several regular_bg_ptr objects may own the same regular background.

The regular background is released when the last remaining regular_bg_ptr owning it is destroyed.

Public static functions

static auto create(fixed x, fixed y, const regular_bg_item& item) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create(fixed x, fixed y, const regular_bg_item& item, int map_index) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create(const fixed_point& position, const regular_bg_item& item) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create(const fixed_point& position, const regular_bg_item& item, int map_index) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create(fixed x, fixed y, regular_bg_map_ptr map) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_map_ptr.
static auto create(const fixed_point& position, regular_bg_map_ptr map) -> regular_bg_ptr
Creates a regular_bg_ptr from the given regular_bg_map_ptr.
static auto create(const regular_bg_builder& builder) -> regular_bg_ptr
Creates a regular_bg_ptr from a regular_bg_builder reference.
static auto create(regular_bg_builder&& builder) -> regular_bg_ptr
Creates a regular_bg_ptr from a moved regular_bg_builder.
static auto create_optional(fixed x, fixed y, const regular_bg_item& item) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create_optional(fixed x, fixed y, const regular_bg_item& item, int map_index) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create_optional(const fixed_point& position, const regular_bg_item& item) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create_optional(const fixed_point& position, const regular_bg_item& item, int map_index) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_item.
static auto create_optional(fixed x, fixed y, regular_bg_map_ptr map) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_map_ptr.
static auto create_optional(const fixed_point& position, regular_bg_map_ptr map) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from the given regular_bg_map_ptr.
static auto create_optional(const regular_bg_builder& builder) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from a regular_bg_builder reference.
static auto create_optional(regular_bg_builder&& builder) -> optional<regular_bg_ptr>
Creates a regular_bg_ptr from a moved regular_bg_builder.

Constructors, destructors, conversion operators

regular_bg_ptr(const regular_bg_ptr& other)
Copy constructor.
regular_bg_ptr(regular_bg_ptr&& other) noexcept
Move constructor.
~regular_bg_ptr()
Releases the referenced regular background if no more regular_bg_ptr objects reference to it.

Public functions

auto operator=(const regular_bg_ptr& other) -> regular_bg_ptr&
Copy assignment operator.
auto operator=(regular_bg_ptr&& other) -> regular_bg_ptr& noexcept
Move assignment operator.
auto dimensions() const -> size
Returns the size in pixels of the regular background.
auto big() const -> bool
Indicates if this regular background is big or not.
auto tiles() const -> const regular_bg_tiles_ptr&
Returns the tiles used by this regular background.
void set_tiles(const regular_bg_tiles_ptr& tiles)
Sets the tiles used by this regular background.
void set_tiles(regular_bg_tiles_ptr&& tiles)
Sets the tiles used by this regular background.
void set_tiles(const regular_bg_tiles_item& tiles_item)
Replaces the tiles used by this regular background with a new tile set created with the given regular_bg_tiles_item.
auto palette() const -> const bg_palette_ptr&
Returns the color palette used by this regular background.
void set_palette(const bg_palette_ptr& palette)
Sets the color palette to use by this regular background.
void set_palette(bg_palette_ptr&& palette)
Sets the color palette to use by this regular background.
void set_palette(const bg_palette_item& palette_item)
Replaces the color palette used by this regular background with a new one created with the given bg_palette_item.
void set_tiles_and_palette(regular_bg_tiles_ptr tiles, bg_palette_ptr palette)
Sets the tiles and the color palette to use by this regular background.
void set_tiles_and_palette(const regular_bg_tiles_item& tiles_item, const bg_palette_item& palette_item)
Replaces the tiles and the color palette used by this regular background with the created with the given regular_bg_tiles_item and bg_palette_item.
auto map() const -> const regular_bg_map_ptr&
Returns the map used by this regular background.
void set_map(const regular_bg_map_ptr& map)
Sets the map used by this regular background.
void set_map(regular_bg_map_ptr&& map)
Sets the map used by this regular background.
void set_map(const regular_bg_map_item& map_item)
Replaces the map used by this regular background with a new map created with the given regular_bg_map_item.
void set_map(const regular_bg_map_item& map_item, int map_index)
Replaces the map used by this regular background with a new map created with the given regular_bg_map_item.
void set_item(const regular_bg_item& item)
Replaces the tiles, the color palette and the map used by this regular background with the created with the given regular_bg_item.
void set_item(const regular_bg_item& item, int map_index)
Replaces the tiles, the color palette and the map used by this regular background with the created with the given regular_bg_item.
auto x() const -> fixed
Returns the horizontal position of the regular background (relative to its camera, if it has one).
void set_x(fixed x)
Sets the horizontal position of the regular background (relative to its camera, if it has one).
auto y() const -> fixed
Returns the vertical position of the regular background (relative to its camera, if it has one).
void set_y(fixed y)
Sets the vertical position of the regular background (relative to its camera, if it has one).
auto position() const -> const fixed_point&
Returns the position of the regular background (relative to its camera, if it has one).
void set_position(fixed x, fixed y)
Sets the position of the regular background (relative to its camera, if it has one).
void set_position(const fixed_point& position)
Sets the position of the regular background (relative to its camera, if it has one).
auto priority() const -> int
Returns the priority of the regular background relative to sprites and other backgrounds.
void set_priority(int priority)
Sets the priority of the regular background relative to sprites and other backgrounds.
auto z_order() const -> int
Returns the priority of the regular background relative to other backgrounds, excluding sprites.
void set_z_order(int z_order)
Sets the priority of the regular background relative to other backgrounds, excluding sprites.
void put_above()
Modify this regular background to be drawn above all of the other backgrounds with the same priority.
void put_below()
Modify this regular background to be drawn below all of the other backgrounds with the same priority.
auto mosaic_enabled() const -> bool
Indicates if the mosaic effect must be applied to this regular background or not.
void set_mosaic_enabled(bool mosaic_enabled)
Sets if the mosaic effect must be applied to this regular background or not.
auto blending_enabled() const -> bool
Indicates if blending must be applied to this regular background or not.
void set_blending_enabled(bool blending_enabled)
Sets if blending must be applied to this regular background or not.
auto blending_top_enabled() const -> bool
Indicates if this regular background is part of the blending top layer or not.
void set_blending_top_enabled(bool blending_top_enabled)
Sets if this regular background is part of the blending top layer or not.
auto blending_bottom_enabled() const -> bool
Indicates if this regular background is part of the blending bottom layer or not.
void set_blending_bottom_enabled(bool blending_bottom_enabled)
Sets if this regular background is part of the blending bottom layer or not.
auto visible() const -> bool
Indicates if this regular background must be committed to the GBA or not.
void set_visible(bool visible)
Sets if this regular background must be committed to the GBA or not.
auto visible_in_window(const window& window) const -> bool
Indicates if this regular background is visible in the given window or not.
void set_visible_in_window(bool visible, window& window)
Sets if this regular background must be visible in the given window or not.
auto camera() const -> const optional<camera_ptr>&
Returns the camera_ptr attached to this regular background (if any).
void set_camera(const camera_ptr& camera)
Sets the camera_ptr attached to this regular background.
void set_camera(camera_ptr&& camera)
Sets the camera_ptr attached to this regular background.
void set_camera(const optional<camera_ptr>& camera)
Sets or removes the camera_ptr attached to this regular background.
void set_camera(optional<camera_ptr>&& camera)
Sets or removes the camera_ptr attached to this regular background.
void remove_camera()
Removes the camera_ptr attached to this regular background (if any).
auto attributes() const -> regular_bg_attributes
Returns the attributes to commit to the GBA for this regular background.
void set_attributes(const regular_bg_attributes& attributes)
Sets the attributes to commit to the GBA for this regular background.
auto hw_id() const -> optional<int>
Returns the hardware ID assigned to this background or bn::nullopt if no hardware ID has been assigned.
auto handle() const -> const void*
Returns the internal handle.
void swap(regular_bg_ptr& other)
Exchanges the contents of this regular_bg_ptr with those of the other one.

Friends

void swap(regular_bg_ptr& a, regular_bg_ptr& b)
Exchanges the contents of a regular_bg_ptr with those of another one.
auto operator==(const regular_bg_ptr& a, const regular_bg_ptr& b) -> bool defaulted
Default equal operator.

Function documentation

static regular_bg_ptr bn::regular_bg_ptr::create(fixed x, fixed y, const regular_bg_item& item)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(fixed x, fixed y, const regular_bg_item& item, int map_index)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
map_index Index of the map to reference in item.map_item().
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(const fixed_point& position, const regular_bg_item& item)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
position Position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(const fixed_point& position, const regular_bg_item& item, int map_index)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
position Position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
map_index Index of the map to reference in item.map_item().
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(fixed x, fixed y, regular_bg_map_ptr map)

Creates a regular_bg_ptr from the given regular_bg_map_ptr.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
map regular_bg_map_ptr used by the regular background.
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(const fixed_point& position, regular_bg_map_ptr map)

Creates a regular_bg_ptr from the given regular_bg_map_ptr.

Parameters
position Position of the regular background.
map regular_bg_map_ptr used by the regular background.
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(const regular_bg_builder& builder)

Creates a regular_bg_ptr from a regular_bg_builder reference.

Parameters
builder regular_bg_builder reference.
Returns The requested regular_bg_ptr.

static regular_bg_ptr bn::regular_bg_ptr::create(regular_bg_builder&& builder)

Creates a regular_bg_ptr from a moved regular_bg_builder.

Parameters
builder regular_bg_builder to move.
Returns The requested regular_bg_ptr.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(fixed x, fixed y, const regular_bg_item& item)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(fixed x, fixed y, const regular_bg_item& item, int map_index)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
map_index Index of the map to reference in item.map_item().
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(const fixed_point& position, const regular_bg_item& item)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
position Position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(const fixed_point& position, const regular_bg_item& item, int map_index)

Creates a regular_bg_ptr from the given regular_bg_item.

Parameters
position Position of the regular background.
item regular_bg_item containing the required information to generate the regular background.
map_index Index of the map to reference in item.map_item().
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(fixed x, fixed y, regular_bg_map_ptr map)

Creates a regular_bg_ptr from the given regular_bg_map_ptr.

Parameters
x Horizontal position of the regular background.
y Vertical position of the regular background.
map regular_bg_map_ptr used by the regular background.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(const fixed_point& position, regular_bg_map_ptr map)

Creates a regular_bg_ptr from the given regular_bg_map_ptr.

Parameters
position Position of the regular background.
map regular_bg_map_ptr used by the regular background.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(const regular_bg_builder& builder)

Creates a regular_bg_ptr from a regular_bg_builder reference.

Parameters
builder regular_bg_builder reference.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

static optional<regular_bg_ptr> bn::regular_bg_ptr::create_optional(regular_bg_builder&& builder)

Creates a regular_bg_ptr from a moved regular_bg_builder.

Parameters
builder regular_bg_builder to move.
Returns The requested regular_bg_ptr if it could be allocated; bn::nullopt otherwise.

bn::regular_bg_ptr::regular_bg_ptr(const regular_bg_ptr& other)

Copy constructor.

Parameters
other regular_bg_ptr to copy.

bn::regular_bg_ptr::regular_bg_ptr(regular_bg_ptr&& other) noexcept

Move constructor.

Parameters
other regular_bg_ptr to move.

regular_bg_ptr& bn::regular_bg_ptr::operator=(const regular_bg_ptr& other)

Copy assignment operator.

Parameters
other regular_bg_ptr to copy.
Returns Reference to this.

regular_bg_ptr& bn::regular_bg_ptr::operator=(regular_bg_ptr&& other) noexcept

Move assignment operator.

Parameters
other regular_bg_ptr to move.
Returns Reference to this.

bool bn::regular_bg_ptr::big() const

Indicates if this regular background is big or not.

Big backgrounds are slower CPU wise, but can have any width or height multiple of 256 pixels.

void bn::regular_bg_ptr::set_tiles(const regular_bg_tiles_ptr& tiles)

Sets the tiles used by this regular background.

Parameters
tiles regular_bg_tiles_ptr to copy.

It must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_tiles(regular_bg_tiles_ptr&& tiles)

Sets the tiles used by this regular background.

Parameters
tiles regular_bg_tiles_ptr to move.

It must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_tiles(const regular_bg_tiles_item& tiles_item)

Replaces the tiles used by this regular background with a new tile set created with the given regular_bg_tiles_item.

Parameters
tiles_item It creates the new background tiles to use by this regular background.

Before creating a new background tile set, the regular_bg_tiles_ptr used by this regular background is removed, so VRAM usage is reduced.

The new background tiles must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_palette(const bg_palette_ptr& palette)

Sets the color palette to use by this regular background.

Parameters
palette bg_palette_ptr to copy.

It must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_palette(bg_palette_ptr&& palette)

Sets the color palette to use by this regular background.

Parameters
palette bg_palette_ptr to move.

It must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_palette(const bg_palette_item& palette_item)

Replaces the color palette used by this regular background with a new one created with the given bg_palette_item.

Parameters
palette_item It creates the color palette to use by this regular background.

Before creating a new color palette, the bg_palette_ptr used by this regular background is removed, so VRAM usage is reduced.

The new color palette must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_tiles_and_palette(regular_bg_tiles_ptr tiles, bg_palette_ptr palette)

Sets the tiles and the color palette to use by this regular background.

Parameters
tiles regular_bg_tiles_ptr to set.
palette bg_palette_ptr to set.

The given parameters must be compatible with the current map of the regular background.

void bn::regular_bg_ptr::set_tiles_and_palette(const regular_bg_tiles_item& tiles_item, const bg_palette_item& palette_item)

Replaces the tiles and the color palette used by this regular background with the created with the given regular_bg_tiles_item and bg_palette_item.

Parameters
tiles_item It creates the new background tiles to use by this regular background.
palette_item It creates the color palette to use by this regular background.

Before creating new resources, the resources used by this regular background are removed, so VRAM usage is reduced.

void bn::regular_bg_ptr::set_map(const regular_bg_map_ptr& map)

Sets the map used by this regular background.

Parameters
map regular_bg_map_ptr to copy.

void bn::regular_bg_ptr::set_map(regular_bg_map_ptr&& map)

Sets the map used by this regular background.

Parameters
map regular_bg_map_ptr to move.

void bn::regular_bg_ptr::set_map(const regular_bg_map_item& map_item)

Replaces the map used by this regular background with a new map created with the given regular_bg_map_item.

Parameters
map_item It creates the new map to use by this regular background.

Before creating a new map, the regular_bg_map_ptr used by this regular background is removed, so VRAM usage is reduced.

void bn::regular_bg_ptr::set_map(const regular_bg_map_item& map_item, int map_index)

Replaces the map used by this regular background with a new map created with the given regular_bg_map_item.

Parameters
map_item It creates the new map to use by this regular background.
map_index Index of the map to reference in map_item.

Before creating a new map, the regular_bg_map_ptr used by this regular background is removed, so VRAM usage is reduced.

void bn::regular_bg_ptr::set_item(const regular_bg_item& item)

Replaces the tiles, the color palette and the map used by this regular background with the created with the given regular_bg_item.

Parameters
item It creates the resources to use by this regular background.

Before creating new resources, the resources used by this regular background are removed, so VRAM usage is reduced.

void bn::regular_bg_ptr::set_item(const regular_bg_item& item, int map_index)

Replaces the tiles, the color palette and the map used by this regular background with the created with the given regular_bg_item.

Parameters
item It creates the resources to use by this regular background.
map_index Index of the map to reference in item.map_item().

Before creating new resources, the resources used by this regular background are removed, so VRAM usage is reduced.

void bn::regular_bg_ptr::set_position(fixed x, fixed y)

Sets the position of the regular background (relative to its camera, if it has one).

Parameters
x Horizontal position of the regular background (relative to its camera, if it has one).
y Vertical position of the regular background (relative to its camera, if it has one).

int bn::regular_bg_ptr::priority() const

Returns the priority of the regular background relative to sprites and other backgrounds.

Backgrounds with higher priority are drawn first (and therefore can be covered by later sprites and backgrounds).

void bn::regular_bg_ptr::set_priority(int priority)

Sets the priority of the regular background relative to sprites and other backgrounds.

Parameters
priority Priority in the range [0..3].

Backgrounds with higher priority are drawn first (and therefore can be covered by later sprites and backgrounds).

int bn::regular_bg_ptr::z_order() const

Returns the priority of the regular background relative to other backgrounds, excluding sprites.

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

void bn::regular_bg_ptr::set_z_order(int z_order)

Sets the priority of the regular background relative to other backgrounds, excluding sprites.

Parameters
z_order Priority relative to other backgrounds, excluding sprites, in the range [-32767..32767].

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

bool bn::regular_bg_ptr::blending_enabled() const

Indicates if blending must be applied to this regular background or not.

Blending is applied to this regular background by making it part of the blending top layer.

void bn::regular_bg_ptr::set_blending_enabled(bool blending_enabled)

Sets if blending must be applied to this regular background or not.

Blending is applied to this regular background by making it part of the blending top layer.

void bn::regular_bg_ptr::set_camera(const camera_ptr& camera)

Sets the camera_ptr attached to this regular background.

Parameters
camera camera_ptr to copy to this regular background.

void bn::regular_bg_ptr::set_camera(camera_ptr&& camera)

Sets the camera_ptr attached to this regular background.

Parameters
camera camera_ptr to move to this regular background.

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

Sets or removes the camera_ptr attached to this regular background.

Parameters
camera Optional camera_ptr to copy to this regular background.

void bn::regular_bg_ptr::set_camera(optional<camera_ptr>&& camera)

Sets or removes the camera_ptr attached to this regular background.

Parameters
camera Optional camera_ptr to move to this regular background.

optional<int> bn::regular_bg_ptr::hw_id() const

Returns the hardware ID assigned to this background or bn::nullopt if no hardware ID has been assigned.

Normally you should not need to call this function, but it can be useful for messing with HDMA for example.

A background doesn't have an assigned hardware ID if it is not visible.

Assigned hardware ID can change after calling this method if some properties of this background or others are updated.

Call this method at your own risk.

void bn::regular_bg_ptr::swap(regular_bg_ptr& other)

Exchanges the contents of this regular_bg_ptr with those of the other one.

Parameters
other regular_bg_ptr to exchange the contents with.

void swap(regular_bg_ptr& a, regular_bg_ptr& b)

Exchanges the contents of a regular_bg_ptr with those of another one.

Parameters
a First regular_bg_ptr to exchange the contents with.
b Second regular_bg_ptr to exchange the contents with.