When do I need to set the contentsScale property of a CALayer?

re: layer content via -drawRect: or -drawLayer:inContext:

Normallly or always? and this is valid only for view's hosted backing layer or every layer I add as a sublayer to the backing layer?

Always. When these methods are called, the current context will already have the scaling factor applied. For instance, if your layer is 10pt x 10pt, it has a bounds of {0,0,10,10}, regardless of contentsScale. If the contentsScale = 2 (e.g. you are on retina), this is actually 20x20 pixels. CALayer will have already setup a 20x20px backing store and applied a scale factor CGContextScaleCTM(context, 2, 2).

This is so that you can do your drawing in your 10x10 conceptual space either way, but the backing store is doubled if the pixels are doubled.

I'm having difficulties imagining a layer without a view, I can imagine a hierarchy of layers but as soon as I want to display them I should add it as a subhierachy of the view's backing layer, or do exist some other means to use them (like creating and just renderring in a context)?

You can create them, add them as sublayers, and either set their delegate to an object where you implement -drawLayer:inContext:, or you can directly set the layer's contents. On iOS, UIView is a fairly shallow wrapper around a CALayer so it generally makes sense to create subviews instead of directly making sublayers, which is why you aren't so familiar with this usage. On OS X, a layer-backed NSView is a big and complicated wrapper around a CALayer, so it makes a lot more sense to make whole hierarchies of layers within a single view.

What does that actually mean? When I do something like that layer.contents = (id)image.CGImage I need to set the contentsScale.

Yes. But what this passage in the documentation is telling you is that if you want to not look ugly, a 10pt x 10pt layer with contentsScale of 2, needs contents that are a 20px x 20px image. I.e. You need to pay attention to the contentsScale of the layer when you are directly setting the layer contents if you want to avoid scaling artifacts.

Do I also need to set it when my layer draws it's contents calling the delegate method drawLayer:inContext: and the layer isn't the backing layer of a view?

Yes. If you are creating layers yourself (not created via a UIView), you need to set their scale manually. Usually this is just layer.contentsScale = [[UIScreen mainScreen] scale]. (Again, on OS X this is a little more complicated since screens can come and go while running.)

On OS X you basically

1. grab your window’s -backingScaleFactor
2. set each (!) layer’s -contentsScale to that scaleFactor
3. implement -layer:shouldInheritContentsScale:fromWindow: in a controller
4. set each layer’s -delegate to that controller

I know it’s frowned upon here on SO to just reference an external URL, but it’s hard to describe this. Here is some code that works correctly for me with regard to the scale factors:

https://github.com/JanX2/ScrollingAboutWindow

Hope that helps.

While a layer is almost always used inside a view, the layer may have been created ad-hoc and added as a sublayer of the view's layer, or assigned as another layer's mask. In both instances, the contentsScale property would have to be set. For example:

UIView *myMaskedView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 100, 100)];CALayer *myMaskLayer = [CALayer new];myMaskLayer.frame = myMaskedView.bounds;UIImage *maskImage = [UIImage imageNamed:@"some_image"];myMaskLayer.contents = (id)maskImage.CGImage;myMaskLayer.contentsScale = maskImage.scale;myMaskedView.layer.mask = myMaskLayer;

You may also want to build a hierarchy of layers for performing animations, without using each layer to back a view:

UIView *myView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 100, 100)];CALayer *sublayerA = [CALayer new];sublayerA.contentsScale = myView.layer.contentsScale;[myView.layer addSublayer:sublayerA];CALayer *sublayerB = [CALayer new];sublayerB.contentsScale = myView.layer.contentsScale;[myView.layer addSublayer:sublayerB];// Continue adding layers   

This is especially important for Retina devices, which have a native screen scale of 2.0; a layer with the default scale of 1.0 would display noticeable pixelation.