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

Question

In the documentation Apple states that you need to consider the scale factor of a layer when it:

• Creates additional Core Animation layers with different scale factors and composites them into its own content
• Sets the contents property of a Core Animation layer directly

The last statement is not totally clear to me. They also say:

Applications that use Core Animation layers directly to provide content may need to adjust their drawing code to account for scale factors. Normally, when you draw in your view’s drawRect: method, or in the drawLayer:inContext: method of the layer’s delegate, the system automatically adjusts the graphics context to account for scale factors.

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? because they also say:

If your application creates layers without an associated view, each new layer object’s scale factor is set to 1.0 initially. If you do not change that scale factor, and if you subsequently draw the layer on a high-resolution screen, the layer’s contents are scaled automatically to compensate for the difference in scale factors. If you do not want the contents to be scaled, you can change the layer’s scale factor to 2.0, but if you do so without providing high-resolution content, your existing content may appear smaller than you were expecting. To fix that problem, you need to provide higher-resolution content for your layer.

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)?

Core Animation’s compositing engine looks at the contentsScale property of each layer to determine whether the contents of that layer need to be scaled during compositing. If your application creates layers without an associated view, each new layer object’s scale factor is set to 1.0 initially. If you do not change that scale factor, and if you subsequently draw the layer on a high-resolution screen, the layer’s contents are scaled automatically to compensate for the difference in scale factors. If you do not want the contents to be scaled, you can change the layer’s scale factor to 2.0, but if you do so without providing high-resolution content, your existing content may appear smaller than you were expecting. To fix that problem, you need to provide higher-resolution content for your layer.

What does that actually mean? When I do something like that layer.contents = (id)image.CGImage I need to set the contentsScale.
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?

Answer 1

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.)

Answer 2

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.

Answer 3

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.