Type Definition libnotcurses_sys::NcVisual

source ·

pub type NcVisual = ncvisual;

Expand description

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:

Implementations§

source §

impl NcVisual

NcVisual Constructors & destructors

source

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

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

C style function: ncvisual_from_bgra().

source

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

Opens an NcVisual at file, extracts the codec and parameters and decodes the first image to memory.

C style function: ncvisual_from_file().

source

pub fn from_plane<'a>( plane: &NcPlane, blitter: impl Into<NcBlitter>, beg_y: Option<u32>, beg_x: Option<u32>, len_y: Option<u32>, len_x: Option<u32> ) -> 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.

Use None for either or both of beg_y and beg_x in order to use the current cursor position along that axis.

Use None for either or both of len_y and len_x in order to go through the boundary of the plane in that axis (same as 0).

C style function: ncvisual_from_plane().

source

pub fn from_sixel<'a>( sequence: &str, len_y: u32, len_x: u32 ) -> NcResult<&'a mut NcVisual>

Constructs an NcVisual from a nul-terminated Sixel control sequence.

C style function: ncvisual_from_sixel().

source

pub fn from_rgb_loose<'a>( rgb: &[u8], rows: u32, rowstride: u32, cols: u32, alpha: u8 ) -> 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().

source

pub fn from_rgb_packed<'a>( rgb: &[u8], rows: u32, rowstride: u32, cols: u32, alpha: u8 ) -> 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().

source

pub fn from_rgba<'a>( rgba: &[u8], rows: u32, rowstride: u32, cols: u32 ) -> 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().

source

pub fn from_palidx<'a>( data: &[u8], rows: u32, rowstride: u32, cols: u32, palsize: u8, pstride: u32, palette: &NcPalette ) -> NcResult<&'a mut NcVisual>

Like from_rgba, but data is pstride-byte palette-indexed pixels, arranged in rows lines of rowstride bytes each, composed of cols pixels.

palette is an array of at least palsize NcChannels.

C style function: ncvisual_from_palidx().

source

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().

source §

impl NcVisual

NcVisual Methods

source

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

Extracts the next frame from the NcVisual.

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

C style function: ncvisual_decode().

source

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

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().

source

pub fn geom( &self, nc: Option<&Nc>, vopts: Option<&NcVisualOptions> ) -> NcResult<NcVisualGeometry>

Returns NcVisualGeometry.

if Nc is not provided, only pix_yx will be filled in, with the true pixel geometry of the current NcVisual.

Additionally cdim_yx and maxpixel_yx are only ever filled in if we know them, and maxpixel_yx is only defined for NcBlitter::PIXEL.

pub fn media_defblitter(nc: &Nc, scale: impl Into<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, NcBlitter::Ascii.
otherwise, if not using NcScale::Stretch then NcBlitter::Half.
otherwise, if sextants are not known to be good, NcBlitter::Quadrant.
otherwise NcBlitter::Sextant

QUADRANT and SEXTANT both distort the original aspect ratio, thus they are only used alongside NcScale::Stretch, while Half is used otherwise.

C style function: ncvisual_media_defblitter().

source

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

Polyfills at the specified location using rgba.

C style function: ncvisual_polyfill_yx().

source

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

Renders the decoded frame according to the provided options.

There are 3 options for choosing the the plane used for rendering:

if the options have set the flag NcVisualFlag::ChildPlane then there must be a plane, which will be the father of the one created.
if the flag is not set and there is no plane, a new plane is created as root of a new pile.
if the flag is not set and there is a plane, we render to it.

A subregion of the visual can be rendered using beg_y, beg_x, len_y, and len_x.

It is an error to specify any region beyond the boundaries of the frame.

Returns the (possibly newly-created) plane to which we drew.

Pixels may not be blitted to the standard plane.

Safety

You must be careful not to end up with multiple exclusive references to the returned NcPlane, or with one exclusive reference and one or more shared references.

C style function: ncvisual_blit().

source

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

Resizes the visual to cols X rows pixels.

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

C style function: ncvisual_resize().

source

pub fn resize_noninterpolative(&mut self, rows: u32, cols: u32) -> 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().

source

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().

source

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

Gets the specified pixel from this NcVisual.

C style function: ncvisual_at_yx().

source

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

Sets the specified pixel.

C style function: ncvisual_set_yx().

source

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 None, subtitles will not be displayed.

C style function: ncvisual_simple_streamer().

source

pub fn subtitle_plane(&self, parent: &mut NcPlane) -> NcResult<&mut NcPlane>

If a subtitle ought be displayed at this time, return a new plane

The returned plane is bound to parent and contains the subtitle, which might be text or graphics (depending on the input format).

C style function: ncvisual_subtitle_plane().

source §

impl NcVisual

`NcDirectF` Constructors & destructors

source

pub fn ncdirectf_from_file<'a>( ncd: &mut NcDirect, file: &str ) -> NcResult<&'a mut NcVisual>

Loads media from disk, but do not yet renders it (presumably because you want to get its geometry via ncdirectf_geom(), or to use the same file with ncdirectf_render() multiple times).

You must destroy the result with ncdirectf_free();

C style function: ncdirectf_from_file().

source