Docs from sprite trimming, new blur effect, texture defaults (#136)

markdown/api/library/display/getDefault.markdown

@@ -54,6 +54,12 @@ A color key indicates which default color value is set.
 
 ## Texture Keys
 
+* `"isExternalTextureRetina"` — The default [Boolean][api.type.Boolean] value to be assigned as a [external texture][api.type.TextureResourceExternal]'s sampling behavior whenever a new one is created, say
+by a plugin. This is `true` by default.
+
+* `"isImageSheetFrameTrimCorrected"` — The default [Boolean][api.type.Boolean] value to be assigned as a new [sprite][api.type.SpriteObject]'s frame trim correction behavior whenever a sprite is loaded by
+Solar2D. This is `false` by default.
+
 * `"magTextureFilter"` — The default magnification sampling filter applied whenever an image is loaded. Values include `"linear"` or `"nearest"`.
 
 * `"minTextureFilter"` — The default minification sampling filter applied whenever an image is loaded. Values include `"linear"` or `"nearest"`.

markdown/api/library/display/setDefault.markdown

@@ -87,6 +87,10 @@ A color key specifies which default color value to set.
 
 * `"preloadTextures"` — The default behavior for texture loading is to load the texture when the display object is created or when the display object uses it. Setting this value to `false` will delay loading of the texture to when the object appears on screen or to when it becomes visible.
 
+* `"isExternalTextureRetina"` — The default behavior for external textures is to be sampled like retina textures, applying content scaling to the `width` and `height` when resolving texture coordinates. Setting this value to `false` will simply use `width` and `height` as is.
+
+* `"isImageSheetFrameTrimCorrected"` — The default (legacy) behavior for trimmed sprites can lead to strange behavior when doing rotation or scaling on them. Setting this value to `true` will apply appropriate corrections. (It will also slightly affect how [object.anchorChildren][api.type.GroupObject.anchorChildren] updates. See the link for further details.)
+
 * `"isImageSheetSampledInsideFrame"` — Affects how [image sheet][api.type.ImageSheet] frames are sampled. If set to `true`, sampling is intruded by half of the source texture pixel size to avoid border artifacts. Default is `false`.
 
 * `"magTextureFilter"` — The default magnification sampling filter applied whenever an image is loaded by Solar2D. Once an image is loaded the first time, the same sampling filter will be applied for any subsequent loads of the same file. This is because textures are loaded once per file. Default value is `"linear"`. Alternative value is `"nearest"`.

markdown/api/type/GroupObject/anchorChildren.markdown

@@ -13,6 +13,12 @@
 
 By default, display groups do not respect anchor points. However, you can achieve anchor behavior on a display group by setting this property to `true`.
 
+<div class="guide-notebox-imp">
+<div class="notebox-title-imp">Note</div>
+
+Setting this property does not force an immediate update of the group, although other display properties will do so. This was assumed to be an oversight and fixed along with some sprite trimming issues. To opt-in to these fixes, set the [default][api.library.display.setDefault] of `"isImageSheetFrameTrimCorrected"` to `true`.
+
+</div>
 
 ## Example
 

markdown/api/type/SpriteObject/index.markdown

@@ -35,6 +35,8 @@ _(Inherits properties from [DisplayObject][api.type.DisplayObject])_
 
 _(Inherits methods from [DisplayObject][api.type.DisplayObject])_
 
+#### [object:useFrameForAnchors()][api.type.SpriteObject.useFrameForAnchors]
+
 #### [object:pause()][api.type.SpriteObject.pause]
 
 #### [object:play()][api.type.SpriteObject.play]

markdown/api/type/SpriteObject/useFrameForAnchors.markdown

@@ -0,0 +1,25 @@
+# object:useFrameForAnchors()
+
+> --------------------- ------------------------------------------------------------------------------------------
+> __Type__ [Function][api.type.Function]
+> __Object__ [SpriteObject][api.type.SpriteObject]
+> __Library__ [display.*][api.library.display]
+> __Return value__ none
+> __Revision__ [REVISION_LABEL](REVISION_URL)
+> __Keywords__ sprite, useFrameForAnchors, anchor
+> __See also__ [display.newSprite()][api.library.display.newSprite]
+> --------------------- ------------------------------------------------------------------------------------------
+
+## Overview
+
+Sets a frame in the currently loaded sequence as the reference for anchor points. Anchor point calculations will be performed as if this was the current frame, even when another is actually being displayed. Without
+this, sequences with variable-sized frames (possibly with trimming) can jump around during scaling and rotation, due to the anchor point resolving to a different position.
+
+## Syntax
+
+object:useFrameForAnchors( [frameIndex] )
+
+##### frameIndex ~^(optional)^~
+
+_[Number][api.type.Number]._ The frame index in the currently loaded sequence you want to use as reference. The default is the current frame, or 1 is none has been set. In a sprite sequence, `1` indicates the first
+frame <nobr>(not `0`)</nobr>.

markdown/guide/graphics/effects.markdown

@@ -163,6 +163,79 @@ object.fill.effect.vertical.sigma = 140
 ``````
 
 
+<!--- FILTER.BLUR-GAUSSIAN-LINEAR -->
+
+<a id="blurGaussianLinear"></a>
+<div class="newline"></div>
+
+<div class="side-by-side">
+
+---------------------------------------- ------------------ ------------------------------------
+![][images.simulator.fx-base-statue] &nbsp;&rarr;&nbsp; ![][images.simulator.fx-blurlinear]
+---------------------------------------- ------------------ ------------------------------------
+
+</div>
+
+### filter.blurGaussianLinear
+
+A lightweight approach to Gaussian blur, as described in [this RasterGrid article](https://www.rastergrid.com/blog/2010/09/efficient-gaussian-blur-with-linear-sampling/).
+
+* `horizontal.offset1` — default = `1.3846153846` ; min = `0` ; max = `100`
+* `horizontal.offset2` — default = `3.2307692308` ; min = `0` ; max = `100`
+* `vertical.offset1` — default = `1.3846153846` ; min = `0` ; max = `100`
+* `vertical.offset2` — default = `3.2307692308` ; min = `0` ; max = `100`
+
+``````lua
+object.fill.effect = "filter.blurGaussianLinear"
+``````
+
+
+<!--- FILTER.BLUR-GAUSSIAN-LINEAR-HORIZONTAL -->
+
+<a id="blurGaussianLinearHorizontal"></a>
+<div class="newline"></div>
+
+<div class="side-by-side">
+
+---------------------------------------- ------------------ ----------------------------------------------
+![][images.simulator.fx-base-cloth] &nbsp;&rarr;&nbsp; ![][images.simulator.fx-blurlinearhorizontal]
+---------------------------------------- ------------------ ----------------------------------------------
+
+</div>
+
+### filter.blurGaussianLinearHorizontal
+
+* `offset1` — default = `1.3846153846` ; min = `0` ; max = `100`
+* `offset2` — default = `3.2307692308` ; min = `0` ; max = `100`
+
+``````lua
+object.fill.effect = "filter.blurGaussianLinearHorizontal"
+``````
+
+
+<!--- FILTER.BLUR-GAUSSIAN-LINEAR-VERTICAL -->
+
+<a id="blurGaussianLinearVertical"></a>
+<div class="newline"></div>
+
+<div class="side-by-side">
+
+---------------------------------------- ------------------ --------------------------------------------
+![][images.simulator.fx-base-cloth] &nbsp;&rarr;&nbsp; ![][images.simulator.fx-blurlinearvertical]
+---------------------------------------- ------------------ --------------------------------------------
+
+</div>
+
+### filter.blurGaussianLinearVertical
+
+* `offset1` — default = `1.3846153846` ; min = `0` ; max = `100`
+* `offset2` — default = `3.2307692308` ; min = `0` ; max = `100`
+
+``````lua
+object.fill.effect = "filter.blurGaussianLinearVertical"
+``````
+
+
 <!--- FILTER.BLUR-HORIZONTAL -->
 
 <a id="blurHorizontal"></a>
@@ -174,8 +247,6 @@ object.fill.effect.vertical.sigma = 140
 ![][images.simulator.fx-base-cloth] &nbsp;&rarr;&nbsp; ![][images.simulator.fx-blurhorizontal]
 ---------------------------------------- ------------------ ----------------------------------------
 
-</div>
-
 ### filter.blurHorizontal
 
 * `blurSize` — default = `8` ; min = `2` ; max = `512`
@@ -1949,7 +2020,7 @@ This composite effect renders a point light upon a surface. In this effect, `poi
 
 The `pointLightColor` parameter is a table containing RGB+A values, and `ambientLightIntensity` specifies the intensity from `0` (dark) to `1` (full&nbsp;brightness).
 
-The `attenuationFactors` parameter is a table containing the diffuse light's distance attenuation factors. In this case, `{x,y,z}` are the constant, linear, and quadratic attenuation factors. Note that distance attenuation does __not__ affect ambient light intensity. For a better understanding of attenuation factors, read about [Falloff](https://developer.valvesoftware.com/wiki/Constant-Linear-Quadratic_Falloff) and [Attenuation&nbsp;of&nbsp;Light](https://learnopengl.com/PBR/Lighting).
+The `attenuationFactors` parameter is a table containing the diffuse light's distance attenuation factors. In this case, `{x,y,z}` are the constant, linear, and quadratic attenuation factors. Note that distance attenuation does __not__ affect ambient light intensity. For a better understanding of attenuation factors, read about [Falloff](https://developer.valvesoftware.com/wiki/Constant-Linear-Quadratic_Falloff) and [Attenuation&nbsp;of&nbsp;Light](http://www.felixgers.de/teaching/jogl/lightAttenuation.html).
 
 * `pointLightPos` — default = `{1,0,0}` ; min = `{0,0,0}` ; max = `{1,1,1}`
 * `pointLightColor` — default = `{1,1,1,1}` ; min = `{0,0,0,0}` ; max = `{1,1,1,1}`