====== SHMotionBlurSprite ======
---- dataentry extension ----
type          : extension
author_mail   : shilo86@gmail.com Shilo White
description   : A simple sprite with a motion blur effect.
lastupdate_dt : 2011-03-27
compatible    : v1.X
depends       : 
tags          : motion, blur, sprite
homepage_url  : https://gist.github.com/870334
download_url  : https://gist.github.com/gists/870334/download
sample_url    : http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurSample.zip
----

===== Description =====
SHMotionBlurSprite class will function just like a normal sprite, but it will give the children a motion blur effect. You can change the blur duration in seconds with "blurDuration" and change the starting blur alpha with "blurAlpha".

===== Sample =====
[[http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurSample.zip|{{http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurScreenshot.png}}]]
  * Project: [[http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurSample.zip|Quads With Blur]]
  * Screenshot: [[http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurScreenshot.png|QuadsWithBlurScreenshot.png]]
  * Recording: [[http://shilo.coarsemode.com/sparrow/extensions/shmotionblursprite/QuadsWithBlurRecording.mov|QuadsWithBlurRecording.mov]]

===== Example =====
<code objc>
//initialize a motion blur sprite with the default properties
SHMotionBlurSprite *motionBlurSprite = [SHMotionBlurSprite motionBlurSprite];
 
//set the blur duration to 10 seconds
motionBlurSprite.blurDuration = 10.0f;
 
//set the starting blur opacity to 25%
motionBlurSprite.blurAlpha = 0.25;
 
//set the blur duration to a negative number to set motion blur to forever
motionBlurSprite.blurDuration = SH_MOTION_BLUR_INFINITE;
motionBlurSprite.blurDuration = -1.0f;
 
//set the blur duration to zero to turn the motion blur off
motionBlurSprite.blurDuration = SH_MOTION_BLUR_NONE;
motionBlurSprite.blurDuration = 0;
</code>

===== Instructions =====
==== To add into your Sparrow project ====
  - Download the source files here: [[https://gist.github.com/gists/870334/download]]
  - Open your desired Sparrow project
  - Drag and drop the files into the "Groups & Files" pane
  - Open "Game.h"
  - Include the extension: <code objc>#include "SHMotionBlurSprite.h"</code>
  - Save "Game.h"

==== To add directly into Sparrow source ====
  - Download the source files here: [[https://gist.github.com/gists/870334/download]]
  - Save the files into Sparrow's "/Classes/" directory
    * Example: "/sparrow/src/Classes/"
  - Navigate back one directory and open "Sparrow.xcodeproj"
    * Example: "/sparrow/src/Sparrow.xcodeproj"
  - Inside the "Groups & Files" pane, locate the "Display" group folder
    * Example: "Sparrow -> Classes -> Display"
  - Right click the "Display" group folder and click "Add -> Existing Files.."
  - Navigate into the "/Classes/" directory and select "SHMotionBlurSprite.h" and "SHMotionBlurSprite.m", then click "add"
  - On the next window, leave all options as default and click "add"
  - In the "Groups & Files" pane, Open "Sparrow.h"
    * Example "Sparrow -> Classes -> Sparrow.h"
  - At the bottom of the file, add: <code objc>#import "SHMotionBlurSprite.h"</code>
  - Save "Sparrow.h"
  - Close "Sparrow.xcodeproj"

===== Source Code =====
%gist(870334)%

===== Changelog =====
  * //2011-01-14:// First version
  * //2011-01-15:// Optimization and bug fixes
  * //2011-03-27:// fixed small warning, added property "renderTexture" so objects can be drawn to it directly if needed

===== Todo =====
  * change default width/height to screen width/height based on rotation
  * Allow objects to render behind it
      * Change the clear alpha value to 0
      * Get the motion blur to show correctly while alpha value equals 0

===== Special Thanks =====
  * [[http://forum.sparrow-framework.org/profile/daniel|Daniel]] for the idea of how to implement a motion blur effect