How do NSBundle pathForResource:ofType: and UIImage imageWithContentsOfFile: handle scale and device modifiers?

Question

In my iOS resource folder, I have the images:

foo~iphone.png
foo@2x~iphone.png
foo~ipad.png
foo@2x~ipad.png

I load them with:

NSString *fileName = [[NSBundle mainBundle] pathForResource:@"foo" ofType:@"png"];
UIImage *image = [UIImage imageWithContentsOfFile:fileName];

Experimentally:

On the iPhone, filename is /path/to/bundle/foo~iphone.png, and on the retina iPhone, it loads the @2x version.

On the iPad, filename is /path/to/bundle/foo~ipad.png, and on the retina iPad, it loads the @2x version.

That is, it loads the image I'd hope, but pathForResource handles the device modifier, and imageWithContentsOfFile handles the scale modifier.

I'd like to know why. The documentation of pathForResource says nothing about device modifiers, and the documentation of imageWithContentsOfFile says nothing about scale modifiers.

Is there separate documentation that indicates precisely what each function does?

Answer 1

The explanation for imageWithContentsOfFile is in related documentation, not in the UIImage documentation itself:

On devices with high-resolution screens, the imageNamed:, imageWithContentsOfFile:, and initWithContentsOfFile: methods automatically looks for a version of the requested image with the @2x modifier in its name. If it finds one, it loads that image instead. If you do not provide a high-resolution version of a given image, the image object still loads a standard-resolution image (if one exists) and scales it during drawing.

When it loads an image, a UIImage object automatically sets the size and scale properties to appropriate values based on the suffix of the image file. For standard resolution images, it sets the scale property to 1.0 and sets the size of the image to the image’s pixel dimensions. For images with the @2x suffix in the filename, it sets the scale property to 2.0 and halves the width and height values to compensate for the scale factor. These halved values correlate correctly to the point-based dimensions you need to use in the logical coordinate space to render the image."

I don't know which documentation explains the behavior of pathForResource.