Struct beryllium::Palette

#[repr(transparent)]
pub struct Palette<'sdl> { /* fields omitted */ }

A palette of Color values.

The way that the Palette type works is slightly different from Rust's normal ownership model, so please pay attention as I explain.

A Palette value holds a pointer to a heap allocated SDL_Palette (wiki). That SDL_Palette has a pointer to the heap allocated Color values, along with a length, reference count, and version number.

When you set a Palette on a Surface or PixelFormat it moves some pointers and adjusts the reference count of the Palette. Now you have the Palette, and also that thing has the same Palette. An edit to the Palette data in either location will affect everyone's data. Having a &mut Palette does not mean that you have an exclusive path of access to the Palette contents.

As a result, I cannot allow you to ever construct a shared reference or unique reference to the Color data held inside the Palette. This means no Deref, Index, or IndexMut, no Iterators of any kind, none of that. This definitely makes the API of the Palette type not quite as fun as you might like.

You can allocate a Palette by calling SDLToken::new_palette and specifying how many Color values the Palette should hold. However, you generally do not need to do this yourself, because if a Surface or PixelFormat needs palette data it will automatically allocate a palette of the correct size when it is created.

All slots in a new Palette are initialized to opaque white (0xFF in all four color channels).

Methods

impl<'_> Palette<'_>

pub fn len(&self) -> usize

Gets the number of colors in the Palette

pub fn set_colors(
    &self,
    start: usize,
    new_colors: &[Color]
) -> Result<(), String>

Assigns a slice of colors into the Palette, starting at the position specified.

Colors that don't "fit" because they would trail off the end are not copied.

Failure

• start values >= the length will give an error.

pub fn get_color(&self, index: usize) -> Option<Color>

Gets the Color at the index specified.

Failure

• None if the index is out of bounds.

pub fn to_vec(&self) -> Vec<Color>

Creates a new Vec with the same colors as this Palette.

Trait Implementations

impl<'_> Drop for Palette<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl<'_> Clone for Palette<'_>

fn clone(&self) -> Self

Clones the colors into an entirely distinct Palette of the same length.

First a new palette of the same length is allocated, then all colors are copied over.

Panics

• If the SDL_Palette cannot be allocated this will panic. That essentially only happens if you're out of memory.
• If the colors cannot be copied over this will panic. It should be impossible for that to fail, but hey.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'sdl> Debug for Palette<'sdl>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.