diff --git a/README.md b/README.md index 49a3073..1fb6004 100644 --- a/README.md +++ b/README.md @@ -469,7 +469,7 @@ Squib supports various configuration properties that can be specified in an exte * `warn_ellipsize` (default: true). Warn when text is ellipsized * `warn_png_scale` (default: true). Warn when a PNG file is upscaled -For debugging/sanity purposes, if you want to make sure your configuration options are parsed correclty, the above options are also available as methods within Squib::Deck, for example: +For debugging/sanity purposes, if you want to make sure your configuration options are parsed correctly, the above options are also available as methods within Squib::Deck, for example: ```ruby Squib::Deck.new do diff --git a/docs/backends.rst b/docs/backends.rst new file mode 100644 index 0000000..2909b5a --- /dev/null +++ b/docs/backends.rst @@ -0,0 +1,20 @@ +Backends: Vector vs. Raster +=========================== + +Squib's graphics rendering engine, Cairo, has the ability to support a variety of surfaces to draw on, including both raster images stored in memory and vectors stored in SVG files. Thus, Squib supports the ability to handle both. They are options in the configuration file ``backend: memory`` or ``backend: svg`` described in :doc:`/config`. + +If you use :doc:`/dsl/save_pdf` then this backend option will determine how your cards are saved too. For `memory`, the PDF will be filled with compressed raster images and be a larger file (yet it will still print at high quality... see discussion below). For SVG backends, PDFs will be smaller. If you have your deck backed by SVG, then the cards are auto-saved, so there is no ``save_svg`` in Squib. (Technically, the operations are stored and then flushed to the SVG file at the very end.) + +There are trade-offs to consider here. + +* Print quality is **usually higher** for raster images. This seems counterintuitive at first, but consider where Squib sits in your workflow. It's the final assembly line for your cards before they get printed. Cairo puts *a ton* of work into rendering each pixel perfectly when it works with raster images. Printers, on the other hand, don't think in vectors and will render your paths in their own memory with their own embedded libraries without putting a lot of work into antialiasing and various other graphical esoterica. You may notice that print-on-demand companies such as The Game Crafter `only accept raster file types `_, because they don't want their customers complaining about their printers not rendering vectors with enough care. +* Print quality is **sometimes higher** for vector images, particularly in laser printers. We have noticed this on a few printers, so it's worth testing out. +* PDFs are **smaller** for SVG back ends. If file size is a limitation for you, and it can be for some printers or internet forums, then an SVG back end for vectorized PDFs is the way to go. +* Squib is **greedy** with memory. While I've tested Squib with big decks on older computers, the `memory` backend is quite greedy with RAM. If memory is at a premium for you, switching to SVG might help. +* Squib does **not support every feature** with SVG back ends. There are some nasty corner cases here. If it doesn't, please file an issue so we can look into it. Not every feature in Cairo perfectly translates to SVG. + +.. note:: + + You can still load PNGs into an SVG-backed deck and load SVGs into a memory-backed deck. To me, the sweet spot is to keep all of my icons, text, and other stuff in vector form for infinite scaling and then render them all to pixels with Squib. + +Fortunately, switching backends in Squib is as trivial as changing the setting in the config file (see :doc:`/config`). So go ahead and experiment with both and see what works for you. diff --git a/docs/colors.rst b/docs/colors.rst index 93900a8..8af4cf8 100644 --- a/docs/colors.rst +++ b/docs/colors.rst @@ -1,28 +1,64 @@ Specifying Colors & Gradients ============================= -Colors can be specified in a wide variety of ways, mostly in a hex-string. Take a look at the examples from `samples/colors.rb`, found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb) +Colors +------ -{include:file:samples/colors.rb} +by hex-string +^^^^^^^^^^^^^ -Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accept a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). The above sample will generate a table of such constants. +You can specify a color via the standard hexadecimal string for RGB (as in HTML and CSS). You also have a few other options as well. You can use: -Additionally, in most places where colors are allowed, you may also supply a string that defines a gradient. Squib supports two flavors of gradients: linear and radial. Gradients are specified by supplying some xy coordinates, which are relative to the card (not the command). Each stop must be between 0.0 and 1.0, and you can supply as many as you like. Colors can be specified as above (in any of the hex notations or built-in constant). If you add two (or more) colors at the same stop, then the gradient keeps the colors in the in order specified and treats it like sharp transition. + * 12-bit (3 hex numbers), RGB. e.g. ``'#f08'`` + * 24-bit (6 hex numbers), RRGGBB. e.g. ``'#ff0088'`` + * 48-bit (9 hex numbers), RRRGGGBBB. e.g. ``'#fff000888'`` -The format for gradient strings look like this: -Linear: -``` -(x1,y1)(x2,y2) color1@stop1 color2@stop2 -``` +Additionally, you can specify the alpha (i.e. transparency) of the color as RGBA. An alpha of ``0`` is full transparent, and ``f`` is fully opaque. Thus, you can also use: + + * 12-bit (4 hex numbers), RGBA. e.g. ``'#f085'`` + * 24-bit (8 hex numbers), RRGGBBAA. e.g. ``'#ff008855'`` + * 48-bit (12 hex numbers), RRRGGGBBBAAA. e.g. ``'#fff000888555'`` + +The ``#`` at the beginning is optional, but encouraged for readability. In layout files (described in :doc:`/layouts`), the ``#`` character will initiate a comment in Yaml. So to specify a color in a layout file, just quote it:: + + # this is a comment in yaml + attack: + fill_color: '#fff' + + +by name +^^^^^^^ + +Under the hood, Squib uses the rcairo `color parser `_ to accept around 300 named colors. The full list can be found `here `_. + +Names of colors can be either strings or symbols, and case does not matter. Multiple words are separated by underscores. For example, ``'white'``, ``:burnt_orange``, or ``'ALIZARIN_CRIMSON'`` are all acceptable names. + +by custom name +^^^^^^^^^^^^^^ + +In your ``config.yml``, as described in :doc:`/config`, you can specify custom names of colors. For example, ``'foreground'``. + +Gradients +-------- + +In most places where colors are allowed, you may also supply a string that defines a gradient. Squib supports two flavors of gradients: linear and radial. Gradients are specified by supplying some xy coordinates, which are relative to the card (not the command). Each stop must be between ``0.0`` and ``1.0``, and you can supply as many as you like. Colors can be specified as above (in any of the hex notations or built-in constant). If you add two or more colors at the same stop, then the gradient keeps the colors in the in order specified and treats it like sharp transition. + +The format for linear gradient strings look like this:: + + '(x1,y1)(x2,y2) color1@stop1 color2@stop2' + The xy coordinates define the angle of the gradient. -Radial: -``` -(x1,y1,radius1)(x2,y2,radius2) color1@stop1 color2@stop2 -``` +The format for radial gradients look like this:: + + '(x1,y1,radius1)(x2,y2,radius2) color1@stop1 color2@stop2' + The coordinates specify an inner circle first, then an outer circle. -Check out the following sample from `samples/gradients.rb`, found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb) +In both of these formats, whitespace is ignored between tokens so as to make complex gradients more readable. + +If you need something more powerful than these two types of gradients (e.g. mesh gradients), then we suggest encapsulating your logic within an SVG and using the :doc:`/dsl/svg` method to render it. -{include:file:samples/gradients.rb} +Examples +-------- diff --git a/docs/config.rst b/docs/config.rst index 5185bb8..076a15b 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,2 +1,65 @@ -Options for config.yml -====================== +Configuration Options +===================== + +Squib supports various configuration properties that can be specified in an external file. By default, Squib looks for a file called ``config.yml`` in the current directory. Or, you can set the ``config:`` option in ``Deck.new`` to specify the name of the configuration file. + +These properties are intended to be immutable for the life of the Deck, and intended to configure how Squib behaves. + +The options include: + +progress_bars + default: ``false`` + + When set to ``true``, long-running operations will show a progress bar in the console + +hint + default: ``:off`` + + Text hints are used to show the boundaries of text boxes. Can be enabled/disabled for individual commands, or set globally with the `hint` method. This setting is overridden by `hint` (and subsequently individual :doc:`/dsl/text`). + +custom_colors + default: ``{}`` + + Defines globally-available named colors available to the deck. Must be specified as a hash in yaml. For example:: + + # config.yml + custom_colors: + fg: '#abc' + bg: '#def' + + +antialias + default: ``'best'`` + + Set the algorithm that Cairo will use for anti-aliasing throughout its rendering. Available options are ``fast``, ``good``, ``best``, ``none``, ``gray``, ``subpixel``. + + Not every option is available on every platform. Using our benchmarks on large decks, `best` is only ~10% slower anyway. For more info see the `Cairo docs `_. + +backend + default: ``'memory'`` + + Defines how Cairo will store the operations. Can be ``svg`` or ``memory``. See :doc:`/backends`. + +prefix + default: ``'card_'`` + + When using an SVG backend, cards are auto-saved with this prefix and ``'%02d'`` numbering format. + +warn_ellipsize + default: true + + Show a warning on the console when text is ellipsized. Warning is issued per card. + +warn_png_scale + default: true + + Show a warning on the console when a PNG file is upscaled. Warning is issued per card. + +Options are available as methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For debugging/sanity purposes, if you want to make sure your configuration options are parsed correctly, the above options are also available as methods within ``Squib::Deck``, for example:: + + Squib::Deck.new do + puts backend # prints 'memory' by default + end diff --git a/docs/data.rst b/docs/data.rst new file mode 100644 index 0000000..901458c --- /dev/null +++ b/docs/data.rst @@ -0,0 +1,22 @@ +Be Data-Driven with XLSX and CSV +================================ + +Squib supports importing data from ExcelX (.xlsx) files and Comma-Separated Values (.csv) files. Because :doc:`/arrays`, these methods are column-based, which means that they assume you have a header row in your table, and that header row will define the name of the column. + +Hash of Arrays +-------------- + +In both DSL methods, Squib will return a ``Hash`` of ``Arrays`` correspoding to each row. Thus, be sure to structure your data like this: + + * First row should be a header - preferably with concise naming since you'll reference it in Ruby code + * Rows should represent cards in the deck + * Columns represent data about cards (e.g. "Type", "Cost", or "Name") + +Of course, you can always import your game data other ways using just Ruby (e.g. from a REST API, a JSON file, or your own custom format). There's nothing special about Squib's methods in how they relate to ``Squib::Deck`` other than their convenience. + +See :doc:`/dsl/xlsx` and :doc:`/dsl/csv` for more details and examples. + +Quantity Explosion +------------------ + +If you want more than one copy of a card, then have a column in your data file called ``Qty`` and fill it with counts for each card. Squib's :doc:`/dsl/xlsx` and :doc:`/dsl/xlsx` methods will automatically expand those rows according to those counts. You can also customize that "Qty" to anything you like by setting the `explode` option (e.g. ``explode: 'Quantity'``). Again, see the specific methods for examples. diff --git a/docs/dsl/png.rst b/docs/dsl/png.rst index b804bdf..8cbc1c4 100644 --- a/docs/dsl/png.rst +++ b/docs/dsl/png.rst @@ -8,7 +8,7 @@ Options .. include:: /args/expansion.rst file - default: ``''`` + default: ``''`` (empty string) file(s) to read in. As in :doc:`/arrays`, if this a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done for that card. diff --git a/docs/dsl/save.rst b/docs/dsl/save.rst index 4e3ad5a..be16062 100644 --- a/docs/dsl/save.rst +++ b/docs/dsl/save.rst @@ -1,2 +1,23 @@ save ----- +==== + +Saves the given range of cards to either PNG or PDF. Wrapper method for other save methods. + +Options +------- + +This method delegates everything to :doc:`save_png` or :doc:`save_pdf` using the ``format`` option. All other options are passed along. + +format + default: ``[]`` (do nothing) + + Use ``:png`` to save as a PNG, and ``:pdf`` to save as PDF. To save to both at once, use ``[:png, :pdf]`` + +Examples +-------- + +:: + + save format: :png, prefix: 'front_' # same as: save_png prefix: 'front_' + save format: :pdf, prefix: 'cards_' # same as: save_pdf prefix: 'cards_' + save format: [:png, :pdf] # same as: save_png; save_pdf diff --git a/docs/index.rst b/docs/index.rst index 63334b8..d9276ba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,10 +12,12 @@ Contents: parameters arrays layouts + data units colors config - get_help + backends + help dsl/index.rst Indices and tables