Type Definition libnotcurses_sys::NcVisual

type NcVisual = ncvisual;

A visual bit of multimedia.

It can be constructed from a rgba or bgra buffer.

The NcVisualOptions structure is used only by the following methods:

• .geom
• .render
• .simple_streamer

Implementations

impl NcVisual

NcVisual Constructors & destructors

pub fn from_bgra<'a>(
    bgra: &[u8],
    rows: NcDim,
    rowstride: NcDim,
    cols: NcDim
) -> NcResult<&'a mut NcVisual>

Like from_rgba, but ‘bgra’ is arranged as BGRA.

C style function: ncvisual_from_bgra().

pub fn from_file<'a>(file: &str) -> NcResult<&'a mut NcVisual>

Opens a visual at file, extracts the codec and parameters and decodes the first image to memory.

C style function: ncvisual_from_file().

pub fn from_plane<'a>(
    plane: &NcPlane,
    blitter: NcBlitter,
    beg_y: NcDim,
    beg_x: NcDim,
    len_y: NcDim,
    len_x: NcDim
) -> NcResult<&'a mut NcVisual>

Promotes an NcPlane to an NcVisual.

The plane may contain only spaces, half blocks, and full blocks. This will be checked, and any other glyph will result in an error.

This function exists so that planes can be subjected to NcVisual transformations. If possible, it’s better to create the ncvisual from memory using from_rgba.

C style function: ncvisual_from_plane().

pub fn from_rgb_loose<'a>(
    rgb: &[u8],
    rows: NcDim,
    rowstride: NcDim,
    cols: NcDim,
    alpha: NcComponent
) -> NcResult<&'a mut NcVisual>

Like from_rgba, but the pixels are 4-byte RGBX. Alpha is filled in throughout using ‘alpha’.

rowstride must be a multiple of 4.

C style function: ncvisual_from_rgb_loose().

pub fn from_rgb_packed<'a>(
    rgb: &[u8],
    rows: NcDim,
    rowstride: NcDim,
    cols: NcDim,
    alpha: NcComponent
) -> NcResult<&'a mut NcVisual>

Like from_rgba, but the pixels are 3-byte RGB. Alpha is filled in throughout using ‘alpha’.

C style function: ncvisual_from_rgb_packed().

pub fn from_rgba<'a>(
    rgba: &[u8],
    rows: NcDim,
    rowstride: NcDim,
    cols: NcDim
) -> NcResult<&'a mut NcVisual>

Prepares an NcVisual, and its underlying NcPlane, based off RGBA content in memory at rgba.

rgba is laid out as rows lines, each of which is rowstride bytes in length. Each line has cols 32-bit 8bpc RGBA pixels followed by possible padding (there will be rowstride - cols * 4 bytes of padding).

The total size of rgba is thus (rows * rowstride) bytes, of which (rows * cols * 4) bytes are actual non-padding data.

C style function: ncvisual_from_rgba().

pub fn destroy(&mut self)

Destroys this NcVisual.

Rendered elements will not be disrupted, but the visual can be neither decoded nor rendered any further.

C style function: ncvisual_destroy().

impl NcVisual

NcVisual Methods

pub fn at_yx(&self, y: NcDim, x: NcDim) -> NcResult<NcPixel>

Gets the specified pixel from this NcVisual.

C style function: ncvisual_at_yx().

pub fn decode(&mut self) -> NcResult<NcIntResult>

Extracts the next frame from the NcVisual.

Returns 0 for normal frames, and 1 to indicate EOF.

C style function: ncvisual_decode().

pub fn decode_loop(&mut self) -> NcResult<NcIntResult>

Extracts the next frame from the NcVisual, ala decode, but if we have reached the end, rewinds to the first frame.

A subsequent NcVisual.render will render the first frame, as if the ncvisual had been closed and reopened.

Returns 0 for normal frames and 1 to indicate EOF.

C style function: ncvisual_decode_loop().

pub fn geom(
    &self,
    nc: &Nc,
    options: &NcVisualOptions
) -> NcResult<(NcDim, NcDim, NcDim, NcDim)>

Gets the size and ratio of NcVisual pixels to output cells along the y→to_y and x→to_x axes.

Returns a tuple with (y, x, to_y, to_x)

An NcVisual of y by x pixels will require (y * to_y) by (x * to_x) cells for full output.

Errors on invalid blitter in options. Scaling is taken into consideration.

C style function: ncvisual_blitter_geom().

pub fn media_defblitter(nc: &Nc, scale: NcScale) -> NcBlitter

Gets the default media (not plot) blitter for this environment when using the specified scaling method.

Currently, this means:

• if lacking UTF-8, NCBLIT_1x1.
• otherwise, if not NCSCALE_STRETCH, NCBLIT_2x1.
• otherwise, if sextants are not known to be good, NCBLIT_2x2.
• otherwise NCBLIT_3x2 NCBLIT_2x2 and NCBLIT_3x2 both distort the original aspect ratio, thus NCBLIT_2x1 is used outside of NCSCALE_STRETCH.

C style function: ncvisual_media_defblitter().

pub fn polyfill_yx(&mut self, y: NcDim, x: NcDim, rgba: NcRgba) -> NcResult<()>

Polyfills at the specified location using rgba.

C style function: ncvisual_polyfill_yx().

pub fn render(
    &mut self,
    nc: &mut Nc,
    options: &NcVisualOptions
) -> NcResult<&mut NcPlane>

Renders the decoded frame to the specified NcPlane.

See NcVisualOptions.

C style function: ncvisual_render().

pub fn resize(&mut self, rows: NcDim, cols: NcDim) -> NcResult<()>

Resizes the visual to cols X rows pixels.

This is a lossy transformation, unless the size is unchanged.

C style function: ncvisual_resize().

pub fn resize_noninterpolative(
    &mut self,
    rows: NcDim,
    cols: NcDim
) -> NcResult<()>

Resizes the visual to in the image to rows X cols pixels, without interpolating the color values.

The original color is retained.

C style function: ncvisual_resize_noninterpolative().

pub fn rotate(&mut self, rads: f64) -> NcResult<()>

Rotates the visual rads radians.

Only M_PI/2 and -M_PI/2 are supported at the moment, but this will change. (FIXME)

C style function: ncvisual_rotate().

pub fn set_yx(&mut self, y: NcDim, x: NcDim, pixel: NcPixel) -> NcResult<()>

Sets the specified pixel.

C style function: ncvisual_set_yx().

pub fn simple_streamer(
    &mut self,
    options: &mut NcVisualOptions,
    time: &NcTime,
    curry: Option<&mut NcPlane>
) -> NcResult<()>

Displays frames.

Provide as an argument to ncvisual_stream().

If you’d like subtitles to be decoded, provide an ncplane as the curry. If the curry is NULL, subtitles will not be displayed.

C style function: ncvisual_simple_streamer().

pub fn subtitle(&self) -> NcResult<&str>

If a subtitle ought be displayed at this time, returns a heap-allocated copy of the UTF8 text.

C style function: ncvisual_subtitle().