UPDATE: see end of post for another idea…

One of the ways they make you buy Unity Pro is gimping the non-Pro version by taking away Stencil Buffer and Render-to-Texture (needed for … many (most?) of the truly interesting effect you can think of). Except … it’s only needed by old-school OpenGL programmers, because everything RtT does can be mimicked in Shaders. Stencils … maybe also?

Anyway, I’m working on a hobby project and don’t need or want the Pro version for now (I’d like to support Unity, but these days the jump in price is way too expensive, at $X000 (they price-gouge you if you’re purchasing from within EU) for a simple hobby project). If/when we’re using it at work, and I have lots of cash, sure – but for now: can’t find that much money.

For the most part, I’m happy to go without RtT for now – generally speaking, hobby projects don’t “need” those kind of effects (and if they do: maybe it’s not a hobby any more?). There’s just one exception: reflections.
Continue reading →

This is very easy, but lots of people find this difficult with good reason!

Here’s a quick guide to how image-scaling is implemented with SVGKit, so you can effortlessly scale your images.

Continue reading →

In app development, the most common thing people do with an SVG is “render it to fit a specific area on screen”. This is very wise – it’s making use of the core feature of Scalable Vector Graphics: resolution independence.

Unfortunately, achieving that aim is a lot less obvious than you would expect. Most of the SVG Spec is extremely well written, but for this aspect the authors “had a bad day”, and wrote some rubbish prose that’s not technically possible. This leads to a lot of confusion…

I’m trying to make SVGKit for iOS/Mac be 100% standards compliant, and the lack of specification in this area has made it very difficult. Worse … people using the library are often confused by simple items like “how do I make the SVG file fit into a small area on screen?”.

It’s been difficult to work through, and I’ve decided to document what I *think* the authors intended – and how I’m implementing it in our open-source library.

Continue reading →

SVG is an awesome image format thats widely used, works in all browsers. SVG graphics make better apps and better games – and automatically “upgrade” themselves for future devices.

This post gives some simple 1-line / few lines of code recipes for using some of the main features of SVGKit – SVG implementation for iOS/OS X.

NOTE: this post refers to the new version of SVGKit, currently found at https://github.com/SVGKit/SVGKit/tree/2013base. The main version will soon be upgraded with this version – but for now, you should the 2013base link in this paragraph

Basic usage / installation

Install instructions are on the main GitHub page.

Basic usage / first-time usage info is on SVGKit 2013 – Usage.

Recipes

Load an SVG file like loading a PNG file

SVGKImage* newImage = [SVGKImage imageNamed:@"imagename"];

Display an SVG file on-screen using an ImageView

[self.view addSubView: [[SVGKFastImageView alloc] initWithImage:newImage];

…or an ImageView that supports CoreAnimation for every element

NB: the “Fast” imageview above saves everything as a single layer. Good for rendering, but bad for interaction. The “Layered” imageview here allows you to tap on any layer, rotate/animate/fade/drop-shadow/glow any element, etc.

[self.view addSubView:  [[SVGKLayeredImageView alloc] initWithImage:newImage];

Use a URL to load an SVG (open an SVG file *directly* from the web)

// Splitting URL to multiple lines to make blogpost
//    easier to read...
NSString* longURL = [NSString stringWithFormat:@"%@%@%@",
@"http://upload.wikimedia.org/",
@"wikipedia/commons/f/fd/",
@"Ghostscript_Tiger.svg";
NSURL* url = [NSURL urlWithString:longURL];
SVGKImage* newImage = [SVGKImage imageWithContentsOfURL:url];

Open an SVG from a custom source (maybe an in-memory SVG creation method)

First, create a class that conforms to SVGKSourceReader, i.e.:

@interface MyNewClass : NSObject <SVGKSourceReader>
...

…then subclass SVGKSource, and over-ride the method:

-(NSObject<SVGKSourceReader>*) newReader:(NSError**) error

Finally, use your customized SVGKSource to load your SVG:

SVGKSource* myCustomSource = [[[MyCustomClass alloc] init] newReader:nil];

/** Other examples, using the default SVGKSource class:
SVGKSource* urlSource = [SVGKSource sourceFromURL: [NSURL ...];
SVGKSource* fileSource = [SVGKSource sourceFromFilename: @"monkey.svg"];
*/

SVGKImage* newImage = [SVGKImage imageWithSource:myCustomSource];

Search an SVG file for particular tags / nodes / elements

SVG is an XML file, containing XML tags/nodes such as: “<svg>”, “<g>”, “<path>”, “<linearGradient>”, etc.

NSString* tagToFind = @"linearGradient";
NodeList* result = [svgImage.DOMDocument getElementsByTagName:tagToFind];

for( Element* domElement in result )
{
   // You can use the Element object directly:
   domElement.tagName;
   ...

   // ...or, if it was parsed by the SVG parser, you can convert it to an SVGElement:
   SVGElement* svgElement = (SVGElement*) domElement; 
   ...
}

Search for sub-tags / sub-nodes of a particular tag/node

If you already have an SVGElement reference, you can search all its descendants:

// To search the entire document, use:

// SVGElement* startPoint = newImage.DOMTree;
SVGElement* startPoint = ... // from your code

NSString* tagToFind = @"linearGradient";
NodeList* result = [startPoint getElementsByTagName:tagToFind];

for( Element* domElement in result )
{
   SVGElement* svgElement = (SVGElement*) domElement; // if your tags are all supported by SVGKit, they will be converted to SVGElement instances
   ...
}

Get a list of ALL descendant tags (from a particular node down)

SVGElement* startPoint = ... // e.g. for whole SVG doc, use: newImage.DOMDocument;
NodeList* allElements = [startPoint getElementsByTagName:@"*"];

Render one small part of the SVG file on its own

E.g. if you want to display a subset of the SVG, or want to export a single element:

NSString* idInSVGFile = ... // assuming your SVG file has an "id" attribute for this node
CALayer* absoluteLayer = [newImage.newCopyPositionedAbsoluteLayerWithIdentifier:isInSVGFile];

...

// NB: "absoluteLayer" is now positioned in absolute space;
//   if you add it to your window using e.g.:
[self.view.layer addSublayer: absoluteLayer];
// ...it will appear in the same place as it appeared before,
//   keeping all the offsets, rotations, etc

Customise the parsing, using your own parser extensions

Create your custom class that adheres to SVGKParserExtension:

@interface MyCustomSVGParserExtension : NSObject <SVGKParserExtension>
...

Then create a parser, INCLUDE THE DEFAULT extensions, and add your one on the end:

MyCustomSVGParserExtension* myCustomExtension = [[MyCustomSVGParserExtension alloc] init];

SVGKParser* parser = [[SVGKParser alloc] init];
[parser addDefaultSVGParserExtensions]; // HIGHLY RECOMMENDED
[parser addParserExtension:myCustomExtension];

SVGKParseResult* result = [parser parseSynchronously];

SVGKImage* newImage = [[SVGKImage alloc] initWithParsedSVG:result];

Get help on why parsing failed (and warnings and line numbers!)

SVGKImage* newImage = ... // use methods above

// EITHER: parse using default parser:
SVGKParseResult* parseResult1 = newImage.parseErrorsAndWarnings; // this is a convenience pointer to (SVGKParser*).currentParseRun

// OR: use a custom parser:
SVGKParser* parser = ... // use methods above
SVGKParseResult* parseResult2 = parser.currentParseRun;

And then you have the following info:

/*  array of NSError objects, each one a "WARNING" from the parser */
parseResult.warnings;

/* array of NSError objects, each one a "FATAL ERROR" from the parser - if your SVG didn't render at all, this is why! */
parseResult.errorsFatal;

/* array of NSError objects, each one a "RECOVERABLE ERROR" from the parser - if your SVG didn't render correctly, this is why! (although you probably still got to see something) */
parseResult.errorsRecoverable;

SVG is an awesome image format thats widely used, works in all browsers. SVG graphics make better apps and better games – and automatically “upgrade” themselves for future devices.

This post explains how you can use SVGKit – the open-source SVG implementation for iOS/OS X in your own apps

NOTE: this post refers to the new version of SVGKit, currently found at https://github.com/SVGKit/SVGKit/tree/2013base. The main version will soon be upgraded with this version – but for now, you should the 2013base link in this paragraph

(NB: basic installation is covered on the GitHub page – this is about how you *use* it)

SVGKit is like Apple’s UIKit

Originally, SVGKit was a bit tricky to use. I re-architected it to be an exact clone of Apple’s UIKit – same classes, same class structure, same method names.

So, we have:

(a side note: We couldn’t use a classname prefix of “SVG” because the SVG spec reserves all classnames beginning “SVG”. Apple had a similar problem when they invented GLKit – the prefix “GL” was already used in the OpenGL library they were extending, so they named their classes “GLK” prefix. Hence … “SVGK”)

Loading an image

You already know how to load a UIImage, the “easy way”:

UIImage* newImage = [UIImage imageNamed:@"myImage.png"];

Well, SVGKit is … the same:

SVGKImage* newImage = [SVGKImage imageNamed:@"myImage.svg"];

Displaying an image: UIImageView

And how do you create a UIImageView?

UIImageView* imageView = [[UIImageView alloc] initWithImage:newImage];

…so, for SVGKit:

SVGKImageView* imageView = [[SVGKFastImageView alloc] initWithImage:newImage];
// ..... or: 
SVGKImageView* imageView = [[SVGKLayeredImageView alloc] initWithImage:newImage];

Wait – why is this different?

The reference in both cases is an SVGKImageView – but you cannot alloc-init that class directly. Why?

Different people use the library in different ways. Some people need performance, others need detailed aniamtion. SVG’s contain a lot of bonus info, and it’s not possible to support every use case with a single class. So, you get to choose which one fits your needs

Advanced uses

So far, so easy. What about when you want more control? And how do you load an SVG over the internet (can you load an SVG directly from the web?)

Time to delve a little deeper…

Loading an SVG: in detail

There are four steps to loading an SVG (all of which are done automatically by SVGKImage above):

1. SVGKSource: specify a location (a file, a filename – or an HTTP URL)
2. SVGKParser: parse the file (all SVG’s are XML files, so your file can contain any custom XML you want)
3. SVG classes: convert to SVG’s custom classes (from the SVG Spec); includes automatic support for CSS styling, cascades, etc
4. SVGKImage: export the SVG to something Apple can render: e.g. a flat CALayer, or a hierarchy of CALayers, etc

Ultimately, I want to add a fifth (optional) stage, where you can “export” the SVG back to a new file. This should be very easy using the SVG classes (they are DOM compliant already).

Every stage is extensible, so you can either add features, or custommize it

Extend SVGKSource: adding new sources

Easy: create a new subclass of SVGKSource, and implement the two methods.

The method signatures are a little strange, because they have to support fast file-access (a C native library from Apple) as well as modern Objective-C methods.

One example of each: the supplied SVGKSource for loading from disk uses C methods, and the supplied one for loading from a URL uses Objective-C methods.

Extend SVGKParser: custom SVG files and formats

NOTE: do NOT subclass SVGKParser; parsing is very complex, and there’s a special mechanism that makes it easy to extend the parser (read on…)

Parsing is complex, so our parser is modular (based on ideas from a modular XML parser I wrote years ago). The SVGKParser class doesn’t parse SVG direclty: instead, it parses raw XML, and converts it to a higher-level version that’s much faster to work with. It also manages error handling, loading bytes from an SVGKSource, etc.

You create a new parser instance with a helper method that includes all the modules you need by default:

SVGKParser* parser = [SVGKParser parserWithDefaultParseExtensions];

SVGKParserExtension: adding your own custom parsing

Our SVG implementation is already split into sub-modules. This makes the code easier to maintain – and it makes it much easier to add support for SVG features one-by-one, in parallel with other developers.

Example classes:

• SVGKParserSVG: parses “Basic” SVG – obvious things that require no special handling. NB: this is the most complex parser extension we have. Most are much simpler
• SVGKParserGradients: parses SVG Gradients – because these were added later by a different developer (Stich) … likewise, if you’re adding a msising SVG feature, feel free to make a new parser-extension for it, it’s easier!
• SVGKParserDefsAndUse: the SVG <defs> and <use> tags are much harder to parse than 99% of SVG, since they require complex cross-referencing and instancing. So, we use a separate parser extension to isolate this code.

For one of my games, I wanted to store gameplay data inside the SVG – attach info to particular SVG tags (e.g. give each SVG path a “bonusPoints” attribute).

To do this in a spec-compliant way, you should:

1. Create a new XML namespace (requires no code: you simply invent a URL on a domain that you own)
2. Put the namespace in your SVG file, using an <xmlns> tag, and give it a “prefix”, e.g. “my-game”
3. Everywhere you want your custom attributes, or custom tags, prefix them, e.g.: “
4. Write an SVGKParserExtension, and in the “supportedTags” and “supportedNamespaces” methods, return ONLY your namespace, and either nil, or the set of tags you’ve invented

Once the file is parsed, use the DOM to fetch your data (by definition, SVG parsers are required to be DOM-compliant parsers too)

e.g.:

NodeList* myCustomNodes = [svgImage.DOMDocument getElementsByTagNameNS:@"http://my.custom.namespace" localName:@"my-custom-tag"];

(NB: NodeList is defined by the DOM, and is just a wrapper for an NSArray. If you #import “NodeList+Mutable.h”, you can access the NSArray directly, and use ObjectiveC fast enumeration. This is cheating, it’s not in the core SVG spec, which is why it’s hidden inside a separate header file)

Extend SVG Classes: the core SVG Spec

Don’t.

(the only valid reason for doing this is if you find features in the spec that are missing or broken in SVGKit. All other usages, you should be able to do in some other way, more easily, with less risk of your changes being broken when we upgrade SVGKit)

Extend SVGKImage export: export your SVG into custom rendering or to a new file on disk

NB: this is subject to change; we will probably invent an interface for exporting at some point. For now, use SVGKImage directly.

All the parsed data for the SVGKImage is available to you directly, for exporting:

• (SVGKImage* image).DOMTree : this property contains the entire parsed SVG-DOM (all the SVG* classes)
• (SVGKImage* image).CALayerTree : this property contains the SVG converted into Apple’s CALayer classes, renderable directly in OS X and iOS

To save memory and CPU, the “CALayerTree” property isn’t created until you request it; if you don’t want the CALayer’s, they’ll never get created.

Improving SVGKit, fixing bugs, and ultra-advanced development

But SVGKit isn’t perfect: there are still missing features, bugs, etc.\

If you find a bug but can’t understand / fix it, please create a simple-as-possible SVG file and send it to us (create an Issue on the GitHub page, and include a link to the file). If you give us permission, we’ll add it to the suite of “test” images we use to verify each version of SVGKit, and that way it will always work, even with future versions.

If you fix bugs, or have bits you want to fix, please have a look at the SVGKit Development guide.

If you want support or help with SVGKit, the very best thing to do is create an Issue on the SVGKit page. That way, any of the contributors can see your problem and help you out. If you email me directly for help, you’re less likely to get a response (I’m busy, and I work on SVGKit entirely unpaid).