Although it is pretty evident that this method does pixel-level hit testing, the documentation is pretty cryptic when it comes to *exactly* how to use the method to perform a specific test. I guess it’s one of those things that you have to figure out by looking at lots of examples. So, here is another example to throw into the mix.
I recently had to work on some code (AS2/F8) to highlight individual lines in a TextField on rollOver. Since no such method exists to do this directly, I approximated using TextField height and font metrics to create a number of ‘highlight’ boxes. One of the questions I had was how to determine if a highlight box was underneath a blank line of text.
Since I’m not directly computing the exact text in a single line, I had no way of knowing if a highlight box was underneath a ‘blank’ line. One way to find out is to take a bitmap snapshot of the TextField (actually, the MovieClip containing the TextField), a snapshot of the rectangle, then do a pixel-level hit test between the two BitmapData objects. This process is encapsulated inside a library method that should be usable in other applications.
Download the AS2/F8 example here. I hope it helps demystify BitmapData.hitTest and perhaps you can find use for this approach in another project.
The Algorithmist 
Excellent. I knew I could rely on you to unravel the hitTest usage. The documentation is pretty obscure, and just wrong even now in the Flex docs:
firstAlphaThreshold:uint — The highest alpha channel value that is considered opaque for this hit test.
That should be LOWest alpha value!
Just one thing though — I think you should dispose the bitmaps before returning from __pixelHitTest.
Yes, it’s a very rough example.
regards,
– jim