iOS Guides

Uploading Images

Note

If you are looking to upload images for use in template graphics, soft buttons, or the menu, you can use the ScreenManager. Other situations, such as VR help lists and turn by turn directions, are not currently covered by the ScreenManager.

You should be aware of these four things when using images in your SDL app:

You may be connected to a head unit that does not have the ability to display images.
You must upload images from your mobile device to the head unit before using them in a template.
Persistent images are stored on a head unit between sessions. Ephemeral images are destroyed when a session ends (i.e. when the user turns off their vehicle).
Images can not be uploaded when the app's hmiLevel is NONE. For more information about permissions, please review Understanding Permissions.

To learn how to use images once they are uploaded, please see Text, Images, and Buttons.

Checking if Graphics are Supported

Before uploading images to a head unit you should first check if the head unit supports graphics. If not, you should avoid uploading unnecessary image data. To check if graphics are supported, check the SDLManager.systemCapabilityManager.defaultMainWindowCapability property once the SDLManager has started successfully.

Objective-C

__weak typeof (self) weakSelf = self;
[self.sdlManager startWithReadyHandler:^(BOOL success, NSError * _Nullable error) {
    if (!success) {
        <#Manager errored while starting up#>
        return;
    }

    SDLWindowCapability *mainWindowCapability = weakSelf.sdlManager.systemCapabilityManager.defaultMainWindowCapability;
    BOOL graphicsSupported = (mainWindowCapability.imageFields.count > 0);
}];

Swift

sdlManager.start { [weak self] (success, error) in
    guard let self = self else { return }

    guard success else {
        <#Manager errored while starting up#>
        return
    }

    let mainWindowCapability = self.sdlManager.systemCapabilityManager.defaultMainWindowCapability
    let graphicsSupported = (mainWindowCapability.count > 0)
}

Uploading an Image Using the File Manager

The SDLFileManager uploads files and keeps track of all the uploaded files names during a session. To send data with the SDLFileManager, you need to create either a SDLFile or SDLArtworkobject. SDLFile objects are created with a local NSURL or NSData; SDLArtwork a UIImage.

Objective-C

UIImage* image = [UIImage imageNamed:@"<#Image Name#>"];
if (!image) {
    <#Error reading from assets#>
    return;
}

SDLArtwork *artwork = [SDLArtwork persistentArtworkWithImage:image asImageFormat:<#SDLArtworkImageFormat#>];

[self.sdlManager.fileManager uploadArtwork:artwork completionHandler:^(BOOL success, NSString * _Nonnull artworkName, NSUInteger bytesAvailable, NSError * _Nullable error) {
    if (error != nil) { return; }
    <#Image Upload Successful#>
    // To send the image as part of a show request, create a SDLImage object using the artworkName
    SDLImage *image = [[SDLImage alloc] initWithName:artworkName isTemplate:<#BOOL#>];
}];

Swift

guard let image = UIImage(named: "<#Image Name#>") else {
    <#Error reading from assets#>
    return
}
let artwork = SDLArtwork(image: image, persistent: <#Bool#>, as: <#SDLArtworkImageFormat#>)

sdlManager.fileManager.upload(artwork: artwork) { (success, artworkName, bytesAvailable, error) in
    guard error == nil else { return }
    <#Image Upload Successful#>
    // To send the image as part of a show request, create a SDLImage object using the artworkName
    let graphic = SDLImage(name: artworkName, isTemplate: <#Bool#>)
}

Batch File Uploads, Persistence, etc.

Similar to other files, artworks can be persistent, batched, overwrite, etc. See Uploading Files for more information.

View on GitHub.com

Previous Section Next Section