Table of Contents

• The Basics of SpiralKit
  • What Is SpiralKit
  • Where to Find It
  • License
  • Prerequisites and Supported Versions
    • Prerequisites
    • Supported Versions
  • IDE
  • Building and Packaging
    • Building the Framework
      • Building for Development Environments
      • Building for Internal Test Environments
      • Building for Public Release
    • Packaging the Framework
      • Packaging as a Universal Binary
      • Packaging as an iOS-Only Binary
  • Including SpiralKit in an Application
  • The Reference Implementation
• The Technical Details of SpiralKit
  • Fundamentals of the Framework Implementation
    • Host View
      • Anatomy of a Host View
    • Draw Engines
      • Anatomy of a Draw Engine
    • Styling Providers
      • Anatomy of a Styling Provider
        • Color Space and Blend Mode
        • Draw Tool Type
    • Effects Engines
      • Anatomy of an Effects Engine
    • Data Providers
      • Anatomy of a Data Provider
      • Provided Extensions of the DGSKDrawDataProviderProtocol Protocol
  • The DGSKDataProviderProtocol Protocol
• Additional Components Included in SpiralKit
  • Factories
    • DGSKDrawEngineFactory
    • DGSKDrawContextStylingProviderFactory
  • Utility Classes
  • The Unloadable Instance Protocol
  • The DGSKLog Macro
• Included Fundamental Component Implementations
  • Included Draw Engines
    • Stroke-Based Engines
    • Cache-Based Engines
    • Composite Engines
  • Included Styling Providers
  • Included Effects Engines
• Protocol Specifications
  • Host View
    • DGSKDrawViewProtocol
  • Draw Engines
    • DGSKDrawEngineProtocol
  • Styling Providers
    • DGSKDrawContextStylingProviderProtocol
    • DGSKRGBDrawContextStylingProviderProtocol
  • Effects Engines
    • DGSKDrawEffectsEngineProtocol
  • Data Providers
    • DGSKDrawDataProviderProtocol
    • DGSKStrokeDrawDataProviderProtocol
    • DGSKCacheDrawDataProviderProtocol
    • DGSKDataProviderProtocol
    • DGSKStrokeDataProviderProtocol
  • Utilities
    • DGSKUnloadableInstanceProtocol

The Basics of SpiralKit

What Is SpiralKit

SpiralKit is a Quartz 2D-based drawing framework for iOS written in Objective-C. The framework enables ‘drawing’ on a UIView in iOS and ships with pen, highlighter, and eraser drawing effects.

The framework is built specifically to enable adding new effects, color spaces, and drawing algorithms in a modular fashion. If you want to provide a unique drawing effect, support of the CMYK color space, or a custom drawing algorithm, you can add such features to SpiralKit without having to modify the fundamental components of the framework.

Where to Find It

The project is hosted on GitHub at https://github.com/digital-generalists/spiralkit.

License

SpiralKit is released under the Apache License 2.0.

Our ‘layman’s terms’ understanding and expectations around the license are:

• You can use and modify SpiralKit for any law-abiding purpose, including commercial products, free of charge.
• You need to acknowledge that you’re using SpiralKit and who originally authored it, including leaving any attributions already in the code in place. Even if you don’t release your source, your product should include an acknowledgement of SpiralKit.
• You need to note if you changed anything in the source.
• You can’t blame us if anything goes wrong with your product.
• You can’t claim to be affiliated with Digital Generalists or the framework’s individual authors, or use our trademarks and copyrights without our written permission to do so. Acknowledging and promoting that you used SpiralKit is encouraged and good karma. Naming your product ‘SpiralKit by Digital Generalists’ or claiming it was ‘built by Digital Generalists’ is not okay.

The license is the binding agreement for use of the framework and takes precedence over our understanding should we have incorrectly interpreted the license in any way.

See the LICENSE.txt file for the formal license specification.

Prerequisites and Supported Versions

Prerequisites

SpiralKit is an iOS-specific framework. To build and use SpiralKit, you need to have Xcode installed.

The provided Xcode project files are generated from Xcode 6.3.1.

• Xcode | download

Xcode should be the only prerequisite for using SpiralKit. If you want to run SpiralKit on a device, well, you’ll need an iOS device.

Supported Versions

The code for SpiralKit is formally verified back to iOS 8.0. Realistically, the functional code should be portable back to iOS 5.1. However, Xcode tooling support for frameworks prior to 8.0 has some opportunities.

Feel free to attempt to take SpiralKit back all the way to iOS 5.1, but you may encounter compiler warnings, and you’ll have no guarantees about the appropriate fit for any of the provided build scripts or project files.

The best bet for pre-iOS 8 integration of the framework is direct incorporation of the SpiralKit source into your application binary. You’re milage may vary, so God-speed if you choose to make a framework build of SpiralKit for pre-iOS 8 OS releases. We’d love if you do, but the framework doesn’t come with a pre-packaged solution for releases prior to iOS 8.0.

IDE

SpiralKit was developed using Xcode 4.3.2 through 6.3.1. Project files for Xcode 6.3.1 are included with the distribution.

Building and Packaging

SpiralKit uses Xcode build profiles linked to shell scripts as its primary build system.

Building the Framework

Building for Development Environments

To build the framework for development:

• Open the SpiralKit project in Xcode
• Select the Development build profile
• Press Cmd+B

The Development build profile will create a debug build of the framework with a DEVBUILD build number. The DGSKLog macro will output logging statements via NSLog in these builds.

Building for Internal Test Environments

To build the framework for internal release (for QA or beta testing for example):

• Open the SpiralKit project in Xcode
• Select the Internal Release build profile
• Press Cmd+B

The Internal Release build profile will create a release build of the framework with an INT build number prefix. The DGSKLog macro will not output any logging statements in these builds.

Building for Public Release

To build the framework for public release:

• Open the SpiralKit project in Xcode
• Select the Public Release build profile
• Press Cmd+B

The Public Release build profile will create a release build of the framework without the INT build number prefix. The DGSKLog macro will not output any logging statements in these builds.

Packaging the Framework

Building the framework will create a working version of SpiralKit that can be used within the iOS simulator. However, finding and configuring an optimized version of the built framework for inclusion in an application requires some additional work. The packaging build profiles simplify and largely automate these tasks.

Packaging as a Universal Binary

The Create-[release profile]-Universal-Framework build profiles will create a version of the framework that will run on both iOS devices and the Xcode simulator.

To package the framework as a Universal binary:

• Open the SpiralKit project in Xcode
• Select the appropriate Development, Internal Release, or Public Release build profile
• Select the iOS Device build target
• Press Cmd+B
• Select any iOS simulator build target
• Press Cmd+B
• Select the appropriate Create-[release profile]-Universal-Framework build profile
• Press Cmd+B

Create-[release profile]-Universal-Framework build profiles are provided for Development, Internal Release, and Public Release release profiles. The Create-[release profile]-Universal-Framework build profiles require that both the Xcode simulator and iOS device builds are done prior to running a Create-[release profile]-Universal-Framework build profile.

The packaged framework will be created in the [SpiralKit project root]/build_ouput directory.

Packaging as an iOS-Only Binary

The Create-[release profile]-iOS-Only-Framework build profiles will create a version of the framework that will run only on iOS devices. This may be valuable for release versions of an application as the created binary is significantly smaller than the universal binary version.

To package the framework as an iOS-only binary:

• Open the SpiralKit project in Xcode
• Select the appropriate Development, Internal Release, or Public Release build profile
• Select the iOS Device build target
• Press Cmd+B
• Select the appropriate Create-[release profile]-iOS-Only-Framework build profile
• Press Cmd+B

Create-[release profile]-iOS-Only-Framework build profiles are provided for Development, Internal Release, and Public Release release profiles. The Create-[release profile]-iOS-Only-Framework build profiles require that the iOS device build is done prior to running a Create-[release profile]-iOS-Only-Framework build profile.

The packaged framework will be created in the [SpiralKit project root]/build_ouput directory.

Including SpiralKit in an Application

To include a built version of the SpiralKit framework in an application:

• Build and package a version of the framework as described here
• Create a new application via Xcode
• Open the new project in Xcode
• Select the project file and click “General” in the code editor window

• Find the “Embedded Binaries” section and click the “+” button

• Navigate to the directory containing the local copy of the SpiralKit framework that was just built and select SpiralKit.framework
• In any file that references an API, class, or protocol from the framework, add an import statement for the SpiralKit framework to the referencing source file. This is essentially the same operation you would perform for a pre-packaged iOS-framework such as UIKit.


#import "SpiralKit/SpiralKit.h"


• Create Data Provider classes to manage the drawing operations.

All provided cache-based drawing algorithms require a data provider class that complies with the DGSKCacheDrawDataProviderProtocol protocol.

All provided stroke-based drawing algorithms require a data provider class that complies with the DGSKStrokeDrawDataProviderProtocol protocol.

Both DGSKCacheDrawDataProviderProtocol and DGSKStrokeDrawDataProviderProtocol inherit from DGSKDrawDataProviderProtocol.

These protocols can be mixed within the same class, meaning that cache-based and stroke-based drawing algorithms can share the same data provider assuming the class implements both protocols.

• Wire SpiralKit into the application


/***/
@implementation ViewController

//@property (strong, nonatomic) UIView *drawView;
@synthesize drawView = _drawView;
//@property (strong, nonatomic) DrawData* drawData;
@synthesize drawData = _drawData;

– (void)viewDidLoad
{
[super viewDidLoad];

[self.view setBackgroundColor:[UIColor whiteColor]];

self.drawData = [[DrawData alloc] init];
// This can be substituted with any DGSKDrawViewProtool-compliant implementation of UIView.
self.drawView = [[DGSKDrawView alloc] initWithFrame:self.view.frame];

id stylingProvider = [DGSKDrawContextStylingProviderFactory createInstanceForDrawToolType:DGSKDrawToolTypeNormal];
stylingProvider.color = [UIColor blackColor];
stylingProvider.lineWidth = 2;
[stylingProvider.effectsEngine calibrateToStylingProvider:stylingProvider];

// Returns the draw engine instance if you need to track it.
[DGSKDrawEngineFactory createInstanceForDrawView:self.drawView withStylingProvider:stylingProvider data:self.drawData];

[self.view insertSubview:self.drawView atIndex:0];
}

/***/
@end

That’s it. After performing the above steps, you should be able to draw on the inserted drawView UIView instance within your application’s UI.

The Reference Implementation

The SpiralKit reference implementation provides a very simple implementation of including SpiralKit in an application and should be used to provide guidance on how to incorporate SpiralKit into an application.

The reference implementation links to a pre-compiled universal instance of the SpiralKit framework. This provided build of the framework linked to the reference implementation can be found at:

[reference implementation source directory]/framework-releases

The Technical Details of SpiralKit

Fundamentals of the Framework Implementation

The framework of SpiralKit is built on five fundamental components:

• The host view for capturing and displaying the draw data
• The drawing algorithm engine
• The drawing styling provider
• The drawing effects engine
• The data providers for the drawing data

Host View

The first thing that typically needs to happen in a drawing application is specifying where the data should be drawn. The second thing that typically needs to happen, although not always required depending on the application’s functionality, is capturing the draw input data from the user. The host view is always responsible for drawing the draw data. If the application enables real-time drawing of draw data, as opposed to simply rendering previously captured draw data, the host view is also responsible for capturing the draw data.

Anatomy of a Host View

A host view consists of a UIView instance that conforms to the DGSKDrawViewProtocol protocol. All views intended to display and capture SpiralKit draw data must implement the DGSKDrawViewProtocol protocol.

The DGSKDrawView class provides a general implementation of a host view. You should use this implementation for your application’s host view(s) unless you definitively need to modify the behavior of the host view, such as enabling a render-only mode for example.

The DGSKDrawView implementation of a host view provides standard handlers for the touch events associated with a drawing application. The DGSKDrawView implementation will track the touch events associated with the UIView in a fashion typically required by a drawing application.

Draw Engines

Draw engines specify how a line, more commonly referred to in SpiralKit as a stroke, is rendered on the screen. The drawing engine provides the mechanics for how a stroke is calculated and ultimately drawn to the screen, but not necessarily how the line should be decorated visually.

A drawing engine will govern the storage mechanism for the drawing and how often a stroke is redrawn. For example, cache-based drawing algorithms will typically output a point-in-time bitmap image of the drawing while the drawing is created. In contrast, stroke-based algorithms will typically re-calculate the active stroke based on received input, updating the visual representation of the stroke as stroke data is updated.

Anatomy of a Draw Engine

A draw engine consists of an implementing class that provides the implementation details of the drawing functionality and an interface specification describing the draw engine API.

The fundamental API expected of all draw engines is defined in the DGSKDrawEngineProtocol protocol. SpiralKit expects all draw engines to conform to this protocol, and any class that implements this protocol can potentially function as a draw engine within SpiralKit.

Styling Providers

Styling providers specify how a stroke is visually decorated. A styling provider provides the fundamental mechanics for how a stroke should visually appear.

A styling provider instance exists within the context of a draw engine as a property of the draw engine.

Properties such as color, size, blend mode, and color space are typically specified by the styling provider. Changing the fundamental color or size of a stroke is typically accomplished by changing properties of the styling provider.

Anatomy of a Styling Provider

A styling provider consists of an implementing class that provides the implementation details of the styling functionality and an interface specification describing the styling API.

Color Space and Blend Mode

The implementing class is responsible for defining visual rendering details such as the color space and blend mode the stroke should employ when drawing the stroke. The color space defines how colors are defined and referenced. Typical color spaces include RGB and CMYK color specifications. blend mode specifies how the color components are composited when drawn, which means how the specific color and alpha components are combined in relation to the complete image they are being drawn to.

Because blend mode affects how the stroke is drawn in relation to the complete drawing, drawing effects typically also modify the blend mode of a styling provider to enable a specific effect. In these situations, the styling provider is still responsible for providing a default blend mode.

Draw Tool Type

SpiralKit includes a mechanism for specifying a draw tool type identifier. The intent of the draw tool type identifier is to serve as a shorthand categorization of the type of draw tool the styling provider is intended to mimic, such as a pen, highlighter, or eraser.

The draw tool type can come in handy for providing defaults for specific style settings depending on what tool type is specified or enabling factory methods which create styling provider instances for a specific draw tool type. SpiralKit leverages this mechanism both for providing default values and for factory methods used to create instances of a styling provider tailored to a specific tool.

The base implementation of SpiralKit delivers the following draw tool types defined in the DGSKDrawToolType enum:

• DGSKDrawToolTypeNormal – the standard draw tool type, which is leveraged by the pen tool type
• DGSKDrawToolTypeHighlighter – the highlighter draw tool type
• DGSKDrawToolTypeEraser – the eraser draw tool type

The fundamental API expected of all styling providers is defined in the DGSKDrawContextStylingProviderProtocol protocol. SpiralKit expects all styling providers to conform to this protocol, and any class that implements this protocol can potentially function as a styling provider within SpiralKit.

Effects Engines

Effects engines specify special visual decoration that should be applied to a stroke when rendered on the screen. The effects engine provides the mechanics for modifying the visual representation of a stroke while the stroke is drawn, enabling real-time modification of the stroke’s visual representation.

An effects engine instance exists within the context of a styling provider as a property of the styling provider.

An effects engine can govern all aspects of a stroke’s visual style and can receive real-time input on the drawing of the stroke. This enables the effects engine to adjust visual output based on real-time input.

Anatomy of an Effects Engine

An effects engine consists of an implementing class that provides the implementation details of the effect functionality and an interface specification describing the effects engine API.

The implementation class of an effects engine is typically responsible for modifying the host styling provider’s properties to apply an effect based on real-time draw data. Alternately, effects engines can be used to encapsulate blend mode and color space settings for a styling provider that will differ only on those aspects across draw tools. SpiralKit leverages the later approach in implementing the highlighter and eraser draw tools, in that the specified color and size parameters should be preserved but the visual decoration of the stroke should change.

The fundamental API expected of all effects engines is defined in the DGSKDrawEffectsEngineProtocol protocol. SpiralKit expects all effects engines to conform to this protocol, and any class that implements this protocol can potentially function as an effects engine within SpiralKit.

Data Providers

Data providers serve as the data model for a draw engine. When a draw engine is instantiated, a data provider is specified and is responsible for storing and retrieving the data captured during drawing operations performed by that draw engine.

The type of data stored by a data provider will be governed largely by the algorithm of the draw engine. For example, a cache-based drawing algorithm will store a bitmap image of the full drawing as its primary data whereas a stroke-based drawing algorithm will store a collection of strokes (which are little more than a collection of related points) as its primary data.

Anatomy of a Data Provider

A data provider consists of an implementing class that provides the implementation details of the data storage functionality and an interface specification, typically represented by a collection of protocols, describing the storage mechanism API.

The fundamental API expected of all data providers is defined in the DGSKDrawDataProviderProtocol protocol. SpiralKit expects all data providers to conform to this protocol and any class that implements this protocol can potentially function as a data provider for a draw engine within SpiralKit. Concrete implementations of a data provider commonly will specify a more specific API definition for a particular storage scheme in an additional protocol that extends from DGSKDrawDataProviderProtocol.

This additional level of abstraction enables composition of multiple storage mechanisms within a single data provider definition. For example, a data provider may implement protocols for both cache-based and stroke-based algorithms. SpiralKit can simply refer to the composite data provider implementation as an instance of the DGSKDrawDataProviderProtocol protocol within common code and defer specific functional references of the storage mechanism to the concrete draw engine implementation only. This allows data providers potentially to be both portable across draw engines of different algorithms and to be usable in draw engines that combine multiple storage/data capture approaches to achieve a certain effect, such as the highlighter draw tool.

Provided Extensions of the DGSKDrawDataProviderProtocol Protocol

SpiralKit provides the following extensions to the DGSKDrawDataProviderProtocol protocol:

• DGSKCacheDrawDataProviderProtocol – A data provider which should accommodate most cache-based drawing algorithms.
• DGSKStrokeDrawDataProviderProtocol – A data provider which should accommodate most stroke-based drawing algorithms.

The DGSKDataProviderProtocol Protocol

The DGSKDataProviderProtocol protocol is a marker interface, meaning no methods or properties are specified in the protocol. It simply serves as an indicator of functional intent. Classes intended to serve as data providers or component properties of data providers should implement this interface. While not explicitly required or referenced by the SpiralKit core, this marker interface can be useful in providing broader persistence functionality of draw data through mechanisms such as CoreData.

Additional Components Included in SpiralKit

SpiralKit includes additional components that serve largely complementary roles within the framework:

• Factories
• Utility Classes
• The Unloadable Instance Protocol
• The DGSKLog Macro

Factories

SpiralKit includes a set of factory classes that encapsulate much of the implementation details associated with constructing instances of several of the fundamental framework components. Using the factories to create instances of these components is not required. However, if you intend to use SpiralKit “as-is”, leveraging the factories may simplify incorporating the framework into your application.

The reference implementation uses these factory classes to create instances of fundamental framework components.

SpiralKit provides the following factories:

• DGSKDrawEngineFactory – A factory to create draw engine instances
• DGSKDrawContextStylingProviderFactory – A factory to create styling provider instances

DGSKDrawEngineFactory

The DGSKDrawEngineFactory creates DGSKSingleStrokeCacheDrawEngine draw engine instances if the specified styling provider indicates a draw tool type of DGSKDrawToolTypeHighlighter. This is because DGSKSingleStrokeCacheDrawEngine is specifically designed to implement the highlighter effect.

All other conditions create DGSKBezierCurveInterpolatedCacheDrawEngine draw engine instances. The factory includes code examples to create each of the alternate draw engines rather than the DGSKBezierCurveInterpolatedCacheDrawEngine draw engine.

DGSKDrawContextStylingProviderFactory

The DGSKDrawContextStylingProviderFactory provides methods which enable creating styling provider instances.

All styling provider instances from this factory will be DGSKRGBDrawContextStylingProvider instances.

Utility Classes

SpiralKit includes a collection of utility classes which provide “helper” methods used throughout SpiralKit. The methods of these classes are exclusively stateless, class-level methods.

These classes are private to the released framework and are not intended as public APIs to a host application. However, if you are forking SpiralKit, methods in these classes may be useful within your new framework code.

SpiralKit includes the following utility classes:

• DGSKDrawUtils – A collection of helper methods that implement algorithms (or portions of algorithms) used in the included draw engines
• DGSKGraphicsUtils – A collection of helper methods that simplify various graphics operations

The Unloadable Instance Protocol

The DGSKUnloadableInstanceProtocol is a protocol which specifies a common memory-release mechanism for the components of SpiralKit. The mechanism enables the on-demand release of allocated objects on the framework object hierarchy.

When incorporating SpiralKit into your application, you may wish to request that framework allocated objects are released on specific operations within your application, such as navigating to a new view. The DGSKUnloadableInstanceProtocol provides a means to trigger that cleanup upon request.

Classes that implement DGSKUnloadableInstanceProtocol should clear any references to associated framework objects when prepareForUnload is called. This will enable the objects to fall out of retained scope within an ARC-enabled application and be released from memory, assuming no additional non-framework references to those objects exist.

Use of DGSKUnloadableInstanceProtocol is largely at your discretion. If you prefer to implement an alternative mechanism for releasing SpiralKit-framework-referenced objects, you can largely ignore DGSKUnloadableInstanceProtocol.

The DGSKLog Macro

The DGSKLog is a wrapper around NSLog which facilitates enabling and suppressing logging statements written to the console. If you wish to have logging statements written to the console for development builds but want those logging statements suppressed in a release build, the DGSKLog will provide that functionality.

SpiralKit enables and disables this macro depending on the release profile the build of the framework was created with. DGSKLog is enabled for Development release profile builds. DGSKLog is disabled for Internal Release and Public Release release profile builds.

Included Fundamental Component Implementations

Included Draw Engines

SpiralKit includes the following draw engine implementations:

Stroke-Based Engines

• DGSKStrokeDrawEngine – A basic stroke-based draw engine implementation. The algorithm tracks the last four captured draw points and performs a basic interpolation calculation of the points to determine the curve along the points. Stroke-based draw algorithms can extend this class and override drawPointPath: withContext: and optionally drawStroke: withContext: to provide a different stroke-based draw algorithm.
• DGSKDouglasPeuckerStrokeDrawEngine – A stroke-based draw engine implementation using the Douglas-Peucker algorithm. The algorithm tracks the last four captured draw points and performs a Douglas-Peucker calculation along the entire stroke to calculate the intended shape of the stroke given the current stroke data.

Cache-Based Engines

• DGSKInterpolatedCacheDrawEngine – A basic cache-based draw engine implementation. The algorithm tracks the last four captured draw points and performs a basic interpolation calculation of the points to determine the curve along the points. Cache-based draw algorithms can extend this class and override performDrawWithContext: to provide a different cache-based draw algorithm.
• DGSKQuadCurveInterpolatedCacheDrawEngine – A cache-based draw engine implementation using a Quad-Curve Interpolation algorithm. The algorithm tracks the last four captured draw points and attempts to smooth the curve by calculating the midpoint values between the four most recent tracked points before performing the interpolation calculation.
• DGSKBezierCurveInterpolatedCacheDrawEngine – A cache-based draw engine implementation using a Bezier Curve Interpolation algorithm. The algorithm tracks the last four captured draw points and performs a Bezier Curve Interpolation calculation to calculate the curve of the most recent four points.

Composite Engines

• DGSKSingleStrokeCacheDrawEngine – A draw engine that implements both cache and stroke semantics to facilitate a specific drawing effect. The algorithm tracks the last four captured draw points and performs a basic interpolation calculation over those points, recalculates the stroke until finalized, and then writes those points to a bitmap for rending when the stroke is finalized.

Included Styling Providers

SpiralKit includes the following styling provider implementations:

• DGSKRGBDrawContextStylingProvider – A styling provider that is based on the RGB color space. SpiralKit ships exclusively supporting the RGB color space. Support for additional color spaces should be a matter of simply mimic’ing the RBG implementation by replacing CMYK or grey-scale attributes for the RGB component attributes and ensuring the implementing styling provider can translate those properties to and from a UIColor instance.

Included Effects Engines

SpiralKit includes the following effects engine implementations:

• DGSKVariableWidthDrawEffectsEngine – An effects engine that shrinks or grows the width of a stroke relative to the distance between draw points.
• DGSKHighlighterDrawEffectsEngine – An effects engine that adjusts the blend mode and alpha components to enable a semi-transparent stroke that composites with the content below the stroke.
• DGSKEraserDrawEffectsEngine – An effects engine that adjusts the blend mode to remove the bitmap content below the stroke.

Protocol Specifications

Host View

DGSKDrawViewProtocol

Properties

• (strong, nonatomic) id<DGSKDrawEngineProtocol> drawEngine – A mutable reference to the draw engine associated with the host view.

Draw Engines

DGSKDrawEngineProtocol

Properties

• (readonly, strong) id<DGSKDrawContextStylingProviderProtocol> stylingProvider – A read-only reference to the styling provider associated with the draw engine. The styling provider provides rules for how a stroke should be visually decorated but not calculated.

Methods

• - (id) initWithView:(UIView *)hostView stylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)stylingProvider data:(id)drawData – The default initializer for a draw engine. All draw engines must provide this initializer to create an instance of the draw engine.
• - (void) changeStylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)stylingProvider – A method which updates the styling provider used by the draw engine. This method is responsible for resetting and calibrating any state data in the draw engine instance to the new styling provider.
• - (void) beginCapture – A method typically called by the host view when the application should begin tracking a new stroke. This method is responsible for preparing both the draw engine and draw data for capturing a new stroke.
• - (void) addFirstPoint:(CGPoint)point – A method typically called by the host view when the first draw point is captured by the data-input mechanism. This method is responsible for adding the new point to the draw data. Depending on the drawing algorithm, specific processing may be needed for the first draw point rather than for subsequent draw data points within the same stroke. This method enables an easy mechanism for distinguishing the first point from subsequent stroke points.
• - (void) addPoint:(CGPoint)point – A method typically called by the host view when a draw point is captured by the data-input mechanism. This method is responsible for adding the new point to the draw data.
• - (void) endCapture – A method typically called by the host view when the data-input mechanism indicates that a draw operation is complete. The method is responsible for finalizing draw data, persisting it if necessary, ensuring the draw output is accurate, and cleaning up any state from the draw operation.
• - (void) cancelCapture – A method typically called by the host view when the data-input mechanism indicates that a draw operation has been cancelled. The method is responsible for cleaning up any state from the draw operation and any previously captured draw data for the stroke.
• - (void) draw:(CGRect)invalidatedRegion – A method typically called by the host view to render the captured draw data to the host view. This method is responsible for actually producing the visual output of the drawing.

Styling Providers

DGSKDrawContextStylingProviderProtocol

Properties

• (nonatomic) DGSKDrawToolType drawToolType – A mutable reference to the type of drawing tool the styling provider is attempting to mimic.
• (nonatomic, readonly) CGColorSpaceRef (*CreateStylingColorSpace)() – A read-only functor which enables abstract mapping of the OS-specific color space creation API to the abstract interface. That is a fancy way of saying this property allows you to map a specific iOS API to this property in a general way which enables SpiralKit to call it when needed without needing to know what the specific API is.
• (nonatomic) UIColor *color – A mutable reference to the color to be used when drawing the stroke.
• (nonatomic) CGBlendMode blendMode – A mutable reference to the blend mode to be used when drawing the stroke.
• (nonatomic) CGFloat lineWidth – A mutable reference to the size to be used when drawing the stroke.
• (nonatomic) CGLineCap lineStyle – A mutable reference to the shape to be used when drawing the stroke.
• (nonatomic, strong) id<DGSKDrawEffectsEngineProtocol> effectsEngine – A mutable reference to the effects engine associated with the styling provider. The effects engine provides rules for how a stroke should be visually modified while drawing.

Methods

• - (id) init – The default initializer for a styling provider. All styling providers must provide this initializer to create an instance of the styling provider.
• - (id) initAsToolType:(DGSKDrawToolType)type – An initializer for creating a styling provider instance with the defaults associated with a particular draw tool. All styling providers must provide this initializer to create an instance of the styling provider.
• - (id) initAsToolType:(DGSKDrawToolType)type withEffectsEngine:(id<DGSKDrawEffectsEngineProtocol>)effectsEnginee – An initializer for creating a styling provider instance with the defaults associated with a particular draw tool and with the specified effects engine implementation. All styling providers must provide this initializer to create an instance of the styling provider.
• - (id) initWithEffectsEngine:(id<DGSKDrawEffectsEngineProtocol>)effectsEngine – An initializer for creating a styling provider instance while applying a the specified effects engine implementation. All styling providers must provide this initializer to create an instance of the styling provider.
• - (id) initWithStylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)provider – An initializer which creates a new copy of a styling provider based on a deep copy of the provided styling provider. All styling providers must provide this initializer to create an instance of the styling provider.
• - (bool) applyPropertiesToContext:(CGContextRef)context – The method which applies the specified visual style to the active stroke.
• - (bool) applyPropertiesToContext:(CGContextRef)context withEffectsBasedOnPoints:(NSArray *)points – A method which applies the specified visual style to the active stroke and passes point information to the effects engine for use in calculating point-based effects.
• - (void) resetEffects – A method which is responsible for resetting any effects-related calculations. This method is typically called when a stroke is finalized or cancelled.
• - (void) applyToolType:(DGSKDrawToolType)toolType – A method which is responsible for applying any styling modifications when the host application requests a new draw tool type. This method can be used to recycle a styling provider instance by simply changing it’s draw properties to fit the requested draw tool type rather than creating a new instance.

DGSKRGBDrawContextStylingProviderProtocol

Properties

• (nonatomic) CGFloat colorComponentRed – A mutable reference to the red color component of the RGB color scheme.
• (nonatomic) CGFloat colorComponentGreen – A mutable reference to the green color component of the RGB color scheme.
• (nonatomic) CGFloat colorComponentBlue – A mutable reference to the blue color component of the RGB color scheme.
• (nonatomic) CGFloat colorComponentAlpha – A mutable reference to the alpha component of the RGB color scheme.

Effects Engines

DGSKDrawEffectsEngineProtocol

Methods

• - (id) init – The default initializer for an effects engine. All effects engines must provide this initializer to create an instance of the effects engine.
• - (id) initWithEffectsEngine:(id<DGSKDrawEffectsEngineProtocol>)effectsEngine – An initializer which creates a new copy of an effects engine based on a deep copy of the provided effects engine. All effects engines must provide this initializer to create an instance of the effects engine.
• - (void) calibrateToStylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)stylingProvider – A method which synchronizes the properties of an effects engine to the settings of a styling provider. The method is typically called when a property of the styling provider that may be used by the effects engine is changed, such as changing the base stroke size.
• - (void) applyEffectsBasedOnPoints:(NSArray *)points toStylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)stylingProvider – A method which applies the visual effect to the properties of the styling provider.
• - (void) resetEffectsForStylingProvider:(id<DGSKDrawContextStylingProviderProtocol>)stylingProvider – A method which resets the properties of the styling provider to the state prior to effect adjustment.

Data Providers

DGSKDrawDataProviderProtocol

Methods

• - (void) strokeFinalized – A method typically called by the draw engine when the data-input mechanism indicates that a draw operation is complete. This method is responsible for persisting draw data and cleaning up any state from the draw operation present in the data provider. This method is commonly called from a draw engine’s endCapture method.

DGSKStrokeDrawDataProviderProtocol

Properties

• (nonatomic, readonly) NSArray *drawStrokes – A read-only reference to the collection of strokes that constitute the complete drawing.

Methods

• - (id<DGSKStrokeDataProviderProtocol>) createStrokeInstance – A factory method that creates a new stroke data model instance.
• - (void) addStroke:(id<DGSKStrokeDataProviderProtocol>) stroke – A method that adds a new stroke to the stroke-based data provider data model.

DGSKCacheDrawDataProviderProtocol

Properties

• (nonatomic) UIImage *contentBitmap – A mutable reference to the complete drawing bitmap created by the draw engine.

DGSKDataProviderProtocol

none

DGSKStrokeDataProviderProtocol

Properties

• (readonly) NSUInteger numberOfPoints – A read-only reference to the number of points within a stroke.
• (nonatomic, readonly) NSArray *drawPoints – A read-only reference to the complete collection of points defining a stroke.

Methods

• - (void) addDrawPoint:(CGPoint) dataPoint – A method which adds a captured draw point to the collection draw points within a stroke.

Utilities

DGSKUnloadableInstanceProtocol

Methods

• - (void) prepareForUnload – A method which should clear any references to associated framework objects. This will enable the framework objects to fall out of retained scope within an ARC-enabled application and be released from memory, assuming no additional non-framework references to those objects exist.

---