Image.centerOrigin() off by half a pixel

[ReignOfError]

To find the center of an image, Image.centerOrigin() divides the image's width and height by two; since indexing starts at 0, the numerators should be width-1 and height-1.

This doesn't affect even image dimensions (e.g., for an image with a side length of 4, 4/2 = 2 is equivalent to (4-1)/2 = 1.5 since the latter rounds to 2) but the center point ends up being one pixel off the actual midpoint for sides with an odd length (e.g., 3/2 = 1.5 isn't equivalent to (3-1)/2 = 1 since the former rounds to 2). So, for a 3 x 3 image, this function will place the origin at (2,2) instead of at the centre point located at (1,1).

[ReignOfError]

Sorry, ran a quick test to double-check this after posting and thought for a moment that I'd made a mistake (so I closed the issue), but a bit more testing indicated that doing so was premature.

I should point out, however, that if lines 109 and 110 in Image.as

_point.x = point.x + x - originX - camera.x * scrollX;
_point.y = point.y + y - originY - camera.y * scrollY;

end up being negative, rounding corrects the origin position for odd dimensions (since rounding a negative number results in a number with a lower absolute value, the opposite of what occurs when a positive value is rounded). The aforementioned test used a 5 x 5 image placed at (0,0), thus rounding "fixed" the origin offset.

[BlckKnght]

The originX and originY values that get set by centerOrigin() are Number variables, so there is no rounding happening within the FlashPunk code (they'll hold 2.5 quite happily). However, when an (unrotated, unscaled, non-blending) Image who's translated coordinates are not integers is rendered, it will be "snapped" to an exact pixel location because of the render() method's use of BitmapData.copyPixels() to do the actual drawing. This is much faster than the other rendering mode (using BitmapData.draw()), but it doesn't handle non-integer coordinates well (it rounds or truncates them in some way that I've not investigated).

So I don't think this is a FlashPunk bug, or at least, not one that's limited to centerOrigin() (whether the larger behavior of using copyPixels() for rendering is buggy is a much more complicated question). The rounding you're seeing is simply a limitation of doing bitmap blitting with non-integer coordinates. If it is causing your rendering to be off by one pixel in a consistent way, you can fix it by adding 0.5 to the x and y coordinates of the Image or Entity instance, perhaps, though this is probably only useful if the coordinates are only going to be adjusted by exact integer amounts during gameplay.

[ReignOfError]

Sorry, I should have made my comment about the test clearer. The problem itself isn't attributable to rounding; the way Actionscript rounds real numbers (it always rounds up, i.e., -0.5 rounds to 0, not -1, but 0.5 rounds to 1) merely masked the effect of the problem when I ran my quick test (I used a 5x5 image at the stage origin, so _point.x ended up being -2.5, which was rounded to -2 when copyPixels() was called). Prior to the test, I assumed -0.5 would round to -1 in Flash, which is the case when rounding in a number of other languages, so the result initially made me think I'd remembered incorrectly. However, this was cleared up once I looked into Flash's rounding behaviour.

That particular test case is an exception; when _point.x and _point.y are both positive (which is a more typical scenario), rounding affects the origin coordinates of images with an odd side length and the image origin will be off by 1 pixel in each direction when the image is rendered. This isn't a problem with Flash itself or copyPixels(). It's simply due to the fact that Image.centerOrigin() currently calculates the center of an image using indexing start at 1, not 0.

For example, for a 3x3 image, the available x coordinates are 0, 1, and 2. Accordingly, the x coordinate of the center is 1 (in the general case, it's (width-1)/2). The same logic applies for the y coordinate of the center. However, Image.centerOrigin() computes the x coordinate of the origin by dividing the width by 2, which for the 3x3 case gives 1.5, a value that is correct for 1-based indexing but not 0-based indexing. When the image is rendered, 1.5 gets rounded up and the result is a 1-pixel offset (except in the case discussed above).

To fix this, Image.centerOrigin() simply needs to be changed from

public function centerOrigin():void
{
originX = _bufferRect.width / 2;
originY = _bufferRect.height / 2;
}

to

public function centerOrigin():void
{
originX = (_bufferRect.width-1) / 2;
originY = (_bufferRect.height-1) / 2;
}

This also correctly computes the center for even-sided images. E.g., for a 4x4 image, the center coordinates are (1.5, 1.5) since available coordinates in x and y are 0, 1, 2, and 3.

[BlckKnght]

I think you're misunderstanding how pixel coordinates are interpreted in Flash and FlashPunk. This is probably the most common interpretation in computer graphics, but I'm sure there are other interpretations used in some other programs.

In FlashPunk, each pixel represents a 1x1 area which is identified by the coordinates of its upper left corner (not its center!).

So, the pixel identified by the coordinates (0, 0) spans from 0 to 1 on each axis and its center is at (0.5, 0.5), the pixel at coordinate (0,1) spans from 0 to 1 on the x-axis and 1 to 2 on the y-axis and is centered at (0.5, 1.5), and so on.

An area of pixels (such as an image being rendered) is also described by the coordinates of its upper left corner, along with its width and height, which can be used to calculate the coordinates of its other corners. A 3 by 3 image being rendered at (7,4) will span from 7 to 10 along the x-axis, and from 4 to 7 along the y-axis. (Note that the coordinates of its other corners describe pixels that are not inside the image's boundaries. This is OK!) The image's center is (8.5, 5.5), which is the center of the pixel at (8,5) (the image's center pixel).

Here's what that 3x3 image would look if you could see the values of the coordinate axes (where the Xs represent the pixels):

 |7 8 9 10
-+----------
4|
 | X X X
5|
 | X X X
6|
 | X X X
7|

FlashPunk's calculations are correct, given this interpretation of pixel coordinates. The changes you are suggesting are not, and they would break a lot of existing code.

[ReignOfError]

Yes, a pixel at (x,y) fills a 1x1 element with the element's upper left corner located at (x,y). I'm quite clear on that. However, consider the 3x3 image example: you state that a 3x3 image rendered at (7,4) will span 7 to 10 along the x-axis. I agree that the x coordinate of the geometric center of the image is 8.5. However, the x coordinate at which the image's center pixel should be located - in pixel coordinates, i.e., the location of the pixel's upper-left corner - is 8.

Since Flashpunk renders images without anti-aliasing in this context, I believe centerOrigin() should be calculating the pixel coordinates of the image center, not its geometric coordinates. However, I should note that, when an image is rendered, it appears that copyPixels simply truncates any decimal components in the destination coordinates (I believe I may have been incorrect when I initially attributed the behaviour we're discussing to rounding).

If you haven't done so, I'd suggest replicating my quick 3x3 image test, which demonstrates the effect of the truncation. Here's the code I used (testImage is just a 3x3 embedded image; the following code goes in the constructor of a class derived from Flashpunk's World class):

testImage.centerOrigin();
var testEnt:Entity = new Entity(5, 5, testImage);
add(testEnt);

For a 3x3 image, the actual geometric center is, as you say, 1.5, and, if we were using anti-aliased rendering, it would make sense to use this value, e.g., by instructing an anti-aliased rendering method to render the image at (3.5, 3.5). However, since aliased rendering is used, using these coordinates results in an offset because the decimal component is truncated when the image is rendered; accordingly, the image gets rendered at (3,3) with its center pixel at (4,4), not (5,5).

I should note that my interpretation of new Entity(5, 5, testImage) after centerOrigin() has been called is "place the entity such that the pixel coordinates of its image's center pixel are (5,5)"; this results in the geometric coordinates of the image's center pixel being (5.5, 5.5). I think this is the most intuitive interpretation in this context. If anti-aliasing were used, my interpretation might change to "place the entity such that the geometric coordinates of its image's center pixel are (5,5)", which would of course result in the center pixel's pixel coordinates being (4.5,4.5).

At any rate, hopefully I've clarified what I'm getting at.

[BlckKnght]

I should note that my interpretation of new Entity(5, 5, testImage) after centerOrigin() has been called is "place the entity such that the pixel coordinates of its image's center pixel are (5,5)"; this results in the geometric coordinates of the image's center pixel being (5.5, 5.5). I think this is the most intuitive interpretation in this context. If anti-aliasing were used, my interpretation might change to "place the entity such that the geometric coordinates of its image's center pixel are (5,5)", which would of course result in the center pixel's pixel coordinates being (4.5,4.5).

FlashPunk is a bit conflicted where it comes to aliasing. It mostly doesn't think about it. It does not, as you're assuming always use integer rendering. Try setting testImage.blend = "normal" in your test case. I think you'll see your image anti-aliased. (Edit: I just tried this, and it still seems to be aliased, just differently so. It's one pixel off in position in each axis, relative to rendering without a blend mode set. I'm not sure why, exactly.)

There's also the fact that even when pixel-snapping happens, the rounding or truncation will happen after image's origin values have been combined with both the Image and it's Entity's x and y coordinates and the camera's x and y coordinates. Any or all of those values can be non-integers. It doesn't make sense to offset one of them and not the others (the Entity class has its own centerOrigin() method, for example, which works just like Image's).

If your 5x5 image was going to be rendered at (0.5, 0.5), what should it's center be? What if it was located at (0,0), but the camera was at (0.5, 0.5)? Your suggested change will simply move the "weird rounding" spot to a different place.

Users of FlashPunk should learn to expect that centered images with odd widths or heights may have aliasing issues. If they care, they can take steps to correct them (offsetting by 0.5, perhaps, or using scale or blend to force anti-aliasing). Or if they don't care (because they need the high performance of copypixels() or because they're going to have aliasing issues anyway due to non-integer positions), they can choose to do nothing.

[ReignOfError]

Interesting! Changing testImage.blend to BlendMode.NORMAL (equivalent to "normal") centers the image properly, but only if FP.stage.quality isn't set to StageQuality.LOW (StageQuality.LOW disables anti-aliasing). It seems that turning on normal blending changes how copyPixels() handles non-integer coordinates, presumably by enabling some under-the-hood antialiasing calculation. With blending set to null, the decimal component of a coordinate value gets truncated, but with blending set to normal, coordinates are rounded (which is why centering works properly with blending turned on, at least for half-pixel coordinate values).

It sounds like you've tried this already, but in case anyone else looks at this in the future, here's a quick demo (again, this code just goes in the constructor of a World-derived class):

// testImage origin isn't changed
// If the next line is commented out, testEnt appears at (0,0); otherwise, it's rendered at (1,1)
testImage.blend = BlendMode.NORMAL; 
var testEnt:Entity = new Entity(0.5, 0.5, testImage);
add(testEnt);

Although blending "fixes" the centering issue by (apparently) changing copyPixels()'s behavior from truncation to rounding, I think it's important to ensure consistent behaviour regardless of whether blending/anti-aliasing is turned on or off. For example, for a 3x3 image we wish to center at (5, 5) (taking "center" to mean "position such that its center pixel is located at pixel coordinates (5, 5)"):

• Image center relative to image origin (geometric coordinates): (1.5, 1.5)
• Image center relative to image origin (pixel coordinates): (1, 1)
• Image position on stage using center in geometric coordinates: (3.5, 3.5)
• Image position on stage using center in pixel coordinates: (4, 4)

Result when using copyPixels():

• Image center computed using geometric coordinates:
  • No blending (blend = null): Image rendered at (3, 3) and center pixel located at (4, 4)
  • Normal blending: Image rendered at (4, 4) and center pixel located at (5, 5)
• Image center computed using pixel coordinates:
  • No blending (blend = null): Image rendered at (4, 4) and center pixel located at (5, 5)
  • Normal blending: Image rendered at (4, 4) and center pixel located at (5, 5)

I think the fact that using pixel coordinates to specify the center results in the same behaviour with or without anti-aliasing is an argument in its favour. However, it's also worth considering an image with even dimensions, say a 2x2 image also centered at (5, 5), as the behaviour is now reversed (I should note that obviously an image with even dimensions doesn't actually have a center pixel, but the coordinates of such a pixel can still be given in pixel coordinates, although they're purely hypothetical):

• Image center relative to image origin (geometric coordinates): (1, 1)
• Image center relative to image origin (pixel coordinates): (0.5, 0.5)
• Image position on stage using center in geometric coordinates: (4, 4)
• Image position on stage using center in pixel coordinates: (4.5, 4.5)

Result when using copyPixels():

• Image center computed using geometric coordinates:
  • No blending (blend = null): Image rendered at (4, 4) and center pixel located at (4.5, 4.5) [note that the center of the center pixel is located at (5, 5), i.e., the image is centered properly in geometric coordinates this time]
  • Normal blending: Image rendered at (4, 4) and center pixel located at (4.5, 4.5) [see comment on previous line]
• Image center computed using pixel coordinates:
  • No blending (blend = null): Image rendered at (4, 4) and center pixel located at (4.5, 4.5)
  • Normal blending: Image rendered at (5, 5) and center pixel located at (5.5, 5.5)

This demonstrates that, for images with even dimensions, the pixel coordinate method is the one that's inconsistent. Accordingly, we're left with a tradeoff: do we want odd-dimensioned images to have their center pixel positioned correctly regardless of aliasing state, or do we want even-dimensioned images to have their center pixel positioned correctly regardless of aliasing state? I think it makes more sense to choose the former, since the "center pixel" in even-dimensioned images doesn't technically exist. However, I admit that such a point of view is biased towards the pixel coordinates viewpoint; from the geometric coordinates viewpoint, even-dimensioned images are placed such that their geometric center is located at the specified coordinate - in this case, (5, 5).

In light of this, I think the centerOrigin() function should be altered such that if the width of the image (or entity) is even, the x coordinate of the center is calculated as width/2 and if the width is odd, the x coordinate is computed as (width-1)/2. The same logic applies to height and the y coordinate of the center. When using aliased rendering, I think this accounts for the best of both worlds, since you can't position the geometric center of an odd-dimensioned image at a pair of integer coordinates and you can't position the (purely virtual) center pixel of an even-dimensioned image at a pair of integer coordinates.

[Draknek]

Just a quick note implementation note: blending makes a difference because copyPixels is only used if there is no blend mode set (and the image is not rotated or scaled). Otherwise it uses draw instead, which does not snap to pixel values.

I've been following this thread vaguely but haven't had time to dive into the details. @BlckKnght knows what he's talking about, I'm happy for him to call the shots here.

[ReignOfError]

Based on the blending on/off test (which, as you pointed out, is really a copyPixels vs draw test) I discussed in my previous comment, it appears the both copyPixels and draw snap to integer coordinate values when modifying BitmapData. However, it looks like the former truncates real numbers in coordinates while the latter rounds them, although I can't find any mention of this in the documentation for BitmapData.

As BlckKnight originally noted, when draw is used, the result of specifying sub-pixel (i.e., real-valued) coordinates isn't an anti-aliased image (at least for this particular test), it's just an image offset by 1 pixel (relative to the image rendered by copyPixels). Further testing showed that this occurs in each dimension for which the coordinate value has a decimal component greater than or equal to 0.5. I don't know why copyPixels truncates real-valued coordinates while draw rounds them, but my suggested modifications to centerOrigin (in the last paragraph of my previous comment) ensure consistent results regardless of which method is used to render to the target BitmapData while also centering whichever of the geometric or pixel centers along each axis can be truly centered given that both copyPixels and draw snap to integer pixel values when blitting (for even dimensions, this is the geometric center; for odd dimensions, this is the center pixel row or column).

[BlckKnght]

Again, I don't think we should do any fudging of the origin for odd widths and heights. FlashPunk uses grid coordinates everywhere, and our users should expect that.

There are really only two solutions to aliasing:

1. Use all integer coordinates. This means that centering an odd-width or height image is a bad idea, unless you specifically correct for the non-integer results! FlashPunk can't anticipate all of the possible places that non-integer values could come from (e.g. your own code calculating width/2), so its up to the programmer to avoid them. Our best way to help out is to make all of our calculations easy to understand. Always using grid coordinates does this. Setting integer origin values for both even and odd dimensioned images would be much more confusing.
2. Use whatever coordinates make the most sense for your game, and ignore the aliasing (or get anti-aliased rendering after rotation or scaling). This is typically the best solution when you're going to have non-integer values in more than one of the camera, Entity and Image positions or origins. It's not worth trying to force some of those to be integers when the others will not be. If the Image is going to be scaled or rotated, there's similarly no reason to worry about integer coordinates, since the transformation is going to cause things to not be lined up perfectly anyway (and, conveniently, the drawing will usually be anti-aliased by Flash).

There is no good reason for FlashPunk to try for consistent aliasing of non-integer coordinates. There are always going to be discontinuities, either when you shift from a fractional coordinate of 0.99 to 1.0 (if the values are being truncated) or from 0.49 to 0.50 (if they're being rounded). If the programmer cares about pixel exact rendering, they should use integer coordinates (everywhere!).

[ReignOfError]

This is subjective, of course, but I don't consider it fudging; rather, I consider it a matter of producing a predictable result for both odd- and even-dimensioned images given that copyPixels truncates coordinates but draw rounds them.

If an odd-dimensioned image has its origin centered and is told to render at (X, Y), isn't it logical to expect the image's center pixel to be placed at (X,Y) rather than (X-1, Y-1), as is the case when copyPixels is used? Additionally, the fact that this behaviour changes such that the center pixel is placed at (X,Y) if draw is being used for rendering is an important inconsistency (this is an issue with Flash, not Flashpunk, but it can easily be accounted for as previously detailed). Even if (X-1, Y-1) is preferred as the pixel coordinates approximation to placing the geometric center at (X, Y), this should at least remain consistent regardless of whether copyPixels or draw is being used for rendering.

For the even case, if an even-dimensioned image has its origin centered and is told to render at (X, Y), I think the current behaviour of centerOrigin makes sense since it results in the geometric center of the image being located at (X, Y) regardless of whether copyPixels or draw is being used for blitting, which is a reasonable result since an even-dimensioned image has no center pixel.

Also, the truncated value of 0.99 is 0, not 1, and 0.49 would be rounded to 0 by draw since it's less than 0.5. For example:

• Given (0.5, 0.5) (this case demonstrates the effect of centerOrigin on odd-dimensioned images):
  • copyPixels truncates to (0, 0)
  • draw rounds to (1, 1)
• Given (0.99, 0.99)
  • copyPixels truncates to (0, 0)
  • draw rounds to (1, 1)
• Given (0.49, 0.49):
  • copyPixels truncates to (0, 0)
  • draw rounds to (0, 0)

This behaviour can be observed if these coordinate pairs are used as entity coordinates in the demo code I included two comments ago and the BlendMode line is alternately commented out and left in. If you try this and the resulting behaviour is different from what I've described, please let me know and I can put the full code and demo image I used on the Flashpunk forums. (I should note that I agree that normally it is inadvisable to place entities at non-integer coordinates, but doing so in the demo mimics the effect of centerOrigin on odd-dimensioned images, e.g., centering a 3x3 image placed at x = 5, y = 5 results in rendering coordinates of x = 3.5, y = 3.5).

[ReignOfError]

As it appears unlikely that centerOrigin() will be altered, I'm just going to leave this complete demo code here for anyone who might stumble across this phenomenon in the future and take the liberty of closing this issue.

(To clarify, by "phenomenon", I mean the fact that the position of the center pixel of an odd-dimensioned image changes depending on whether or not blending - and therefore copyPixels or draw - is used when rendering.)

testWorld.as

package  
{
    import flash.display.Bitmap;
    import flash.display.BitmapData;
    import flash.display.BlendMode;
    import flash.geom.Matrix;
    import flash.geom.Point;
    import flash.geom.Rectangle;
    import net.flashpunk.FP;
    import net.flashpunk.graphics.Image;
    import net.flashpunk.World;
    import net.flashpunk.utils.Input;

    public class testWorld extends World
    {

        [Embed(source = 'test3x3.png')] // This is just a 3x3 image containing an 'x' shape.
        private const test3x3:Class;
        private const testImage:Image = new Image(test3x3);

        private var bm3:Bitmap = new test3x3();
        private var bmd3:BitmapData = bm3.bitmapData;

        private var useCopyPixels:Boolean = true;

        public function testWorld():void
        {
            testImage.centerOrigin();
        }

        override public function update():void
        {
            if (Input.mousePressed) {
                if (useCopyPixels) {
                    testImage.blend = BlendMode.NORMAL; // testImage will be rendered using BitmapData.draw()
                    useCopyPixels = false;
                }
                else {
                    testImage.blend = null; // testImage will be rendered using BitmapData.copyPixels()
                    useCopyPixels = true;
                }
            }

            super.update();
        }

        override public function render():void
        {
            // Since this image is odd-dimensioned (3x3), its rendering coordinates will be half-pixel values (since 5 - 3/2 = 3.5)
            // When testImage.blend == null, copyPixels is used in Image.render() and the center pixel of the image will be located at (4, 4)
            // When testImage.blend == BlendMode.NORMAL, draw is used in Image.render() and the center pixel of the image will be located at (5, 5)
            testImage.render(FP.buffer, new Point(5, 5), camera);

            // This is included just to demonstrate that the difference between how copyPixels and draw handle half-pixel coordinates doesn't depend on something else in Image.render()
            if (useCopyPixels){
                FP.buffer.copyPixels(bmd3, new Rectangle(0, 0, 3, 3), new Point(0.5, 0.5));
            }
            else {
                FP.buffer.draw(bm3, new Matrix(1, 0, 0, 1, 0.5, 0.5), null, null, null, false); // Note that no blending is used
                //FP.buffer.draw(bmd3, new Matrix(1, 0, 0, 1, 0.5, 0.5), null, null, null, false); // If BitmapData (rather than Bitmap) is used, anti-aliasing will be used (just a side note)
            }

            super.render();
        }

    }

}

Main.as

package 
{
    import net.flashpunk.Engine;
    import net.flashpunk.FP;

    public class Main extends Engine
    {
        public function Main():void
        {
            super(50, 50);
            FP.world = new testWorld();
            FP.screen.scale = 5; // This just makes the effect easier to see; it's otherwise unrelated
        }   
    }   
}