diff --git a/README.md b/README.md index 30c4890..24ef360 100644 --- a/README.md +++ b/README.md @@ -171,9 +171,10 @@ screen.render(); - [Special Elements](#special-elements) - [Terminal](#terminal-from-box) - [Image](#image-from-box) - - [Layout](#layout-from-element) - [PNG](#png-from-box) + - [W3MImage](#w3mimage-from-box) - [Video](#video-from-box) + - [Layout](#layout-from-element) ### Other @@ -1396,6 +1397,75 @@ using `w3mimgdisplay` (using a [W3MImage element](#w3mimage-from-box)). - See [W3MImage element](#w3mimage-from-box) +#### PNG (from Box) + +Convert any `.png` file (or `.gif`, see below) to an ANSI image and display it +as an element. This differs from the `Image` element in that it uses blessed's +internal PNG parser and does not require external dependencies. + +Blessed uses an internal from-scratch PNG reader because no other javascript +PNG reader supports Adam7 interlaced images (much less pass the png test +suite). + +The blessed PNG reader supports adam7 deinterlacing, animation (APNG), all +color types, bit depths 1-32, alpha, alpha palettes, and outputs scaled bitmaps +(cellmaps) in blessed for efficient rendering to the screen buffer. It also +uses some code from libcaca/libcucul to add density ASCII characters in order +to give the image more detail in the terminal. + +If a corrupt PNG or a non-PNG is passed in, blessed will display error text in +the element. + +`.gif` files are also supported via a javascript implementation (they are +internally converted to bitmaps and fed to the PNG renderer). Any other image +format is support only if the user has imagemagick (`convert` and `identify`) +installed. + +##### Options: + +- Inherits all from Box. +- __file__ - URL or path to PNG file. Can also be a buffer. +- __scale__ - Scale cellmap down (`0-1.0`) from its original pixel width/height + (Default: `1.0`). +- __width/height__ - This differs from other element's `width` or `height` in + that only one of them is needed: blessed will maintain the aspect ratio of + the image as it scales down to the proper number of cells. __NOTE__: PNG's + are always automatically shrunken to size (based on scale) if a `width` or + `height` is not given. +- __ascii__ - Add various "density" ASCII characters over the rendering to give + the image more detail, similar to libcaca/libcucul (the library mplayer uses + to display videos in the terminal). +- __animate__ - Whether to animate if the image is an APNG/animating GIF. If + false, only display the first frame or IDAT (Default: `true`). +- __speed__ - Set the speed of animation. Slower: `0.0-1.0`. Faster: `1-1000`. + It cannot go faster than 1 frame per millisecond, so 1000 is the fastest. + (Default: 1.0) +- __optimization__ - `mem` or `cpu`. If optimizing for memory, animation frames + will be rendered to bitmaps _as the animation plays_, using less memory. + Optimizing for cpu will precompile all bitmaps beforehand, which may be + faster, but might also OOM the process on large images. (Default: `mem`). + +##### Properties: + +- Inherits all from Box. +- __img__ - Image object from the png reader. +- __img.width__ - Pixel width. +- __img.height__ - Pixel height. +- __img.bmp__ - Image bitmap. +- __img.cellmap__ - Image cellmap (bitmap scaled down to cell size). + +##### Events: + +- Inherits all from Box. + +##### Methods: + +- Inherits all from Box. +- __setImage(file)__ - Set the image in the box to a new path. File can be a + path, url, or buffer. +- __clearImage()__ - Clear the image. + + #### W3MImage (from Box) Display an image in the terminal (jpeg, png, gif) using w3mimgdisplay. Requires @@ -1434,6 +1504,32 @@ terminals. node supports `spawnSync`. +#### Video (from Box) + +A box which spins up a pseudo terminal in order to render a video via `mplayer +-vo caca` or `mpv --vo caca`. Requires `mplayer` or `mpv` to be installed with +libcaca support. + +##### Options: + +- Inherits all from Box. +- __file__ - Video to play. +- __start__ - Start time in seconds. + +##### Properties: + +- Inherits all from Box. +- __tty__ - The terminal element running `mplayer` or `mpv`. + +##### Events: + +- Inherits all from Box. + +##### Methods: + +- Inherits all from Box. + + #### Layout (from Element) A layout which can position children automatically based on a `renderer` method @@ -1608,101 +1704,6 @@ for (var i = 0; i < 10; i++) { ``` -#### PNG (from Box) - -Convert any `.png` file (or `.gif`, see below) to an ANSI image and display it -as an element. This differs from the `Image` element in that it uses blessed's -internal PNG parser and does not require external dependencies. - -Blessed uses an internal from-scratch PNG reader because no other javascript -PNG reader supports Adam7 interlaced images (much less pass the png test -suite). - -The blessed PNG reader supports adam7 deinterlacing, animation (APNG), all -color types, bit depths 1-32, alpha, alpha palettes, and outputs scaled bitmaps -(cellmaps) in blessed for efficient rendering to the screen buffer. It also -uses some code from libcaca/libcucul to add density ASCII characters in order -to give the image more detail in the terminal. - -If a corrupt PNG or a non-PNG is passed in, blessed will display error text in -the element. - -`.gif` files are also supported via a javascript implementation (they are -internally converted to bitmaps and fed to the PNG renderer). Any other image -format is support only if the user has imagemagick (`convert` and `identify`) -installed. - -##### Options: - -- Inherits all from Box. -- __file__ - URL or path to PNG file. Can also be a buffer. -- __scale__ - Scale cellmap down (`0-1.0`) from its original pixel width/height - (Default: `1.0`). -- __width/height__ - This differs from other element's `width` or `height` in - that only one of them is needed: blessed will maintain the aspect ratio of - the image as it scales down to the proper number of cells. __NOTE__: PNG's - are always automatically shrunken to size (based on scale) if a `width` or - `height` is not given. -- __ascii__ - Add various "density" ASCII characters over the rendering to give - the image more detail, similar to libcaca/libcucul (the library mplayer uses - to display videos in the terminal). -- __animate__ - Whether to animate if the image is an APNG/animating GIF. If - false, only display the first frame or IDAT (Default: `true`). -- __speed__ - Set the speed of animation. Slower: `0.0-1.0`. Faster: `1-1000`. - It cannot go faster than 1 frame per millisecond, so 1000 is the fastest. - (Default: 1.0) -- __optimization__ - `mem` or `cpu`. If optimizing for memory, animation frames - will be rendered to bitmaps _as the animation plays_, using less memory. - Optimizing for cpu will precompile all bitmaps beforehand, which may be - faster, but might also OOM the process on large images. (Default: `mem`). - -##### Properties: - -- Inherits all from Box. -- __img__ - Image object from the png reader. -- __img.width__ - Pixel width. -- __img.height__ - Pixel height. -- __img.bmp__ - Image bitmap. -- __img.cellmap__ - Image cellmap (bitmap scaled down to cell size). - -##### Events: - -- Inherits all from Box. - -##### Methods: - -- Inherits all from Box. -- __setImage(file)__ - Set the image in the box to a new path. File can be a - path, url, or buffer. -- __clearImage()__ - Clear the image. - - -#### Video (from Box) - -A box which spins up a pseudo terminal in order to render a video via `mplayer --vo caca` or `mpv --vo caca`. Requires `mplayer` or `mpv` to be installed with -libcaca support. - -##### Options: - -- Inherits all from Box. -- __file__ - Video to play. -- __start__ - Start time in seconds. - -##### Properties: - -- Inherits all from Box. -- __tty__ - The terminal element running `mplayer` or `mpv`. - -##### Events: - -- Inherits all from Box. - -##### Methods: - -- Inherits all from Box. - - ### Other diff --git a/lib/widget.js b/lib/widget.js index 6dcfd41..dfb7993 100644 --- a/lib/widget.js +++ b/lib/widget.js @@ -36,10 +36,10 @@ widget.classes = [ 'ListTable', 'Terminal', 'Image', - 'W3MImage', - 'Layout', 'PNG', - 'Video' + 'W3MImage', + 'Video', + 'Layout' ]; widget.classes.forEach(function(name) {