Why am I seeing a crash when using most contentsGravity constants in NSView?

Question

I have an NSView subclass and in the initWithFrame method am setting the following:

self.wantsLayer = YES;
self.layer.contents = [NSImage imageNamed:@"sprite-sheet"];
self.layer.contentsGravity = kCAGravityLeft;

and when I run it, I get the expected visual results... and a crash with the following log:

** Misuse of NSImage and CALayer. contentsGravity is left. It should be one of resize, resizeAspect, or resizeAspectFill.

Why? There's no indication in the docs that the other values should not be used.

Answer 1

Actually, the behavior you are seeing is in the documentation. It's just in the NSImage documentation and not the CALayer documentation (emphasis by me):

Using Images with CALayer Objects

Although you can assign an NSImage object directly to the contents property of a CALayer object, doing so may not always yield the best results. Instead of using your image object, you can use the layerContentsForContentsScale: method to obtain an object that you can use for your layer’s contents. That method creates an image that is suited for use as the contents of a layer and that is supports all of the layer’s gravity modes. By contrast, the NSImage class supports only the kCAGravityResize, kCAGravityResizeAspect, and kCAGravityResizeAspectFill modes.