rsvg - npm Package Compare versions

Comparing version 0.1.2 to 0.1.3

index.js

@@ -9,5 +9,14 @@ /*jshint node:true*/
 
+/**
+ * Represents one SVG file to be rendered. You can optionally pass the SVG file
+ * directly as an argument (Buffer or string) to the constructor. Otherwise the
+ * object is a writable stream and you can pipe a file into it.
+ *
+ * @constructor
+ * @param {(Buffer|string)} [buffer] - SVG file.
+ */
 function Rsvg(buffer) {
 	var self = this;
 
+	// Create proper options for the writable stream super constructor.
 	var options;
@@ -25,6 +34,10 @@ if (Buffer.isBuffer(buffer)) {
 
+	// Inheritance pattern: Invoke super constructor.
 	Writable.call(self, options);
 
+	// Create new instance of binding.
 	self.handle = new binding.Rsvg(buffer);
 
+	// When finished piping into this object, we need to tell the binding that by
+	// invoking the `close()` method.
 	self.on('finish', function() {
@@ -38,2 +51,3 @@ try {
 
+	// Define getter/setter for `baseURI` property.
 	Object.defineProperty(self, 'baseURI', {
@@ -50,2 +64,3 @@ configurable: true,
 
+	// Define getter/setter for `dpiX` property.
 	Object.defineProperty(self, 'dpiX', {
@@ -62,2 +77,3 @@ configurable: true,
 
+	// Define getter/setter for `dpiY` property.
 	Object.defineProperty(self, 'dpiY', {
@@ -74,2 +90,3 @@ configurable: true,
 
+	// Define getter for `width` property.
 	Object.defineProperty(self, 'width', {
@@ -83,2 +100,3 @@ configurable: true,
 
+	// Define getter for `height` property.
 	Object.defineProperty(self, 'height', {
@@ -92,10 +110,42 @@ configurable: true,
 }
+
+// Inherit from writable stream.
 util.inherits(Rsvg, Writable);
 
+/**
+ * Base URI.
+ * @member {string}
+ */
 Rsvg.prototype.baseURI = null;
+
+/**
+ * Horizontal resolution. Allowed values: >= 0.
+ * @member {number}
+ */
 Rsvg.prototype.dpiX = 90;
+
+/**
+ * Vertical resolution. Allowed values: >= 0.
+ * @member {number}
+ */
 Rsvg.prototype.dpiY = 90;
+
+/**
+ * Image width. Always integer.
+ * @readonly
+ * @member {number}
+ */
 Rsvg.prototype.width = 0;
+
+/**
+ * Image height. Always integer.
+ * @readonly
+ * @member {number}
+ */
 Rsvg.prototype.height = 0;
 
+/**
+ * @see [Node.JS API]{@link http://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback_1}
+ * @private
+ */
 Rsvg.prototype._write = function(data, encoding, callback) {
@@ -112,2 +162,6 @@ try {
 
+/**
+ * Get the DPI for the outgoing pixbuf.
+ * @returns {{x: number, y: number}}
+ */
 Rsvg.prototype.getDPI = function() {
@@ -117,2 +171,11 @@ return this.handle.getDPI();
 
+/**
+ * Set the DPI for the outgoing pixbuf. Common values are 75, 90, and 300 DPI.
+ * Passing null to x or y will reset the DPI to whatever the default value
+ * happens to be (usually 90). You can set both x and y by specifying only the
+ * first argument.
+ *
+ * @param {number} x - Horizontal resolution.
+ * @param {number} [y] - Vertical resolution. Set to the same as X if left out.
+ */
 Rsvg.prototype.setDPI = function(x, y) {
@@ -122,2 +185,9 @@ this.handle.setDPI(x, y);
 
+/**
+ * Get the SVG's size or the size/position of a subelement if id is given. The
+ * id must begin with "#".
+ *
+ * @param {string} [id] - Subelement to determine the size and position of.
+ * @returns {{width: number, height: number, x: number, y: number}}
+ */
 Rsvg.prototype.dimensions = function(id) {
@@ -127,2 +197,8 @@ return this.handle.dimensions(id);
 
+/**
+ * Checks whether the subelement with given id exists in the SVG document.
+ *
+ * @param {string} id - Subelement to check existence of.
+ * @returns {boolean}
+ */
 Rsvg.prototype.hasElement = function(id) {
@@ -132,2 +208,20 @@ return this.handle.hasElement(id);
 
+/**
+ * Base render method. Valid high-level formats are: PNG, PDF, SVG, RAW. You
+ * can also specify the pixel structure of raw images: ARGB32 (default), RGB24,
+ * A8, A1, RGB16_565, and RGB30 (only enabled for Cairo >= 1.12). You can read
+ * more about the low-level pixel formats in the [Cairo Documentation]{@link
+ * http://cairographics.org/manual/cairo-Image-Surfaces.html#cairo-format-t}.
+ *
+ * If the id is given, only that subelement is rendered.
+ *
+ * The PNG format is the slowest of them all, since it takes time to encode the
+ * image as a PNG buffer.
+ *
+ * @param {number} width - Output image width, should be an integer.
+ * @param {number} height - Output image height, should be an integer.
+ * @param {string} [format] - One of the formats listed above.
+ * @param {string} [id] - Subelement to render.
+ * @returns {{data: Buffer, format: string, width: number, height: number}}
+ */
 Rsvg.prototype.render = function(width, height, format, id) {
@@ -137,2 +231,16 @@ return this.handle.render(width, height, format, id);
 
+/**
+ * Render the SVG as a raw memory buffer image. This can be used to create an
+ * image that is imported into other image libraries. This render method is
+ * usually very fast.
+ *
+ * The pixel format is ARGB and each pixel is 4 bytes, ie. the buffer size is
+ * width*height*4. There are no memory "spaces" between rows in the image, like
+ * there can be when calling the base render method with pixel formats like A8.
+ *
+ * @param {number} width - Output image width, should be an integer.
+ * @param {number} height - Output image height, should be an integer.
+ * @param {string} [id] - Subelement to render.
+ * @returns {{data: Buffer, format: string, pixelFormat: string, width: number, height: number}}
+ */
 Rsvg.prototype.renderRaw = function(width, height, id) {
@@ -142,2 +250,10 @@ return this.render(width, height, 'RAW', id);
 
+/**
+ * Render the SVG as a PNG image.
+ *
+ * @param {number} width - Output image width, should be an integer.
+ * @param {number} height - Output image height, should be an integer.
+ * @param {string} [id] - Subelement to render.
+ * @returns {{data: Buffer, format: string, width: number, height: number}}
+ */
 Rsvg.prototype.renderPNG = function(width, height, id) {
@@ -147,2 +263,10 @@ return this.render(width, height, 'PNG', id);
 
+/**
+ * Render the SVG as a PDF document.
+ *
+ * @param {number} width - Output document width, should be an integer.
+ * @param {number} height - Output document height, should be an integer.
+ * @param {string} [id] - Subelement to render.
+ * @returns {{data: Buffer, format: string, width: number, height: number}}
+ */
 Rsvg.prototype.renderPDF = function(width, height, id) {
@@ -152,2 +276,13 @@ return this.render(width, height, 'PDF', id);
 
+/**
+ * Render the SVG as an SVG. This seems superfluous, but it can be used to
+ * normalize the input SVG. However you can not be sure that the resulting SVG
+ * file is smaller than the input. It's not a SVG compression engine. You can
+ * be sure that the output SVG follows a more stringent structure.
+ *
+ * @param {number} width - Output document width, should be an integer.
+ * @param {number} height - Output document height, should be an integer.
+ * @param {string} [id] - Subelement to render.
+ * @returns {{data: string, format: string, width: number, height: number}}
+ */
 Rsvg.prototype.renderSVG = function(width, height, id) {
@@ -157,6 +292,6 @@ return this.render(width, height, 'SVG', id);
 
-Rsvg.prototype.renderVIPS = function(width, height, id) {
-	return this.render(width, height, 'VIPS', id);
-};
-
+/**
+ * String representation of this SVG render object.
+ * @returns {string}
+ */
 Rsvg.prototype.toString = function() {
@@ -179,2 +314,3 @@ var obj = {};
 
+// Export the Rsvg object.
 exports.Rsvg = Rsvg;

package.json

 {
 	"name": "rsvg",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"description": "Parse SVG files and render them as PNG, PDF, SVG, or raw memory buffer images.",
@@ -5,0 +5,0 @@ "repository": {

readme.md

@@ -12,2 +12,25 @@
 
+## Basic Usage
+
+Here is a simple example. Look in `index.js` for more documentation.
+
+```javascript
+var Rsvg = require('rsvg').Rsvg;
+var fs = require('fs');
+
+// Create SVG render instance.
+var svg = new Rsvg();
+
+// When finishing reading SVG, render and save as PNG image.
+svg.on('finish', function() {
+  console.log('SVG width: ' + svg.width);
+  console.log('SVG height: ' + svg.height);
+  fs.writeFile('tiger.png', svg.renderPNG(600, 400).data);
+});
+
+// Stream SVG file into render instance.
+fs.createReadStream('tiger.svg').pipe(svg);
+```
+
+
 ## Installation
@@ -14,0 +37,0 @@

No alert changes

Improved metrics

Total package byte prevSize

32371

increased by20.74%

Lines of code

262

increased by101.54%

Number of lines in readme file

69

increased by50%

No dependency changes