We have a control which we do our own custom drawing in OnRender. However, we would like to use a PNG with transparency as sort of a stencil for various drawing 'passes' if you will.
Now we already know that we can simply use a PNG in an ImageBrush and set it as the control's OpacityMask, but we actually want to do several drawing passes with several different stencils. If we wanted to go the OpacityMask route, we'd have to create separate controls, separate ImageMasks, then stack them all up on top of each other which also clutters up your visual tree.
We don't want to do that. We want to do all of the drawing in the OnRender override of a single Control subclass. We just want those draw calls to be masked out by an image. We then want to repeat that over and over until our drawing is done.
Any way this can be done?
HA! Found it! Odd that the S/O community has been so quiet on this one, but for those looking for it, it's called DrawingContext.PushOpacityMask (and the corresponding 'Pop()') and does exactly what you think it does... it pushes an opacity mask (via a brush) onto the DC and all subsequent drawing is relative to the brush's opacity values.
You can also layer 'masks' for some pretty cool effects too. They are additive, not just the last one set.
I'm pretty sure the built-in OpacityMask is just used with this function in the OnRender call. What this means is you can still use the OpacityMask (provided you push that on first) then your own mask(s) for your own drawing calls. Pretty neat stuff!
Hope this helps others who were looking for this.