Image Sizes and Filenames

Required Images Sizes, Resolutions and Naming Conventions

PDF for offline use
Sample Code:
Related Articles:
Related SDKs:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-03

This article covers the deprecated technique of using a file naming convention to supply the different version of each file needed to support all iOS devices with the required images sizes and resolutions.

Resolution Independent Images and Image Filenames

⚠️

NOTE: This method of working with images in an iOS app has been deprecated by Apple. The developer should use Asset Catalog Image Sets to manage an app's images instead.

When Apple initially introduced the iPhone and iPod Touch devices, all of the images a developer needed to include in a Xamarin.iOS app only had to support the fixed screen size of 320 x 480 pixels at non-high definition resolutions. As Apple started to introduce iOS devices with higher resolutions and large screen sizes, iOS's Image handling routines were adapted to automatically select the correct version of an image's file for the given hardware that the application was running on based on how the image's file was named.

By decorating the name of an image file with specific keywords or character patterns, multiple copies of the file can be included in the application's bundle and the correct version (based on the device and resolution) would automatically be selected by iOS's image handling routines at runtime - all without developer intervention or code changes.

The following special keywords or character patterns can be used when naming an image file for use in a Xamarin.iOS app:

Keyword or Pattern Definition
@2x Used to define a 2 times, Retina resolution size of a given image file. For example, if Image.png is 320x480 pixels, then Image@2x.png would be used to define a 640x960 pixel version of the same image.
@3x Used to define a 3 times, HD resolution size of a given image file. For example, if Image.png is 414x736 pixels, then Image@3x.png would be used to define a 1242x2208 pixel version of the same image. @3x was added to support the iPhone 6 Plus's higher resolution display.
~iphone Denotes that this version of an image will be used when the Xamarin.iOS application in running on an iPhone or iPod Touch device. For example, if the application bundle included an Image~iPad.png and an Image~iphone.png file, the Image~iphone.png would be used when running on an iPhone device.
~ipad Denotes that this version of an image will be used when the Xamarin.iOS application in running on an iPad device. For example, if the application bundle included an Image~iPhone.png and an Image~ipad.png file, the Image~ipad.png would be used when running on an iPad device.

The keyword or special pattern is included between the file's name and it's extension and multiple keywords or patterns may be included. In code or when setting an image in the iOS Designer, the developer specifies the version of the file without the keyword or pattern. If available, iOS will select the correct version based on the current device the application is running on.

So, given the following versions of an image file included in a Xamarin.iOS application's bundle:

  • Image.png
  • Image~ipad.png
  • Image@2x.png
  • Image@2x~iphone.png
  • Image@3x.png

Calling UIImage.FromFile("Image.png") would do the following on the given iOS device and resolution:

Device/Resolution Action
iPhone/Standard Resolution The Image.png version of the file would be used.
iPad/Standard Resolution The Image~ipad.png version of the file would be used.
iPhone/Retina Resolution The Image@2x~iphone.png version of the file would be used.
iPad/Retina Resolution The Image@2x.png version of the file would be used.
iPhone 6/Retina Resolution The Image@2x~iphone.png version of the file would be used.
iPhone 6 Plus/HD Resolution The Image@3x.png version of the file would be used.

When working with image filenames in a Xamarin.iOS app project, please keep these naming conventions in mind. These should also be considered when designing the app and creating and including the necessary image assets to support the iOS hardware and version that the developer will want the app to run on.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.