{"id":19370172,"url":"https://github.com/phonegap/phonegap-plugin-fast-canvas","last_synced_at":"2025-04-23T15:32:00.824Z","repository":{"id":8943132,"uuid":"10677468","full_name":"phonegap/phonegap-plugin-fast-canvas","owner":"phonegap","description":"Fast, 2D, mostly-HTML5-canvas-compatible rendering surface for Android.","archived":false,"fork":false,"pushed_at":"2016-03-04T14:20:14.000Z","size":418,"stargazers_count":195,"open_issues_count":7,"forks_count":58,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-02T17:11:15.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phonegap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-13T22:38:42.000Z","updated_at":"2024-08-08T15:19:03.000Z","dependencies_parsed_at":"2022-09-01T15:31:57.645Z","dependency_job_id":null,"html_url":"https://github.com/phonegap/phonegap-plugin-fast-canvas","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonegap%2Fphonegap-plugin-fast-canvas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonegap%2Fphonegap-plugin-fast-canvas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonegap%2Fphonegap-plugin-fast-canvas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonegap%2Fphonegap-plugin-fast-canvas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phonegap","download_url":"https://codeload.github.com/phonegap/phonegap-plugin-fast-canvas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250460540,"owners_count":21434261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T08:14:25.371Z","updated_at":"2025-04-23T15:32:00.496Z","avatar_url":"https://github.com/phonegap.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"FastCanvas\n==========\n\nFastCanvas is a Cordova/PhoneGap plugin which implements a very fast, 2D, \nmostly-canvas-compatible rendering surface for Android. It focuses on moving \ngraphics around on the screen quickly and efficiently using hardware \nacceleration.\n\nUnlike the HTML5 canvas, FastCanvas will encompass your entire screen and cannot be \nintegrated with other elements in the DOM.  It lives outside of the DOM in a separate \nrendering surface that fully covers all HTML content.  More on how FastCanvas is displayed \nto the screen is available in the [Architecture](#architecture) section. \nIf you already have an application which uses a full screen DOM canvas, switching over \nto FastCanvas could be an easy way to provide a boost in performance, and consistency within\nthat performance, to your mobile application or game.\n\nWhile FastCanvas attempts to look and behave very similar to the HTML5 canvas, it\nonly supports a subset of the HTML5 canvas API, focusing on what benefits most from\nhardware acceleration.  More information about API support is described in the \n[FastCanvas API](#fastCanvas-api) section.\n\n\nGetting Started\n===============\n\nFastCanvas is supported on Android devices.  Additionally, your application must \nbe designed so that:\n\n1. Your application runs a full screen canvas\n2. Use of the 2D canvas API is limited to transforms and drawing images (see: \n[FastCanvas API](#fastcanvas-api))\n\nFor devices that don't support FastCanvas, the API will fallback to using the standard\nHTML canvas.  This is handled for you seamlessly making it easy to write cross-platform \nCanvas applications the use FastCanvas on Android.\n\nPrerequisites:\n* [ADT for Eclipse](http://developer.android.com/sdk/index.html)\n* [Cordova](http://cordova.apache.org/#download) or [PhoneGap](http://phonegap.com/download/) for Android (Getting started guides: [Cordova](http://cordova.apache.org/docs/en/2.7.0/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android), [PhoneGap](http://docs.phonegap.com/en/2.7.0/guide_getting-started_android_index.md.html#Getting%20Started%20with%20Android))\n* [FastCanvas](https://github.com/phonegap/phonegap-fast-canvas-plugin)\n\n\n## Adding FastCanvas to Your Application ##\n\n1. Clone the FastCanvas tree down from github (if you haven't already).\n5. Copy `FastCanvas\\FastCanvas.js` to your Java project's `assets\\www` folder and include a reference to it in your `index.html`.\n3. Copy the `FastCanvas\\Android\\src\\com` folder to your Java project's `src` folder.\n4. Copy the `FastCanvas\\Android\\libs\\armeabi` folder to your Java project's `libs` folder.\n5. In your `res/xml/config.xml` file add the following line to the end of the \u003cplugins\u003e section: \n   \n```\n\u003cplugin name=\"FastCanvas\" value=\"com.adobe.plugins.FastCanvas\"/\u003e\n```\n\n### Adding FastCanvas using the PlugMan script ###\n\nAdditional prerequisites:\n* [nodejs](http://nodejs.org/)\n* [plugman](https://github.com/apache/cordova-plugman)\n\n```\n\tnpm install -g plugman\n```\n\nThis is an alternate method, as used by the PhoneGap Build system.\nAfter creating your Cordova app with `create`, run the PlugMan script as follows to install the FastCanvas plugin:\n\n```\n\tplugman --platform android --project \u003cyour project folder\u003e --plugin https://github.com/FastCanvas/FastCanvas.git\n```\n\n#### If you have scale issues with your content ####\nAdding the following to your `index.html` will often help:\n\n```\n\t\u003cmeta name=\"viewport\" content=\"user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi\" /\u003e\n```\n\n#### Changing the Java interface ####\n\nAdditional prerequisites:\n* Android NDK - the [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html) is a separate download.\nThe native interface used by FastCanvas is defined in `FastCanvasJNI.java`. \nIf at any point in time you change `FastCanvasJNI.java`, you'll also need to regenerate \n`FastCanvasJNI.h` and then recompile the native code.\n\nThese instructions are for Windows. If working on a Mac, use / instead of \\, mv instead of move, etc.\n\n1. Compile FastCanvasJNI.java:\n```\n\t\\FastCanvas\\Android\u003ejavac -d . src\\com\\adobe\\plugins\\FastCanvasJNI.java src\\com\\adobe\\plugins\\FastCanvasTextureDimension.java\n```\n\n2. Create FastCanvasJNI.h\n```\n\t\\FastCanvas\\Android\u003ejavah -jni com.adobe.plugins.FastCanvasJNI\n```\n\t\n3. Move it to the correct location\n```\n\t\\FastCanvas\\Android\u003emove com_adobe_plugins_FastCanvasJNI.h jni\\FastCanvasJNI.h\n```\n\t\n4. Clean up\n```\n\t\\FastCanvas\\Android\u003ermdir /s com\n```\n\t\n5. Build the JNI library from the command line (Command Prompt or Terminal window): \n```\n\t\\FastCanvas\\Android\u003e[path to NDK]\\ndk-build\n```\n\t\n\tShould produce output similar to: \n```\n\t\tCompile++ thumb  : FastCanvasJNI \u003c= FastCanvasJNI.cpp\n\t\tCompile++ thumb  : FastCanvasJNI \u003c= Canvas.cpp\n\t\tStaticLibrary    : libstdc++.a\n\t\tSharedLibrary    : libFastCanvasJNI.so\n\t\tInstall          : libFastCanvasJNI.so =\u003e libs/armeabi/libFastCanvasJNI.so\n```\n\n\nUsing FastCanvas in Your Project\n================================\n\nFastCanvas was designed to mimic the standard HTML 2D Canvas to help make it easy to use \nor implement in your existing canvas-based applications.  Like the HTML canvas, FastCanvas\nconsists of both a canvas object and a context object.  The API is very similar with a few\nexceptions:\n\n* Canvas objects are created with `FastCanvas.create()`\n* Image objects are created with `FastCanvas.createImage()`\n* At the end of each frame a call to `FastCanvas.render()` is required\n\nThese commands work with both FastCanvas and HTML canvas applications.  Once you have your \napplication working with FastCanvas, it will also work with an HTML canvas.\n\nThe following is a basic usage example of FastCanvas shifting and rotating an\nimage drawn to the screen:\n\n```javascript\nvar canvas = FastCanvas.create(); // specific to FastCanvas\nvar context = canvas.getContext(\"2d\");\nvar myImage = FastCanvas.createImage(); // specific to FastCanvas\nmyImage.onload = function(){\n   context.translate(100, 100);\n   context.rotate(Math.PI);\n   context.drawImage(myImage, 0, 0);\n   FastCanvas.render(); // specific to FastCanvas\n}\nmyImage.src = \"images/myImage.jpg\";\n```\n\nYou can see much of the code matches usage of the HTML canvas.  `FastCanvas.create()` will even create \nan HTML canvas is FastCanvas is not supported.  This is also the case \nwith `FastCanvas.createImage()` which, depending on the result from `FastCanvas.create()` will create \na standard HTML Image if an HTML canvas was created and a FastCanvasImage object (images used by FastCanvas) \nwhen FastCanvas is being used.  Usage of these image objects are largely the same - at least as far as \ncanvases are concerned - as you can see from the code used to load the image above.  Similarly, the API of \nthe context returned from `FastCanvas.getContext(\"2d\")` matches that of HTML's CanvasRenderingContext2D object, \nat least as far as FastCanvas supports it. `FastCanvas.render()` is an extra step specific \nto FastCanvas but will only do the necessary render step when a FastCanvas is being used and will be a \nno op (doing nothing) when an HTML canvas has been created.\n\nIn addition to the code changes, because FastCanvas applications are full screen, your HTML should also include \nthe following meta tag to be assured that window metrics are reported accurately and consistently:\n\n```html\n   \u003cmeta name=\"viewport\" content=\"user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, \n\t\twidth=device-width, height=device-height, target-densitydpi=device-dpi\" /\u003e\n```\n\n\n\nExample Using FastCanvas\n========================\n\nThe game \"Hungry Hero\" has been re-implemented in JavaScript (from\nAS3). It is a simple touch based flying game based on the Starling API.\nWe are currently using an approximation of Starling - a simple \ndisplay list API - to wrap calls to the FastCanvas plugin to do rendering.\n\nhttps://github.com/phonegap/phonegap-fast-canvas-example\n\n\nFastCanvas API\n==============\n\nThe bulk of the FastCanvas API consists a subset of the methods within the \nstandard HTML5 canvas implementation of \n[CanvasRenderingContext2D](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#canvasrenderingcontext2d) - \nthe 2D context obtained when using `canvas.getContext(\"2d\");`.  A goal in\ndesigning FastCanvas was to make it as close as possible to the existing\nHTML5 canvas to make its easy and intuitive to use, and to make the \nprocess of porting an existing application to FastCanvas as painless as possible.\n\nThe subset supported in FastCanvas for its context includes: \n\n| Member | Notes |\n| ------ | ----- |\n| context.clearRect(); | Not supported, but available (NOOP) |\n| context.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh); | Supported |\n| context.globalAlpha; | Supported |\n| context.resetTransform(); | Supported |\n| context.restore(); | Supported |\n| context.rotate(angle); | Supported |\n| context.save(); | Supported |\n| context.scale(x, y); | Supported |\n| context.setTransform(a, b, c, d, e, f); | Supported |\n| context.transform(a, b, c, d, e, f); | Supported |\n| context.translate(x, y); | Supported |\n\nAdditionally, FastCanvas includes the following:\n\n| Member | Notes |\n| ------ | ----- |\n| FastCanvas.create(); | Creates a canvas object for you, FastCanvas if available, otherwise a standard HTML canvas. |\n| FastCanvas.createImage(); | Creates an image object for you, FastCanvasImage if a FastCanvas was created in FastCanvas.create(), otherwise a standard HTML Image. |\n| FastCanvas.render(); | To be called after all context calls are finished to commit the drawing to the screen. |\n| FastCanvas.setBackgroundColor(color); | Sets the canvas background (automatic for first time calling getContext()) |\n| FastContext2D.capture(x,y,w,h,fileName, successCallback, errorCallback); | Saves the current state of the canvas as an image |\n\n\nArchitecture\n============\n\nFastCanvas runs a Canvas(-like) implementation. \n\n### On A Top Surface\n\nFastCanvas output will cover any HTML output - so you should generally avoid \nHTML rendering as it will only consume performance. The FastCanvas plugin \ncreates an OpenGL surface that sits on top of the browser.\n\n### OpenGL renderer in C++\n\nThe renderer itself is OpenGL ES1.1 command streams, and the code\nis written in C++. The advantage of C++ is both portability and\ncontrol of memory management. \n\n### Separate Thread\n\nYour JS code runs in the browser thread, while most of the work\nFastCanvas does in in the UI thread. A tight stream of rendering commands\nis sent between the threads. This allows some load balancing between\nthe threads, separation of the game from the renderer, and (in the \nfuture) downclocking the render thread.\n\n\nUsing FastCanvas Efficiently\n----------------------------\n\nFor best performance, minimize the number of draw calls per fram in the GL layer.\n\nWhat that means at the JavaScript level is:\n* Use sprite sheets\n* Use as few textures as possible\n* Avoid swapping textures in and out, and preload if possible.\n* Try to batch drawImage calls that use the same texture. It is vastly more efficient to make ten drawImage calls in a row using one texture, and then make ten more using a second texture, than to switch back and forth twenty times.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphonegap%2Fphonegap-plugin-fast-canvas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphonegap%2Fphonegap-plugin-fast-canvas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphonegap%2Fphonegap-plugin-fast-canvas/lists"}