Documentation fixed and improved on ScreenBuffer HD

CHANGELOG

@@ -1,8 +1,14 @@
 
+v1.1.1
+------
+
+Documentation fixed and improved on ScreenBuffer HD
+
+
 v1.1.0
 ------
 
-New: ScreenBufferHD, a 24-bit screen buffer with composition (issue #9)
+New: ScreenBufferHD, a 32-bit (RGBA) screen buffer with composition (issue #9).
 
 
 v1.0.5

README.md

@@ -52,7 +52,7 @@ Click any image to see the documentation related to the feature!
 
 ## Key features
 
-*New:* [ScreenBuffer HD](doc/screenbuffer-hd.md#top) (*beta*), 24-bit surfaces with composition
+*New:* [ScreenBuffer HD](doc/screenbuffer-hd.md#top) (*beta*), 32-bit (RGBA) surfaces with composition
 
 * [colors, 256 colors or even 24-bit colors](doc/low-level.md#ref.colors), if the terminal supports it
 * [styles (bold, underline, italic, and many more)](doc/low-level.md#ref.styles)

doc/screenbuffer-hd.md

@@ -8,7 +8,7 @@
 
 *This feature is still in beta/unstable version, it is not under the SemVer contract.*
 
-This is the 32-bit version of [the ScreenBuffer](screenbuffer.md#ref.ScreenBuffer), it subclasses it.
+This is the 32-bit (RGBA) version of [the ScreenBuffer](screenbuffer.md#ref.ScreenBuffer), it subclasses it.
 
 See the [the ScreenBuffer documentation](screenbuffer.md#ref.ScreenBuffer) for the common parts:
 **only HD specific features are listed here.**
@@ -41,12 +41,15 @@ When drawing to another surface, blending options can be given like *opacity* an
 	* [.draw()](#ref.ScreenBufferHD.draw)
 
 * [The Attribute Object](#ref.ScreenBufferHD.attributes)
+* [The Built-In Blend Functions](#ref.ScreenBufferHD.blendFn)
 
 
 
 <a name="ref.ScreenBufferHD.create"></a>
 ### ScreenBuffer.create( options )
 
+* blending `false` or `object`, see [.blending](#ref.ScreenBufferHD.blending)
+
 This creates a ScreenBufferHD instance with the appropriate options.
 
 
@@ -56,11 +59,23 @@ This creates a ScreenBufferHD instance with the appropriate options.
 
 Either `false` or an `object`, the is default value for [*.draw()*](#ref.ScreenBufferHD.draw)'s blending option.
 
+If it's an `object`, it has the following properties:
+* fn `function` (optional, default to `ScreenBufferHD.blendFn.normal`) it is the function used to blend rgb channels.
+  see the [built-in blend functions](#ref.ScreenBufferHD.blendFn)
+* opacity `number` (optional, default to `1`) this is the opacity of the surface, *alpha channel* is multiplied by this value
+* blendSrcFgWithDstBg `boolean` (optional, default to `false`), if:
+	* false: the **foreground** color of the source is blended with the **foreground** color of the destination
+	  to produce the new **foreground** color
+	* true: the **foreground** color of the source is blended with the **background** color of the destination
+	  to produce the new **foreground** color
+
 
 
 <a name="ref.ScreenBufferHD.draw"></a>
 ### .draw( [options] )
 
+* blending `false` or `object`, see [.blending](#ref.ScreenBufferHD.blending)
+
 This draws the current *screenBufferHD* into its *dst* (destination), which is either a `Terminal`
 or another `ScreenBufferHD` instance.
 
@@ -95,3 +110,25 @@ Available attributes are:
 * charTransparency `boolean` *character transparency*, anything drawn with that attribute
   will use the existing destination's character instead of its own character
 
+
+
+<a name="ref.ScreenBufferHD.blendFn"></a>
+### The Built-In Blend Functions
+
+`ScreenBufferHD.blendFn` is an object containing built-in blend functions.
+
+The result of those blend functions are **ALWAYS** alpha-mixed (using *alpha* and *opacity*) with the destination
+before writing it.
+
+* .normal: the source overwrite the destination
+* .multiply: the source and the destination are multiplied, producing in a darker image
+* .screen: this is the inverse of the *multiply* blending: the inverse of the source and the inverse of the destination
+  are multiplied, then inverted again, producing a brighter image
+* .overlay: it combines *multiply* and *screen* blend modes, the parts where the destination is light become lighter,
+  the parts where the destination is dark become darker
+* .hardLight: like *overlay* but swap source and destination, i.e. the parts where the source is light become lighter,
+  the parts where the source is dark become darker
+* .softLight: a softer version of *hardLight*
+
+See [Wikipedia blend modes page](https://en.wikipedia.org/wiki/Blend_modes) for details.
+

lib/ScreenBufferHD.js

@@ -204,8 +204,7 @@ ScreenBufferHD.prototype.blitterCellBlendingIterator = function blitterCellBlend
 	if (
 		! ( attr[ BPOS_BLENDING ] & STYLE_TRANSPARENCY ) &&
 		! ( attr[ BPOS_BLENDING ] & CHAR_TRANSPARENCY ) &&
-		attr[ BPOS_A ] === 255 &&
-		attr[ BPOS_BG_A ] === 255 &&
+		attr[ BPOS_A ] === 255 && attr[ BPOS_BG_A ] === 255 && opacity === 1 &&
 		blendFn === ScreenBufferHD.blendFn.normal
 	)
 	{
@@ -217,8 +216,7 @@ ScreenBufferHD.prototype.blitterCellBlendingIterator = function blitterCellBlend
 	if (
 		( attr[ BPOS_BLENDING ] & STYLE_TRANSPARENCY ) &&
 		( attr[ BPOS_BLENDING ] & CHAR_TRANSPARENCY ) &&
-		attr[ BPOS_A ] === 0 &&
-		attr[ BPOS_BG_A ] === 0
+		( ! opacity || ( attr[ BPOS_A ] === 0 && attr[ BPOS_BG_A ] === 0 ) )
 	)
 	{
 		// Fully transparent, do nothing

package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "256 colors, keys and mouse, input field, progress bars, screen buffer, text buffer, and many more... Whether you just need colors and styles, build a simple interactive command line tool or a complexe terminal app: this is the absolute terminal lib for Node.js!",
   "main": "lib/termkit.js",
   "directories": {