Type Alias 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:
Aliased Type§
struct NcVisual { /* private fields */ }
Implementations§
source§impl NcVisual
impl NcVisual
§NcVisual Constructors & destructors
sourcepub fn from_bgra<'a>(
bgra: &[u8],
rows: u32,
rowstride: u32,
cols: u32
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn from_file<'a>(file: &str) -> NcResult<&'a mut NcVisual>
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().
sourcepub 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>
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().
sourcepub fn from_sixel<'a>(
sequence: &str,
len_y: u32,
len_x: u32
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn from_rgb_loose<'a>(
rgb: &[u8],
rows: u32,
rowstride: u32,
cols: u32,
alpha: u8
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn from_rgb_packed<'a>(
rgb: &[u8],
rows: u32,
rowstride: u32,
cols: u32,
alpha: u8
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn from_rgba<'a>(
rgba: &[u8],
rows: u32,
rowstride: u32,
cols: u32
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn from_palidx<'a>(
data: &[u8],
rows: u32,
rowstride: u32,
cols: u32,
palsize: u8,
pstride: u32,
palette: &NcPalette
) -> NcResult<&'a mut NcVisual>
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
NcChannel
s.
C style function: ncvisual_from_palidx().
sourcepub fn destroy(&mut self)
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
impl NcVisual
§NcVisual Methods
sourcepub fn decode(&mut self) -> NcResult<NcResult_i32>
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().
sourcepub fn decode_loop(&mut self) -> NcResult<NcResult_i32>
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().
sourcepub fn geom(
&self,
nc: Option<&Nc>,
vopts: Option<&NcVisualOptions>
) -> NcResult<NcVisualGeometry>
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.
§See also
C style function: ncvisual_geom().
sourcepub fn media_defblitter(nc: &Nc, scale: impl Into<NcScale>) -> NcBlitter
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
thenNcBlitter::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().
sourcepub fn polyfill_yx(
&mut self,
y: u32,
x: u32,
rgba: impl Into<NcRgba>
) -> NcResult<()>
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().
sourcepub unsafe fn blit(
&mut self,
nc: &mut Nc,
options: Option<&NcVisualOptions>
) -> NcResult<&mut NcPlane>
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 flagNcVisualFlag::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().
sourcepub fn resize(&mut self, rows: u32, cols: u32) -> NcResult<()>
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().
sourcepub fn resize_noninterpolative(&mut self, rows: u32, cols: u32) -> NcResult<()>
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().
sourcepub fn rotate(&mut self, rads: f64) -> NcResult<()>
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().
sourcepub fn at_yx(&self, y: u32, x: u32) -> NcResult<NcPixel>
pub fn at_yx(&self, y: u32, x: u32) -> NcResult<NcPixel>
Gets the specified pixel from this NcVisual.
C style function: ncvisual_at_yx().
sourcepub fn set_yx(
&mut self,
y: u32,
x: u32,
pixel: impl Into<NcPixel>
) -> NcResult<()>
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().
sourcepub fn simple_streamer(
&mut self,
options: &mut NcVisualOptions,
time: &NcTime,
curry: Option<&mut NcPlane>
) -> NcResult<()>
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().
sourcepub fn subtitle_plane(&self, parent: &mut NcPlane) -> NcResult<&mut NcPlane>
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
impl NcVisual
§NcDirectF
Constructors & destructors
sourcepub fn ncdirectf_from_file<'a>(
ncd: &mut NcDirect,
file: &str
) -> NcResult<&'a mut NcVisual>
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().
sourcepub fn ncdirectf_free(&mut self)
pub fn ncdirectf_free(&mut self)
Frees a NcVisual
returned from ncdirectf_from_file().
C style function: ncdirectf_free().
source§impl NcVisual
impl NcVisual
§NcDirectF
Methods
sourcepub fn ncdirectf_render(
&mut self,
ncd: &mut NcDirect,
options: &NcVisualOptions
) -> NcResult<&mut NcPlane>
pub fn ncdirectf_render( &mut self, ncd: &mut NcDirect, options: &NcVisualOptions ) -> NcResult<&mut NcPlane>
Same as NcDirect.render_frame()
, except frame
must already have
been loaded.
A loaded frame may be rendered in different ways before it is destroyed.
C style function: ncdirectf_render().
sourcepub fn ncdirectf_geom(
&mut self,
ncd: &mut NcDirect,
options: &NcVisualOptions
) -> NcResult<NcVisualGeometry>
pub fn ncdirectf_geom( &mut self, ncd: &mut NcDirect, options: &NcVisualOptions ) -> NcResult<NcVisualGeometry>
Having loaded the frame
, get the geometry of a potential render.
C style function: ncdirectf_geom().