@ff0000-ad-tech/ad-canvas

    1.4.1 • Public • Published
    RED Interactive Agency - Ad Technology

    npm (tag) GitHub issues npm downloads

    GitHub contributors GitHub commit-activity npm license PRs Welcome


    Ad Canvas

    This lightweight package is a simple-to-use tool that makes it easy to create animation, masking, layering, blend modes, and drawing all sorts of graphical content, such as:

    • Vector paths
    • Shapes
    • Bitmaps
    • Videos
    • Text

    Read more about some of the ways this framework compares to vanilla javascript in the Why CanvasDrawer? section.

    Getting Started

    Canvas Elements

    Features

    Tweening

    Getting Started

    It may be beneficial to familiarize yourself with the syntax of ad-ui, as there are many similarities. Or, this can be your stepping stone to ad-ui!

    CanvasDrawer

    Make a new CanvasDrawer instance - this instance will house whatever elements you create

    let myCanvasDrawer = new CanvasDrawer({
        target: myDomElement,
        css: {
            width: 300,
            height: 250
        },
        debug: true,
        retina: true
    })

    In this example, we create a new UICanvas DOM element (which can be referenced as myCanvasDrawer.canvas). Setting retina: true means the canvas will render at double-density. Setting debug: true adds a background color so that we can see the canvas element, which is transparent otherwise.

    Rendering

    CanvasDrawer has an update() method which must be called any time you make a change and want to see it.

    CanvasElements

    A CanvasElement is the broad term for anything that is drawn within the CanvasDrawer framework. It refers to:

    • CanvasImage - use a bitmap, canvas, CanvasDrawer, or video source to make image data
    • CanvasRect - create a rectangle
    • CanvasCircle - create an arc, semi circle, or circle
    • CanvasPath - use points and curves to create a pathed shape
    • CanvasText - write text into a canvas

    Example

    Draw a bitmap data into a CanvasDrawer. In this example, the source is referenced by the name of the bitmap, as ID'd by ImageManager - this might be "myBitmap.png"` for instance.

    let myImage = new CanvasImage({
        target: myCanvasDrawer,
        id: 'myCanvasImage'
        source: "myBitmap",
        params: {
            width: 300,
            height: 250
        }
    })
     
    // setting the alpha by ID
    myCanvasDrawer.elements.myCanvasImage.alpha = 0.5
     
    // setting the alpha by variable
    myImage.alpha = 0.5
     
    // re-render the CanvasDrawer to ensure update is seen
    myCanvasDrawer.update()

    Features

    These CanvasElements can have features such as:

    • drop shadows
    • rotation, scale, alpha
    • strokes

    There are also additional classes that, if imported, will open up other features to you, such as:

    Tweening

    Tweening a CanvasElement is as easy as initializing it through CanvasTweener - it's an additional load that you might not want, so we give you the option.

    // injects tweening capability into a CanvasDrawer instance
    CanvasTweener.init(myCanvasDrawer)
     
    // call the CanvasElement to tween by a variable definition
    myCanvasDrawer.tween.to(myImage, 2, { rotation: 90, alpha: 0 })
    // call the CanvasElement to tween by an ID
    myCanvasDrawer.tween.to("myCanvasImage", 2, { rotation: 90, alpha: 0 })
     
    myCanvasDrawer.tween.fromTo(myShape, 2, { scale: 0 }, { scale: 1, ease: Back.easeOut })
     
    myCanvasDrawer.tween.start()

    This tween object that is part of your CanvasDrawer instance uses the same format as GreenSock's Tween Package. However, since HTML5 canvas requires refreshing in order to render changes, CanvasTweener takes care of that for us without having to write update() calls elsewhere. The myCanvasDrawer.tween.start() method ensures these tweens don't begin until we're ready to call all of them.

    Why CanvasDrawer?

    It's a lightweight package!

    • Using every nook and cranny the CanvasDrawer suite has to offer only adds an additional 40k to your file size.
    • Compare that to other packages which are 150k or higher, and you have a fast-loading platform with powerful features giving you the best possible tools for quick development and stunning animations.

    The grunt-work has been done for you

    • The classes that allow for blurring, color transformations, etc are there to save you, the user, the effort of researching how to build and keep track of these effects.

    Animations are straightfoward

    • With vanilla Canvas2D, animation becomes complicated. There are no native object declarations or stored values: you must work that logic out yourself, and constantly call verbose code in order to render graphics.

    Compare some vanilla canvas drawing to how it might look using CanvasDrawer:

    // any time you want to draw the image at a different X, Y, width, or height, 
    // you need to clear your canvas ...
    ctx.clearRect(0, 0, 100, 200)
     
    // and if you want to scale, rotate, or change the alpha, that's another kind of logic 
    // you must develop code for and
    manage yourself
    ctx.save()
    ctx.globalAlpha = 0.5
    ctx.rotate(Math.PI)
    ctx.restore()
     
    // finally, make a verbose call to the context to draw all images you may have created
    ctx.drawImage(img1, 10, 10, 100, 200)
    ctx.drawImage(img2, 0, 0, 50, 50)
    ctx.drawImage(img3, 100, 30, 60, 60)
     
    // and how do you animate this? How do you get your image to move its x-coordinate using TweenLite?
    TweenLite.to(???, 1, {x: 200, onUpdate: function(){
        ctx.clearRect(...)
        ctx.drawImage(...)
    }})
    // sounds exhausting, and you're going erase every other image you added unless you put in 
    // additional conditions to re-draw them.

    CanvasDrawer makes the simple act or redrawing and moving elements easy, saving you file size and processing by packaging the creation and storage of a canvas' drawable data in objects easy to manipulate:

    myCanvasImage1.x = 10
    myCanvasImage2.rotation = 20
    myCanvasImage3.alpha = 0.5
     
    myCanvasDrawer.tween.to(myCanvasImage1, 1, { x: 200 })
    myCanvasDrawer.tween.start()
    // easy peasy, lemon squeezy

    API

    CanvasBlendMode

    CanvasBlur

    CanvasCircle

    CanvasColoring

    CanvasDisplaceChannel

    CanvasDisplacementMap

    • new CanvasDisplacementMap(imgObj)
    • .source : CanvasDrawer | UICanvas | canvas
    • .map : CanvasDrawer | UICanvas | canvas
    • .target : CanvasDrawer | UICanvas | canvas
    • .x : number
    • .y : number
    • .scaleX : number
    • .scaleY : number
    • .channelX : CanvasDisplaceChannel | number
    • .channelY : CanvasDisplaceChannel | number
    • .draw()

    CanvasDrawer

    CanvasElement

    • new CanvasElement()

    CanvasImage

    CanvasLineTo

    CanvasPath

    CanvasRect

    CanvasShape

    • new CanvasShape()

    CanvasSprite

    • new CanvasSprite()

    CanvasText

    CanvasTexture

    CanvasTiling

    CanvasTweener

    CanvasUtils


    Keywords

    none

    Install

    npm i @ff0000-ad-tech/ad-canvas

    DownloadsWeekly Downloads

    0

    Version

    1.4.1

    License

    MIT

    Unpacked Size

    365 kB

    Total Files

    46

    Last publish

    Collaborators

    • scientifantastic
    • gmcdev