.\" Automatically generated by Pandoc 2.5
.\"
.TH "notcurses_ncvisual" "3" "v1.3.1" "" ""
.hy
.SH NAME
.PP
notcurses_ncvisual \- notcurses multimedia
.SH SYNOPSIS
.PP
\f[B]#include <notcurses.h>\f[R]
.IP
.nf
\f[C]
typedef enum {
  NCSCALE_NONE,
  NCSCALE_SCALE,
  NCSCALE_STRETCH,
} ncscale_e;

typedef int\ (*streamcb)(struct notcurses*, struct ncvisual*, void*);
\f[R]
.fi
.PP
\f[B]bool notcurses_canopen(const struct notcurses* nc);\f[R]
.PP
\f[B]struct ncvisual* ncplane_visual_open(struct ncplane* nc, const
char* file, int* averr);\f[R]
.PP
\f[B]struct ncvisual* ncvisual_open_plane(struct notcurses* nc, const
char* file, int* averr, int y, int x, ncscale_e style);\f[R]
.PP
\f[B]void ncvisual_destroy(struct ncvisual* ncv);\f[R]
.PP
\f[B]struct AVFrame* ncvisual_decode(struct ncvisual* nc, int*
averr);\f[R]
.PP
\f[B]int ncvisual_render(const struct ncvisual* ncv, int begy, int begx,
int leny, int lenx);\f[R]
.PP
\f[B]int ncvisual_simple_streamer(struct notcurses* nc, struct ncvisual*
ncv, void* curry);\f[R]
.PP
\f[B]int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv,
int* averr, float timescale, streamcb streamer, void* curry);\f[R]
.PP
\f[B]struct ncplane* ncvisual_plane(struct ncvisual* ncv);\f[R]
.SH DESCRIPTION
.PP
The frame will be scaled to the size of the ncplane per the ncscale_e
style.
\f[B]ncvisual_render\f[R] actually blits the decoded frame to its
associated plane.
A subregion of the frame can be specified using \f[B]begx\f[R],
\f[B]begy\f[R], \f[B]lenx\f[R], and \f[B]leny\f[R].
To render the rectangle having its origin at \f[B]begy\f[R],
\f[B]begx\f[R] and the lower\-right corner, \-1 can be supplied as
\f[B]leny\f[R] and \f[B]lenx\f[R].
{0, 0, \-1, \-1} will thus render the entire visual.
Negative values for \f[B]begy\f[R] or \f[B]begx\f[R] are an error.
It is an error to specify any region beyond the boundaries of the frame.
Supplying zero for either \f[B]leny\f[R] or \f[B]lenx\f[R] will result
in a zero\-area rendering.
.SH RETURN VALUES
.PP
\f[B]notcurses_canopen\f[R] returns true if this functionality is
enabled, or false if Notcurses was not built with FFmpeg support.
\f[B]ncplane_visual_open\f[R] and \f[B]ncvisual_open_plane\f[R] return
an \f[B]ncvisual\f[R] object on success, or \f[B]NULL\f[R] on failure.
Success from these functions indicates that the specified \f[B]file\f[R]
was opened, and enough data was read to make a firm codec
identification.
It does not mean that the entire file is properly\-formed.
On failure, \f[B]averr\f[R] will be updated.
\f[B]ncvisual_decode\f[R] returns a valid \f[B]AVFrame\f[R] on success,
or \f[B]NULL\f[R] on error.
It likewise updates \f[B]averr\f[R] in the event of an error.
\f[B]ncvisual_render\f[R] returns the number of cells emitted, or \-1 on
error.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_ncplane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.