http://developer.apple.com/library/ios/documentation/DataManagement/Conceptual/DocumentBasedAppPGiOS/DocumentBasedAppPGiOS.pdf

Apple-TV_2nd_gen_Setup_Guide.pdf-manuel

Apple-Archives-and-Serializations-Programming-manuel

Apple-SafariWebContent.pdf-Guide-manuel

Apple-iTunes_ExtrasandiTunes_LPTestGuide1.1.pdf-manuel

Apple-Text-System-User-Interface-Layer-Programming-manuel

Apple-CocoaTextArchitecture.pdf-manuel

Apple-Key-Value-Observing-Programming-Guide-manuel

Apple-Location-Awareness-Programming-Guide-manuel

Apple-SharkUserGuide.pdf-manuel

Apple-drawingprintingios.pdf-manuel

Apple-QuickTime7_User_Guide.pdf-manuel

Apple-Event-Handling-Guide-for-iOS-manuel

Apple-ipod_nano_3rd_gen_features_guide.pdf-manuel

Apple-iTunes_VideoandAudio_Asset_Guide5.0.pdf-manuel

Apple-ARD3_AdminGuide.pdf-manuel

Apple-SafariWebContent.pdf-Guide-manue

Apple-iphone_3gs_finger_tips.pdf-manuel

Apple-InstrumentsUserGuide.pdf-manuel

Apple-Logic-Pro-9-TDM-Guide-manuel

Apple-macbook_air_users_guide.pdf-manuel

Apple-macbook_air-13-inch_mid-2012-qs_ta.pdf-manuel

Apple-AppStoreMarketingGuidelines-JP.pdf-Japon-manuel

Apple-macbook_pro_retina_qs_ta.pdf-manuel

Apple-ipad_user_guide_tu.pdf-manuel

Apple-ipad_user_guide_th.pdf-manuel

Apple-iphone_user_guide_gr.pdf-manuel

Apple-Nike_Plus_iPod_Sensor_UG_2A.pdf-manuel

Apple-ipad_manual_del_usuario.pdf-manuel

Apple-ipad_uzivatelska_prirucka.pdf-manuel

Apple-ipad_wifi_informations_importantes.pdf-manuel

Apple-Xsan_2_Admin_Guide_v2.3.pdf-manuel

Apple-macbook_pro-13-inch-late-2012-quick_start.pdf-manuel

Apple-CocoaDrawingGuide.pdf-manuel

Apple-Cryptographic-Services-Guide-manuel

Apple-Resource-Programming-Guide-manuel

AppleSafariVisualEffectsProgGuide.pdf-manuel

/Apple-WorkingWithUSB.pdf-manuel

Apple-macbook_pro-retina-mid-2012-important_product_info_f.pdf-manuel

Apple-iOS_Security_May12.pdf-manue

Apple-Mac-Pro-2008-Performance-and-Productivity-for-Creative-Pros

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-KernelProgramming.pdf-manuel

Apple-Core-Data-Model-Versioning-and-Data-Migration-Programming-Guide-manuel

Apple-RED_Workflows_with_Final_Cut_Pro_X.pdf-manuel

Apple-Transitioning-to-ARC-Release-Notes-manuel

Apple-iTunes-Connect-Sales-and-Trends-Guide-manuel

Apple-App-Sandbox-Design-Guide-manuel

Apple-String-Programming-Guide-manuel

Apple-Secure-Coding-Guide-manuel

Apple_AirPort_Networks_Early2009.pdf-manuel

Apple-TimeCapsule_SetupGuide_TA.pdf-manuel

Apple-time_capsule_4th_gen_setup.pdf-manuel

Apple-TimeCapsule_SetupGuide.pdf-manuel

Apple-TimeCapsule_SetupGuide_CH.pdf-Chinois-manuel

Apple-CodeSigningGuide.pdf-manuel

Apple-ViewControllerPGforiOS.pdf-manuel

Apple-KeyValueObserving.pdf-manuel

Apple-mac_mini-late-2012-quick_start.pdf-manuel

Apple-OS-X-Mountain-Lion-Core-Technologies-Overview-June-2012-manuel

Apple-OS-X-Server-Product-Overview-June-2012-manuel

Apple-Apple_Server_Diagnostics_UG_109.pdf-manuel

Apple-PackageMaker_UserGuide.pdf-manuel

Apple-InstrumentsUserGuide.pdf-manuel

Apple-Logic-Pro-9-TDM-Guide-manuel

Apple-macbook_air_users_guide.pdf-manuel

Apple-macbook_air-13-inch_mid-2012-qs_ta.pdf-manuel

Apple-AppStoreMarketingGuidelines-JP.pdf-Japon-manuel

Apple-macbook_pro_retina_qs_ta.pdf-manuel

Apple-ipad_user_guide_tu.pdf-manuel

Apple-ipad_user_guide_th.pdf-manuel

Apple-iphone_user_guide_gr.pdf-manuel

Apple-Nike_Plus_iPod_Sensor_UG_2A.pdf-manuel

Apple-ipad_manual_del_usuario.pdf-manuel

Apple-ipad_uzivatelska_prirucka.pdf-manuel

Apple-ipad_wifi_informations_importantes.pdf-manuel

Apple-Xsan_2_Admin_Guide_v2.3.pdf-manuel

Apple-macbook_pro-13-inch-late-2012-quick_start.pdf-manuel

Apple-CocoaDrawingGuide.pdf-manuel

Apple-Cryptographic-Services-Guide-manuel

Apple-Resource-Programming-Guide-manuel

AppleSafariVisualEffectsProgGuide.pdf-manuel

/Apple-WorkingWithUSB.pdf-manuel

Apple-macbook_pro-retina-mid-2012-important_product_info_f.pdf-manuel

Apple-iOS_Security_May12.pdf-manue

Apple-Mac-Pro-2008-Performance-and-Productivity-for-Creative-Pros

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-KernelProgramming.pdf-manuel

Apple-Core-Data-Model-Versioning-and-Data-Migration-Programming-Guide-manuel

Apple-RED_Workflows_with_Final_Cut_Pro_X.pdf-manuel

Apple-Transitioning-to-ARC-Release-Notes-manuel

Apple-iTunes-Connect-Sales-and-Trends-Guide-manuel

Apple-App-Sandbox-Design-Guide-manuel

Apple-String-Programming-Guide-manuel

Apple-Secure-Coding-Guide-manuel

Apple_AirPort_Networks_Early2009.pdf-manuel

Apple-TimeCapsule_SetupGuide_TA.pdf-manuel

Apple-time_capsule_4th_gen_setup.pdf-manuel

Apple-TimeCapsule_SetupGuide.pdf-manuel

Apple-TimeCapsule_SetupGuide_CH.pdf-Chinois-manuel

Apple-CodeSigningGuide.pdf-manuel

Apple-ViewControllerPGforiOS.pdf-manuel

Apple-KeyValueObserving.pdf-manuel

Apple-mac_mini-late-2012-quick_start.pdf-manuel

Apple-OS-X-Mountain-Lion-Core-Technologies-Overview-June-2012-manuel

Apple-OS-X-Server-Product-Overview-June-2012-manuel

Apple-Apple_Server_Diagnostics_UG_109.pdf-manuel

Apple-PackageMaker_UserGuide.pdf-manuel

Apple-Instrumentos_y_efectos_de_Logic_Studio.pdf-Manuel

Apple-ipod_nano_kayttoopas.pdf-Finlande-Manuel

Apple_ProRes_White_Paper_October_2012.pdf-Manuel

Apple-wp_osx_configuration_profiles.pdf-Manuel

Apple-UsingiTunesProducerFreeBooks.pdf-Manuel

Apple-ipad_manual_do_usuario.pdf-Portugais-Manuel

Apple-Instruments_et_effets_Logic_Studio.pdf-Manuel

Apple-ipod_touch_gebruikershandleiding.pdf-Neerlandais-Manuel

AppleiPod_shuffle_4thgen_Manual_del_usuario.pdf-Espagnol-Manuel

Apple-Premiers-contacts-avec-votre-PowerBook-G4-Manuel

Apple_Composite_AV_Cable.pdf-Manuel

Apple-iPod_shuffle_3rdGen_UG_DK.pdf-Danemark-Manuel

Apple-iPod_classic_160GB_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-VoiceOver_GettingStarted-Manuel

Apple-iPod_touch_2.2_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-Apple_TV_Opstillingsvejledning.pdf-Allemand-Manuel

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-iphone_prirucka_uzivatela.pdf-Manuel

Apple-Aan-de-slag-Neerlandais-Manuel

Apple-airmac_express-80211n-2nd-gen_setup_guide.pdf-Thailande-Manuel

Apple-ipod_nano_benutzerhandbuch.pdf-Allemand-Manuel

Apple-aperture3.4_101.pdf-Manuel

Apple-Pages09_Anvandarhandbok.pdf-Manuel

Apple-nike_plus_ipod_sensor_ug_la.pdf-Mexique-Manuel

Apple-ResEdit-Reference-For-ResEdit02.1-Manuel

Apple-ipad_guide_de_l_utilisateur.pdf-Manuel

Apple-Compressor-4-Benutzerhandbuch-Allemand-Manuel

Apple-AirPort_Networks_Early2009_DK.pdf-Danemark-Manuel

Apple-MacBook_Pro_Mid2007_2.4_2.2GHz_F.pdf-Manuel

Apple-MacBook_13inch_Mid2010_UG_F.pdf-Manuel

Apple-Xserve-RAID-Presentation-technologique-Janvier-2004-Manuel

Apple-MacBook_Pro_15inch_Mid2010_F.pdf-Manuel

Apple-AirPort_Express-opstillingsvejledning.pdf-Danemark-Manuel

Apple-DEiPod_photo_Benutzerhandbuch_DE0190269.pdf-Allemand-Manuel

Apple-Final-Cut-Pro-X-Logic-Effects-Reference-Manuel

Apple-iPod_touch_2.1_Brugerhandbog.pdf-Danemark-Manuel

Apple-Remote-Desktop-Administratorhandbuch-Version-3.1-Allemand-Manuel

Apple-Qmaster-4-User-Manual-Manuel

Apple-Server_Administration_v10.5.pdf-Manuel

Apple-ipod_classic_features_guide.pdf-Manuel

Apple-Lecteur-Optique-Manuel

Apple-Carte-AirPort-Manuel

Apple-iPhone_Finger_Tips_Guide.pdf-Anglais-Manuel

Apple-Couvercle-Manuel

Apple-battery.cube.pdf-Manuel

Apple-Boitier-de-l-ordinateur-Manuel

Apple-Pile-Interne-Manuel

Apple-atacable.pdf-Manuel

Apple-videocard.pdf-Manuel

Apple-Guide_de_configuration_de_l_Airport_Express_5.1.pdf-Manuel

Apple-iMac_Mid2010_UG_F.pdf-Manuel

Apple-MacBook_13inch_Mid2009_F.pdf-Manuel

Apple-MacBook_Mid2007_UserGuide.F.pdf-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Administration_de_QuickTime_Streaming_et_Broadcasting_10.5.pdf-Manuel

Apple-Opstillingsvejledning_til_TimeCapsule.pdf-Danemark-Manuel

Apple-iPod_nano_5th_gen_Benutzerhandbuch.pdf-Manuel

Apple-iOS_Business.pdf-Manuel

Apple-AirPort_Extreme_Installationshandbuch.pdf-Manuel

Apple-Final_Cut_Express_4_Installation_de_votre_logiciel.pdf-Manuel

Apple-MacBook_Pro_15inch_2.53GHz_Mid2009.pdf-Manuel

Apple-Network_Services.pdf-Manuel

Apple-Aperture_Performing_Adjustments_f.pdf-Manuel

Apple-Supplement_au_guide_Premiers_contacts.pdf-Manuel

Apple-Administration_des_images_systeme_et_de_la_mise_a_jour_de_logiciels_10.5.pdf-Manuel

Apple-Mac_OSX_Server_v10.6_Premiers_contacts.pdf-Francais-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Mise_a_niveau_et_migration_v10.5.pdf-Manue

Apple-MacBookPro_Late_2007_2.4_2.2GHz_F.pdf-Manuel

Apple-Mac_mini_Late2009_SL_Server_F.pdf-Manuel

Apple-Mac_OS_X_Server_10.5_Premiers_contacts.pdf-Manuel

Apple-iPod_touch_2.0_Guide_de_l_utilisateur_CA.pdf-Manuel

Apple-MacBook_Pro_17inch_Mid2010_F.pdf-Manuel

Apple-Comment_demarrer_Leopard.pdf-Manuel

Apple-iPod_2ndGen_USB_Power_Adapter-FR.pdf-Manuel

Apple-Feuille_de_operations_10.4.pdf-Manuel

Apple-Time_Capsule_Installationshandbuch.pdf-Allemand-Manuel

Apple-F034-2262AXerve-grappe.pdf-Manuel

Apple-Mac_Pro_Early2009_4707_UG_F

Apple-imacg5_17inch_Power_Supply

Apple-Logic_Studio_Installieren_Ihrer_Software_Retail

Apple-IntroductionXserve1.0.1

Apple-Aperture_Getting_Started_d.pdf-Allemand

Apple-getting_started_with_passbook

Apple-iPod_mini_2nd_Gen_UserGuide.pdf-Anglais

Apple-Deploiement-d-iPhone-et-d-iPad-Reseaux-prives-virtuels

Apple-F034-2262AXerve-grappe

Apple-Mac_OS_X_Server_Glossaire_10.5

Apple-FRLogic_Pro_7_Guide_TDM

Apple-iphone_bluetooth_headset_userguide

Apple-Administration_des_services_reseau_10.5

Apple-imacg5_17inch_harddrive

Apple-iPod_nano_4th_gen_Manuale_utente

Apple-iBook-G4-Getting-Started

Apple-XsanGettingStarted

Apple-Mac_mini_UG-Early2006

Apple-Guide_des_fonctionnalites_de_l_iPod_classic

Apple-Guide_de_configuration_d_Xsan_2

Apple-MacBook_Late2006_UsersGuide

Apple-sur-Fnac.com

Apple-Mac_mini_Mid2010_User_Guide_F.pdf-Francais

Apple-PowerBookG3UserManual.PDF.Anglais

Apple-Installation_de_votre_logiciel_Logic_Studio_Retail

Apple-Pages-Guide-de-l-utilisateur

Apple-MacBook_Pro_13inch_Mid2009.pdf.Anglais

Apple-MacBook_Pro_15inch_Mid2009

Apple-Installation_de_votre_logiciel_Logic_Studio_Upgrade

Apple-FRLogic_Pro_7_Guide_TDM

Apple-airportextreme_802.11n_userguide

Apple-iPod_shuffle_3rdGen_UG

Apple-iPod_classic_160GB_User_Guide

Apple-iPod_nano_5th_gen_UserGuide

Apple-ipod_touch_features_guide

Apple-Wireless_Mighty_Mouse_UG

Apple-Advanced-Memory-Management-Programming-Guide

Apple-iOS-App-Programming-Guide

Apple-Concurrency-Programming-Guide

Apple-MainStage-2-User-Manual-Anglais

Apple-iMacG3_2002MultilingualUserGuide

Apple-iBookG3_DualUSBUserGuideMultilingual.PDF.Anglais

Apple-imacG5_20inch_AirPort

Apple-Guide_de_l_utilisateur_de_Mac_Pro_Early_2008

Apple-Installation_de_votre_logiciel_Logic_Express_8

Apple-iMac_Guide_de_l_utilisateur_Mid2007

Apple-imacg5_20inch_OpticalDrive

Apple-FCP6_Formats_de_diffusion_et_formats_HD

Apple-prise_en_charge_des_surfaces_de_controle_logic_pro_8

Apple-Aperture_Quick_Reference_f

Apple-Shake_4_User_Manual

Apple-aluminumAppleKeyboard_wireless2007_UserGuide

Apple-ipod_shuffle_features_guide

Apple-Color-User-Manual

Apple-XsanGettingStarted

Apple-Migration_10.4_2e_Ed

Apple-MacBook_Air_SuperDrive

Apple-MacBook_Late2007-f

ApplePowerMacG5_(Early_2005)_UserGuide

Apple-iSightUserGuide

Apple-MacBook_Pro_Early_2008_Guide_de_l_utilisateur

Apple-Nouvelles-fonctionnalites-aperture-1.5

Apple-premiers_contacts_2e_ed_10.4.pdf-Mac-OS-X-Server

Apple-premiers_contacts_2e_ed_10.4

Apple-eMac_2005UserGuide

Apple-imacg5_20inch_Inverter

Apple-Keynote2_UserGuide.pdf-Japon

Apple-Welcome_to_Tiger.pdf-Japon

Apple-XsanAdminGuide_j.pdf-Japon

Apple-PowerBookG4_UG_15GE.PDF-Japon

Apple-Xsan_Migration.pdf-Japon

Apple-Xserve_Intel_DIY_TopCover_JA.pdf-Japon

Apple-iPod_nano_6thgen_User_Guide_J.pdf-Japon

Apple-Aperture_Photography_Fundamentals.pdf-Japon

Apple-nikeipod_users_guide.pdf-Japon

Apple-QuickTime71_UsersGuide.pdf-Japon

Apple-iMacG5_iSight_UG.pdf-Japon

Apple-Aperture_Performing_Adjustments_j.pdf-Japon

Apple-iMacG5_17inch_HardDrive.pdf-Japon

Apple-iPod_shuffle_Features_Guide_J.pdf-Japon

Apple-MacBook_Air_User_Guide.pdf-Japon

Apple-MacBook_UsersGuide.pdf-Japon

Apple-iPad_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-Apple_AirPort_Networks_Early2009_H.pd-Norge-Norvege

Apple-iPod_classic_120GB_no.pdf-Norge-Norvege

Apple-StoreKitGuide.pdf-Japon

Apple-Xserve_Intel_DIY_ExpansionCardRiser_JA.pdf-Japon

Apple-iMacG5_Battery.pdf-Japon

Apple-Logic_Pro_8_Getting_Started.pdf-Japon

Apple-PowerBook-handbok-Norge-Norveg

Apple-iWork09_formler_og_funksjoner.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacPro_HardDrive_DIY.pdf-Japon

Apple-iPod_Fifth_Gen_Funksjonsoversikt.pdf-Norge-Norvege

Apple-MacBook_13inch_white_Early2009_H.pdf-Norge-Norvege

Apple-GarageBand_09_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2009_H.pdf-Norge-Norvege

Apple-imac_mid2011_ug_h.pdf-Norge-Norvege

Apple-iDVD_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iMac_Mid2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_13inch_Mid2009_H.pdf-Norge-Norvege

/Apple-iPhone_3G_Viktig_produktinformasjon_H-Norge-Norvege

Apple-MacBook_13inch_Mid2010_UG_H.pdf-Norge-Norvege

Apple-macbook_air_13inch_mid2011_ug_no.pdf-Norge-Norvege

Apple-Mac_mini_Early2009_UG_H.pdf-Norge-Norvege

Apple-ipad2_brukerhandbok.pdf-Norge-Norvege

Apple-iPhoto_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_Brukerhandbok_Late2008.pdf-Norge-Norvege

Apple-Pages09_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_13inch_Late2009_UG_H.pdf-Norge-Norvege

Apple-iPhone_3GS_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple-MacBook_13inch_Aluminum_Late2008_H.pdf-Norge-Norvege

Apple-Wireless_Keyboard_Aluminum_2007_H-Norge-Norvege

Apple-NiPod_photo_Brukerhandbok_N0190269.pdf-Norge-Norvege

Apple-MacBook_Pro_13inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacBook_Pro_17inch_Mid2010_H.pdf-Norge-Norvege

Apple-Velkommen_til_Snow_Leopard.pdf-Norge-Norvege.htm

Apple-TimeCapsule_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iPhone_3GS_Hurtigstart.pdf-Norge-Norvege

Apple-Snow_Leopard_Installeringsinstruksjoner.pdf-Norge-Norvege

Apple-iMacG5_iSight_UG.pdf-Norge-Norvege

Apple-iPod_Handbok_S0342141.pdf-Norge-Norvege

Apple-ipad_brukerhandbok.pdf-Norge-Norvege

Apple-GE_Money_Bank_Handlekonto.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iPod_nano_6thgen_Brukerhandbok.pdf-Norge-Norvege

Apple-iPod_touch_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_Air_13inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Early2011_H.pdf-Norge-Norvege

Apple-Numbers09_Brukerhandbok.pdf-Norge-Norvege

Apple-Welcome_to_Leopard.pdf-Japon

Apple-PowerMacG5_UserGuide.pdf-Norge-Norvege

Apple-iPod_touch_2.1_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering-klargjoring.pdf-Norge-Norvege

Apple-MacOSX10.3_Welcome.pdf-Norge-Norvege

Apple-iPod_shuffle_3rdGen_UG_H.pdf-Norge-Norvege

Apple-iPhone_4_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple_TV_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iMovie_08_Komme_i_gang.pdf-Norge-Norvege

Apple-iPod_classic_160GB_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering_10.6.pdf-Norge-Norvege

Apple-Network-Services-Location-Manager-Veiledning-for-nettverksadministratorer-Norge-Norvege

Apple-iOS_Business_Mar12_FR.pdf

Apple-PCIDualAttachedFDDICard.pdf

Apple-Aperture_Installing_Your_Software_f.pdf

Apple-User_Management_Admin_v10.4.pdf

Apple-Compressor-4-ユーザーズマニュアル Japon

Apple-Network_Services_v10.4.pdf

Apple-iPod_2ndGen_USB_Power_Adapter-DE

Apple-Mail_Service_v10.4.pdf

Apple-AirPort_Express_Opstillingsvejledning_5.1.pdf

Apple-MagSafe_Airline_Adapter.pdf

Apple-L-Apple-Multiple-Scan-20-Display

Apple-Administration_du_service_de_messagerie_10.5.pdf

Apple-System_Image_Admin.pdf

Apple-iMac_Intel-based_Late2006.pdf-Japon

Apple-iPhone_3GS_Finger_Tips_J.pdf-Japon

Apple-Power-Mac-G4-Mirrored-Drive-Doors-Japon

Apple-AirMac-カード取り付け手順-Japon

Apple-iPhone開発ガイド-Japon

Apple-atadrive_pmg4mdd.j.pdf-Japon

Apple-iPod_touch_2.2_User_Guide_J.pdf-Japon

Apple-Mac_OS_X_Server_v10.2.pdf

Apple-AppleCare_Protection_Plan_for_Apple_TV.pdf

Apple_Component_AV_Cable.pdf

Apple-DVD_Studio_Pro_4_Installation_de_votre_logiciel

Apple-Windows_Services

Apple-Motion_3_New_Features_F

Apple-g4mdd-fw800-lowerfan

Apple-MacOSX10.3_Welcome

Apple-Print_Service

Apple-Xserve_Setup_Guide_F

Apple-PowerBookG4_17inch1.67GHzUG

Apple-iMac_Intel-based_Late2006

Apple-Installation_de_votre_logiciel

Apple-guide_des_fonctions_de_l_iPod_nano

Apple-Administration_de_serveur_v10.5

Apple-Mac-OS-X-Server-Premiers-contacts-Pour-la-version-10.3-ou-ulterieure

Apple-boot_camp_install-setup

Apple-iBookG3_14inchUserGuideMultilingual

Apple-mac_pro_server_mid2010_ug_f

Apple-Motion_Supplemental_Documentation

Apple-imac_mid2011_ug_f

Apple-iphone_guide_de_l_utilisateur

Apple-macbook_air_11inch_mid2011_ug_fr

Apple-NouvellesfonctionnalitesdeLogicExpress7.2

Apple-QT_Streaming_Server

Apple-Web_Technologies_Admin

Apple-Mac_Pro_Early2009_4707_UG

Apple-guide_de_l_utilisateur_de_Numbers08

Apple-Decouverte_d_Aperture_2

Apple-Guide_de_configuration_et_d'administration

Apple-mac_integration_basics_fr_106.

Apple-iPod_shuffle_4thgen_Guide_de_l_utilisateur

Apple-ARA_Japan

Apple-081811_APP_iPhone_Japanese_v5.4.pdf-Japan

Apple-Recycle_Contract120919.pdf-Japan

Apple-World_Travel_Adapter_Kit_UG

Apple-iPod_nano_6thgen_User_Guide

Apple-RemoteSupportJP

Apple-Mac_mini_Early2009_UG_F.pdf-Manuel-de-l-utilisateur

Apple-Compressor_3_Batch_Monitor_User_Manual_F.pdf-Manuel-de-l-utilisateur

Apple-Premiers__contacts_avec_iDVD_08

Apple-Mac_mini_Intel_User_Guide.pdf

Apple-Prise_en_charge_des_surfaces_de_controle_Logic_Express_8

Apple-mac_integration_basics_fr_107.pdf

Apple-Final-Cut-Pro-7-Niveau-1-Guide-de-preparation-a-l-examen

Apple-Logic9-examen-prep-fr.pdf-Logic-Pro-9-Niveau-1-Guide-de-preparation-a-l-examen

Apple-aperture_photography_fundamentals.pdf-Manuel-de-l-utilisateu

Apple-emac-memory.pdf-Manuel-de-l-utilisateur

Apple-Apple-Installation-et-configuration-de-votre-Power-Mac-G4

Apple-Guide_de_l_administrateur_d_Xsan_2.pdf

Apple-premiers_contacts_avec_imovie6.pdf

Apple-Tiger_Guide_Installation_et_de_configuration.pdf

Apple-Final-Cut-Pro-7-Level-One-Exam-Preparation-Guide-and-Practice-Exam

Apple-Open_Directory.pdf

Apple-Nike_+_iPod_User_guide

Apple-ard_admin_guide_2.2_fr.pdf

Apple-systemoverviewj.pdf-Japon

Apple-Xserve_TO_J070411.pdf-Japon

Apple-Mac_Pro_User_Guide.pdf

Apple-iMacG5_iSight_UG.pdf

Apple-premiers_contacts_avec_iwork_08.pdf

Apple-services_de_collaboration_2e_ed_10.4.pdf

Apple-iPhone_Bluetooth_Headset_Benutzerhandbuch.pdf

Apple-Guide_de_l_utilisateur_de_Keynote08.pdf

APPLE/Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-iPod_shuffle_3rdGen_UG_F.pdf

Apple-iPod_classic_160Go_Guide_de_l_utilisateur.pdf

Apple-iBookG4GettingStarted.pdf

Apple-Administration_de_technologies_web_10.5.pdf

Apple-Compressor-4-User-Manual-fr

Apple-MainStage-User-Manual-fr.pdf

Apple-Logic_Pro_8.0_lbn_j.pdf

Apple-PowerBookG4_15inch1.67-1.5GHzUserGuide.pdf

Apple-MacBook_Pro_15inch_Mid2010_CH.pdf

Apple-LED_Cinema_Display_27-inch_UG.pdf

Apple-MacBook_Pro_15inch_Mid2009_RS.pdf

Apple-macbook_pro_13inch_early2011_f.pdf

Apple-iMac_Mid2010_UG_BR.pdf

Apple-iMac_Late2009_UG_J.pdf

Apple-iphone_user_guide-For-iOS-6-Software

Apple-iDVD5_Getting_Started.pdf

Apple-guide_des_fonctionnalites_de_l_ipod_touch.pdf

Apple_iPod_touch_User_Guide

Apple_macbook_pro_13inch_early2011_f

Apple_Guide_de_l_utilisateur_d_Utilitaire_RAID

Apple_Time_Capsule_Early2009_Setup_F

Apple_iphone_4s_finger_tips_guide_rs

Apple_iphone_upute_za_uporabu

Apple_ipad_user_guide_ta

Apple_iPod_touch_User_Guide

apple_earpods_user_guide

apple_iphone_gebruikershandleiding

apple_iphone_5_info

apple_iphone_brukerhandbok

apple_apple_tv_3rd_gen_setup_tw

apple_macbook_pro-retina-mid-2012-important_product_info_ch

apple_Macintosh-User-s-Guide-for-Macintosh-PowerBook-145

Apple_ipod_touch_user_guide_ta

Apple_TV_2nd_gen_Setup_Guide_h

Apple_ipod_touch_manual_del_usuario

Apple_iphone_4s_finger_tips_guide_tu

Apple_macbook_pro_retina_qs_th

Apple-Manuel_de_l'utilisateur_de_Final_Cut_Server

Apple-iMac_G5_de_lutilisateur

Apple-Cinema_Tools_4.0_User_Manual_F

Apple-Personal-LaserWriter300-User-s-Guide

Apple-QuickTake-100-User-s-Guide-for-Macintosh

Apple-User-s-Guide-Macintosh-LC-630-DOS-Compatible

Apple-iPhone_iOS3.1_User_Guide

Apple-iphone_4s_important_product_information_guide

Apple-iPod_shuffle_Features_Guide_F

Liste-documentation-apple

Apple-Premiers_contacts_avec_iMovie_08

Apple-macbook_pro-retina-mid-2012-important_product_info_br

Apple-macbook_pro-13-inch-mid-2012-important_product_info

Apple-macbook_air-11-inch_mid-2012-qs_br

Apple-Manuel_de_l_utilisateur_de_MainStage

Apple-Compressor_3_User_Manual_F

Apple-Color_1.0_User_Manual_F

Apple-guide_de_configuration_airport_express_4.2

Apple-TimeCapsule_SetupGuide

Apple-Instruments_et_effets_Logic_Express_8

Apple-Manuel_de_l_utilisateur_de_WaveBurner

Apple-Macmini_Guide_de_l'utilisateur

Apple-PowerMacG5_UserGuide

Disque dur, ATA parallèle Instructions de remplacement

Apple-final_cut_pro_x_logic_effects_ref_f

Apple-Leopard_Installationshandbok

Manuale Utente PowerBookG4

Apple-thunderbolt_display_getting_started_1e

Apple-Compressor-4-Benutzerhandbuch

Apple-macbook_air_11inch_mid2011_ug

Apple-macbook_air-mid-2012-important_product_info_j

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-Manuel_de_l_utilisateur_d_Utilitaire_de_reponse_d_impulsion

Apple-Aperture_2_Raccourcis_clavier

AppleTV_Setup-Guide

Apple-livetype_2_user_manual_f

Apple-imacG5_17inch_harddrive

Apple-macbook_air_guide_de_l_utilisateur

Apple-MacBook_Early_2008_Guide_de_l_utilisateur

Apple-Keynote-2-Guide-de-l-utilisateur

Apple-PowerBook-User-s-Guide-for-PowerBook-computers

Apple-Macintosh-Performa-User-s-Guide-5200CD-and-5300CD

Apple-Macintosh-Performa-User-s-Guide

Apple-Workgroup-Server-Guide

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPad-User-Guide-For-iOS-5-1-Software

Apple-Boot-Camp-Guide-d-installation-et-de-configuration

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Guide de l’utilisateur ipad Pour le logiciel iOS 5.1

PowerBook G4 Premiers Contacts APPLE

Guide de l'Utilisateur iphone pour le logiciel ios 5.1 APPLE

Guide de l’utilisateur ipad Pour le logiciel iOS 4,3

Guide de l’utilisateur iPod nano 5ème génération

Guide de l'utilisateur iPod Touch 2.2 APPLE

Guide de l’utilisateur QuickTime 7  Mac OS X 10.3.9 et ultérieur Windows XP et Windows 2000

Guide de l'utilisateur MacBook 13 pouces Mi 2010

Guide de l’utilisateur iPhone (Pour les logiciels iOS 4.2 et 4.3)

Guide-de-l-utilisateur-iPod-touch-pour-le-logiciel-ios-4-3-APPLE

Guide-de-l-utilisateur-iPad-2-pour-le-logiciel-ios-4-3-APPLE

Guide de déploiement en entreprise iPhone OS

Guide-de-l-administrateur-Apple-Remote-Desktop-3-1

Guide-de-l-utilisateur-Apple-Xserve-Diagnostics-Version-3X103

Guide-de-configuration-AirPort-Extreme-802.11n-5e-Generation

Guide-de-configuration-AirPort-Extreme-802-11n-5e-Generation

Guide-de-l-utilisateur-Capteur-Nike-iPod

Guide-de-l-utilisateur-iMac-21-5-pouces-et-27-pouces-mi-2011-APPLE

Guide-de-l-utilisateur-Apple-Qadministrator-4

Guide-d-installation-Apple-TV-3-eme-generation

User-Guide-iPad-For-ios-5-1-Software

Document-Based App Programming Guide for iOSContents About Document-Based Applications in iOS 6 At a Glance 7 Document Objects Are Model Controllers 7 When Designing an Application, Consider Document-Data Format and Other Issues 7 Creating a Subclass of UIDocument Requires Two Method Overrides 7 An Application Manages a Document Through Its Life Cycle 7 An Application Stores Document Files in iCloud Upon User Request 8 An Application Ensures That Document Data is Saved Automatically 8 An Application Resolves Conflicts Between Different Document Versions 8 How to Use This Document 8 Prerequisites 9 See Also 9 Designing a Document-Based Application 10 Why Create a Document-Based Application? 10 A Document in iOS 11 A Document in iCloud Storage 12 Properties of a UIDocument Object 12 Design Considerations for Document-Based Applications 13 Defining Object Relationships 13 Designing the User Interface 14 Choosing Types, Formats, and Strategies for Document Data 15 Document-Based Application Preflight 18 What You Must Do to Make a Document-Based Application 18 Creating and Configuring the Project 19 How iOS Identifies Your Application’s Documents 20 Declare a Document Type 20 Exporting the Document UTI 22 Creating a Custom Document Object 23 Declaring the Document Class Interface 23 Loading Document Data 24 Supplying a Snapshot of Document Data 26 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Storing Document Data in a File Package 27 Other Method Overrides You Might Make 28 Managing the Life Cycle of a Document 30 Setting the Preferred Storage Location for Document Files 30 Creating a New Document 31 Document Filename Versus Document Name 31 Composing the File URL and Saving the Document File 31 Opening and Closing a Document 33 Discovering an Application’s Documents 33 Downloading Document Files from iCloud 36 Opening a Document 36 Closing a Document 38 Moving Documents to and from iCloud Storage 39 Getting the Location of the iCloud Container Directory 39 Moving a Document to iCloud Storage 40 Removing a Document from iCloud Storage 42 Monitoring Document-State Changes and Handling Errors 43 Deleting a Document 45 Change Tracking and Undo Operations 48 How UIKit Saves Document Data Automatically 48 Implementing Undo and Redo 48 Implementing Change Tracking 50 Resolving Document Version Conflicts 51 Learning About Document Version Conflicts 51 Strategies for Resolving Document Version Conflicts 51 How to Tell iOS That a Document Version Conflict Is Resolved 52 An Example: Letting the User Pick the Version 53 Document Revision History 56 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsFigures, Tables, and Listings Designing a Document-Based Application 10 Figure 1-1 Document file, document object, and model objects managed by the document object 12 Figure 1-2 A view controller manages both a document object and the view that presents document data 14 Document-Based Application Preflight 18 Figure 2-1 iOS looking up a document UTI from the extension of its file URL 20 Figure 2-2 Specification of a document type in Xcode 21 Figure 2-3 Exporting a custom document UTI in Xcode 22 Table 2-1 Properties for defining a document type (CFBundleDocumentTypes) 21 Table 2-2 Properties for exporting a document UTI (UTExportedTypeDeclarations) 22 Creating a Custom Document Object 23 Figure 3-1 Structure of a file package 27 Listing 3-1 Document subclass declarations (NSData) 23 Listing 3-2 Document subclass declarations (NSFileWrapper) 24 Listing 3-3 Loading a document’s data (NSData) 25 Listing 3-4 Loading a document’s data (NSFileWrapper) 25 Listing 3-5 Returning a snapshot of document data (NSData) 26 Listing 3-6 Returning a snapshot of document data (NSFileWrapper) 26 Managing the Life Cycle of a Document 30 Table 4-1 UIDocumentState constants 43 Listing 4-1 Getting a URL to the application’s Documents directory in the local sandbox 32 Listing 4-2 Saving a new document to the file system 32 Listing 4-3 Getting the locations of documents stored locally and in iCloud storage 34 Listing 4-4 Collecting information about documents in iCloud storage 35 Listing 4-5 Responding to a request to open a document 37 Listing 4-6 Opening a document 38 Listing 4-7 Closing a document 39 Listing 4-8 Getting the iCloud container directory URL 40 Listing 4-9 Moving a document file to iCloud storage from local storage 41 Listing 4-10 Moving a document file from iCloud storage to local storage 42 Listing 4-11 Adding an observer of the UIDocumentStateChangedNotification notification 43 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4Listing 4-12 Evaluating the current document state 44 Listing 4-13 Updating a document’s user interface to reflect its state 45 Listing 4-14 Deleting a selected document 46 Change Tracking and Undo Operations 48 Listing 5-1 Implementing undo and redo for a text field 49 Listing 5-2 Updating the change count of a document 50 Resolving Document Version Conflicts 51 Listing 6-1 Detecting a conflict in document versions 53 Listing 6-2 Showing the user interface for resolving document version conflicts 54 Listing 6-3 Resolving a document version conflict 54 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5 Figures, Tables, and ListingsThe UIKit framework offers support for applications that manage multiple documents, with each document containing a unique set of data that is stored in a file located either in the application sandbox or in iCloud. iCloud Daemon iCloud Daemon Central to this support is the UIDocument class, introduced in iOS 5.0. A document-based application must create a subclass of UIDocument that loads document data into its in-memory data structures and supplies UIDocument with the data to write to the document file. UIDocument takes care of many details related to document management for you. Besides its integration with iCloud, UIDocument reads and writes document data in the background so that your application’s user interface does not become unresponsive during these operations. It also saves document data automatically and periodically, freeing your users from the need to explicitly save. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6 About Document-Based Applications in iOSAt a Glance Although a document-based application is responsible for a range of behaviors, making an application document-based is usually not a difficult task. Document Objects Are Model Controllers In the Model-View-Controller design pattern, document objects—that is, instances of subclasses of UIDocument—are model controllers. A document object manages the data associated with a document, specifically the model objects that internally represent what the user is viewing and editing. A document object, in turn, is typically managed by a view controller that presents a document to users. Relevant Chapter: “Designing a Document-Based Application” (page 10) When Designing an Application, Consider Document-Data Format and Other Issues Before you write a line of code you should consider aspects of design specific to document-based applications. Most importantly, what is the best format of document data for your application, and how can you make that format work for your application in iOS and Mac OS X? What is the most appropriate document type? You also need to plan for the view controllers(and views) managing such tasks as opening documents, indicating errors, and moving selected documents to and from iCloud storage. Relevant Chapters: “Designing a Document-Based Application” (page 10), “Document-Based Application Preflight” (page 18) Creating a Subclass of UIDocument Requires Two Method Overrides The primary role of a document object is to be the “conduit” of data between a document file and the model objects that internally represent document data. It gives the UIDocument class the data to write to the document file and, after the document file isread, it initializesits model objects with the data that UIDocument givesit. To fulfill thisrole, yoursubclass of UIDocument must override the contentsForType:error: method and the loadFromContents:ofType:error: method, respectively. Relevant Chapter: “Creating a Custom Document Object” (page 23) An Application Manages a Document Through Its Life Cycle An application is responsible for managing the following events during a document’s lifetime: ● Creation of the document ● Opening and closing the document About Document-Based Applications in iOS At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7● Monitoring changes in document state and responding to errors or version conflicts ● Moving documents to iCloud storage (and removing them from iCloud storage) ● Deletion of the document Relevant Chapter: “Managing the Life Cycle of a Document” (page 30) An Application Stores Document Files in iCloud Upon User Request Applications give their users the option for putting all document files in iCloud storage or all document files in the local sandbox. To move document files to iCloud, they compose a file URL locating the document in an iCloud container directory of the application and then call a specific method of the NSFileManager class, passing in the file URL. Moving document filesfrom iCloud storage to the application sandbox follows a similar procedure. Relevant Chapter: “Managing the Life Cycle of a Document” (page 30) An Application Ensures That Document Data is Saved Automatically UIDocument follows the saveless model and automatically saves a document’s data at specific intervals. A user usually never has to save a document explicitly. However, your application must play its part in order for the saveless model to work, either by implementing undo and redo or by tracking changes to the document. Relevant Chapter: “Change Tracking and Undo Operations” (page 48) An Application Resolves Conflicts Between Different Document Versions When documents are stored in iCloud, conflicts between versions of a document can occur. When a conflict occurs, UIKit informs the application about it. The application must attempt to resolve the conflict itself or invite the user to pick the version he or she prefers. Relevant Chapter: “Resolving Document Version Conflicts” (page 51) How to Use This Document Before you start writing any code for your document-based application, you should at least read the first two chapters, “Designing a Document-Based Application” (page 10) and “Document-Based Application Preflight” (page 18). These chapters talk about design and configuration issues, and give you an overview of the tasks required for well-designed document-based applications About Document-Based Applications in iOS How to Use This Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8Prerequisites Before you read Document-Based Application Programming Guide for iOS you should become familiar with the information presented in iOS App Programming Guide . See Also The following documents are related in some way to Document-Based Application Programming Guide for iOS : ● Uniform Type Identifiers Overview and the related reference discuss Uniform Type Identifiers (UTIs), which are the primary identifiers of document types. ● FileMetadataSearchProgrammingGuide describeshowtoconductsearchesusingtheNSMetadataQuery class and related classes. You use metadata queries to locate an application’s documents stored in iCloud. ● iCloud Design Guide provides an introduction to iCloud document support. About Document-Based Applications in iOS Prerequisites 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9The UIDocument class, introduced in iOS 5.0, plays the principal role in document-based applications for iOS. It is an abstract base class—meaning that for you to have something useful, you must create a subclass of it that is tailored to the needs of your application. The application-specific code that you add to the subclass augments what UIDocument makes possible: efficient behavior of documents in a mobile environment integrated with iCloud storage. Why Create a Document-Based Application? When you have an idea for any application and sit down to design it, you must evaluate a multitude of options. What style of application should you use (master-detail, page-based utility, OpenGL game, and so on)? Will the application do its own drawing, will it respond to gestures or touch events, and will it incorporate audiovisual assets? What will the data model be—for example, should the application use Core Data? The decision whether to make your application document-based might seem to complicate that series of choices, but it really boils down to how you anticipate people will use your application. Document-based applications are ideal, even necessary, when users expect to enter and edit content in a visual container and store that content under a name they specify. Each container of information—a document—is unique. You are no doubt familiar with several types of document-based applications found in both desktop and mobile systems. To name a few, there are word processors, spreadsheets, and drawing programs. With the iCloud technology, you have an even more compelling reason to make your application document-based. Your users, for example, could create a document using your application on a OS X desktop system and then later, without having to do any syncing or copying, edit that document on an iPad using the iOS version of your application. This feature gives them an additional incentive to buy your application. When you adopt the UIDocument approach to document-based applications, your application gets a lot of behavior “for free” or with minimal coding effort on your part. ● Integration with iCloud storage. The UIDocument object coordinates all reading and writing of document data from and to iCloud storage. It does this by adopting the NSFilePresenter protocol and by calling methods of the NSFileCoordinator and NSFileManager classes. ● Background writing and reading of document data. If your application reads and writes a document synchronously, it can become momentarily unresponsive. The UIDocument object avoids this problem by reading and writing document data asynchronously on a background dispatch queue. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10 Designing a Document-Based Application● Savelessmodel. In the saveless model, a user of a document-based application rarely hasto save documents explicitly; The UIDocument object saves document data automatically at intervals optimized for what the user is doing with the document. You make your document-based application “saveless” by implementing undo management or change tracking (see “Change Tracking and Undo Operations” (page 48) for information). ● Safe saving. The UIDocument object saves document data safely; consequently, if some external event interrupts a save operation, document data won’t be left in an inconsistent state. The object implements safe saving by first writing the newest version of a document to a temporary file and then replacing the current document file with it. ● Support for handling errors and version conflicts. When the UIDocument object detects a conflict between different versions of a document, it notifies the application. The application can then attempt to resolve the conflict itself, or it can ask the user to pick the desired document version. The UIDocument object also notifies an application when a save operation does not succeed. “Managing the Life Cycle of a Document” (page 30) describes how to observe these notifications; “Resolving Document Version Conflicts” (page 51) discusses strategies for dealing with document-version conflicts. A Document in iOS Although the broad definition of a document is a “container of information,” that container can be viewed in several ways. To a user, a document is the text, images, shapes, and other forms of information that he or she creates, edits, and saves under a unique name. A document can also refer to a document file: the persistent, on-disk representation of document data. And a document can mean a UIDocument object that represents and manages the in-memory representation of that same data. A document object also plays a key role in converting document data between its representation on disk to its representation in memory. It cooperates with the UIDocument class in the writing of document data to a file and the reading of that data. For writing, a document typically provides a snapshot of data that can be Designing a Document-Based Application A Document in iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11written to the document file; for reading, it receives data and initializes the document’s model objects with it. A document, in a sense, is a conduit between data stored in a file and the internal representation of that data. Figure 1-1 illustrates these relationships. Figure 1-1 Document file, document object, and model objects managed by the document object Document Model Model Model Model Document File A Document in iCloud Storage In iCloud, files reside locally in a container directory that is associated with an application. That directory has an internal structure that includes, most importantly, a Documents subdirectory. In the iCloud scheme, files and file packages written to the Documents subdirectory are considered document files—even if they don’t originate from document-based applications. Filesthat are written to other locationsin the container directory are considered data files. Document objects are file presenters because the UIDocument class adopts the NSFilePresenter protocol. A file presenter is used together with NSFileCoordinator objects to coordinate access to a file or directory among the objects of an application and between an application and other processes. A file presenter is involved in other clients’ access of the same presented file or directory. When users ask to store document files in iCloud storage, a document-based application should save those files (including file packages) in the Documents subdirectory of the iCloud container directory. See “Managing the Life Cycle of a Document” (page 30) for specifics. For more information about iCloud mobile containers, see iCloud Design Guide . Properties of a UIDocument Object A document object has several defining properties, most of which relate to its role as a manager of document data. These properties are declared by the UIDocument class. Designing a Document-Based Application A Document in iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12● File URL. A document must have a location where it can be stored, whether that location is in the local file system or in iCloud storage. The fileURL property identifies this location. When you create a UIDocument object, you must specify a file URL as the parameter of the initWithFileURL: initializer method of UIDocument. ● Document name. A UIDocument object obtains a default document name from the filename component of the file URL and stores it in the localizedName property. You can override the getter method of this property to provide a custom, localized document name. Note: The display name of a document does not have to correspond to the filename of the document. In addition, usersshould not be required to specify a document name. See “Creating a New Document” (page 31) for more information on this subject. ● File type. The file type is a Uniform Type Identifier (UTI) derived from the extension of the file URL and assigned to the fileType property. For more information, see “How iOS Identifies Your Application’s Documents” (page 20). ● Modification date. The date the document file was last modified. This value is stored in the fileModificationDate property. It can be use for (among other things) resolving document-version conflicts. ● Document state. A document is in one of several possible states during its runtime life. These states can indicate, for example, that there was an error in saving the document or that there are conflicting document versions. UIDocument storesthe current documentstate in the documentState property. For information about observing changes in document state, see “Monitoring Document-State Changes and Handling Errors” (page 43). Design Considerations for Document-Based Applications Before you write a line of code for your document-based application, it’s worth your while to think about a few design issues. Defining Object Relationships As with all applications, you should devise an overall design for the objects of your document-based application that is based on the Model-View-Controller design pattern (MVC). Although the following MVC design for documents is recommended, you are free to come up with your own object-relationship designs. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13In MVC terms, a document is a model controller; it “owns” and manages the model objects that represent the document’s content. The document object itself is owned and managed by a view controller. The view controller, by definition, also manages a view that presents the content managed by the document object. It is thus a mediating controller in this network of relationships, obtaining the data it needs to present in the view from the document object and passing data entered or changed by usersto the document object. Figure 1-2 depicts these object relationships. Figure 1-2 A view controller manages both a document object and the view that presents document data Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. manages manages View controller Document Model Model Model Just as a view controller embeds its view, a view controller might embed the document object as a declared property. When your application instantiates the view controller, it initializes it with the document object or with the document’s file URL (from which the view controller itself can create the document object). Of course, a document-based application will have other view controllers (with their views) and possibly other model objects. To get an idea of what other view controllers might be required, see “Designing the User Interface” (page 14). Designing the User Interface Neither UIKit nor the developer tools provide any support for the user interface of a document-based application. For instance, there is no UIDocumentView class or UIDocumentViewController class and there is no standard interface for selecting documents. Rather than regret the absence, take it as an opportunity to create a user interface for your document-based application that makes it stand out from the competition. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14Nonetheless, all document-based applications should enable their users to do certain things that require user interface elements; these include the following: ● Viewing and editing a document ● Creating a new document ● Selecting a document from a list of documents owned by the application ● Opening, closing, and deleting a selected document ● Putting a selected document in iCloud storage (and removing a selected document from iCloud storage) ● Indicating error conditions, including document-version conflicts ● Undoing and redoing changes (recommended but not required) When you design your application, be sure to include the view controllers, views, and controlsthat are necessary to implement these actions. Choosing Types, Formats, and Strategies for Document Data When designing the data model for your document-based application, it’s critical that you ask and answer the following questions: What is the type of my document? A document must have a document type, a collection of information that characterizes the document and associatesit with an application. A document type has a name, an icon (optional), a handler rank, and a Uniform Type Identifier (UTI) that is paired with one or more filename extensions. For an application to edit the same document in iOS and in OS X, the document-type information should be consistent. “Creating and Configuring the Project” (page 19) explains how to specify document typesin a document-based iOS application. See Uniform Type Identifiers Overview for a description of UTIs and Uniform Type Identifiers Reference for descriptions of common Uniform Type Identifiers. How should I represent the document data that is written to a file? You have basically three choices: ● Core Data (database). Core Data is a technology and framework for object-graph management and persistence. It can use the built-in SQLite data library as a database system. The UIManagedDocument class, a subclass of UIDocument, is intended for document-based applications that use Core Data. ● Supported object formats. UIDocument supports the NSData and NSFileWrapper objects as native typesfor document-data representation. NSData isintended for flat files, and NSFileWrapper isintended for file packages, which are directories that iOS treats as a single file. If you give UIDocument one of these objects, it saves it to the file system without further involvement on your part. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15● Custom object formats. If you want the document data written to a file to be of a type other than NSData or NSFileWrapper, you can write it to the file yourself in an override of a specific UIDocument method. Keep in mind that your code will have to duplicate what UIDocument does for you, and so you must deal with greater complexity and a greater possibility of error. See UIDocument Class Reference for further information. Why would I want to store my document data in a database instead of a file? If the data set managed by your document object is primarily a large object graph but your application uses only a subsection of that graph at any time, then UIManagedDocument and Core Data are a good option. Core Data brings many benefits to a document-based application: ● Incremental reading and writing of document data ● Support for undo and redo operations ● Automatic support for resolving document-version conflicts ● Data compatibility for cross-platform applications The “downside” to Core Data isthat it is a complex technology; it takestime to become familiar with its concepts, classes, and techniques. To learn more, read Core Data Programming Guide and UIManagedDocument Class Reference . Which of the supported object formats (NSData or NSFileWrapper) is best for my application? Whether you use an NSData or NSFileWrapper object for document data depends on how complex that data is and on whether part of your document’s model-object graph can be written out separately to a file. For example, if your document data is plain text and nothing else, then NSData is a suitable container for it. If, however, the data has multiple components—for example, text and images—use NSFileWrapper methods to create a file package for the data. File wrapper objects—and file packages which they represent—offersome advantages over binary data objects. ● File wrappers support incremental saving. In contrast with a single binary data object, if a file wrapper contains your document data—for example, text and an image—and the text changes, only the file containing the text has to be written out to disk. This capability results in better performance. ● File wrappers (and file packages) make it easier to version documents. A file package, for example, can contain a property list file that holds version information and other metadata about a document. “Storing Document Data in a File Package” (page 27) discusses(and illustrates) how you use an NSFileWrapper object to represent document data in a form that can be written out as a file package. Can I archive my model-object graph and have that NSData object written to the document file? Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16Yes, that is possible, but some of the caveats previously mentioned apply. If any part of your document’s model-object graph can be written to a separate file, don’t archive that part. Instead, store the NSData archive and the partitioned-out items as separate components of a file package. What if my document file is very large? If the data stored in a document file can be large, you might have to write and read the data incrementally to ensure a good user experience. There are a few approaches you might take: ● Use UIManagedDocument. Remember, Core Data gives you incremental reading and writing “for free.” ● Store the separable components of your document data in a file package. ● Override lower-level methods of UIDocument and do the incremental reading and writing of data yourself. (See UIDocument Class Reference for particulars.) You should always use an API for incremental reading and writing that is appropriate to the data type; for example, the AV Foundation framework has methods for incremental reading of large multimedia files. What should I be thinking about if I want my documents to be editable on both platforms? Your application will have a competitive advantage if your users can create and edit documents both on iOS mobile devices (iPhone, iPad, and iPad touch) and on OS X desktop systems. But for this to be possible, the format of the document data on both platforms should be compatible. Some important considerations for document-data compatibility are: ● Some technologies are available on one platform but not the other. For example, if you’re using RTF as a document format in OS X, that format won’t work in iOS because its text system doesn’t support rich text. ● The corresponding classesin each platform are not compatible. Thisis especially true with colors(UIColor and NSColor), images (UIImage and NSImage), and Bezier paths (UIBezierPath and NSBezierPath). NSColor objects, for example, are defined in terms of a color space (NSColorSpace), but there is no color space class in UIKit. If you define a document property with one of these classes, you must devise a way (when preparing the document data for writing) to convert the property into a form that can be accurately reconstituted on the other platform. One way to do this is to “drop down” to a lower-level framework that is shared by both platforms. For example, UIColor defines a CIColor property holding a Core Image object representing the color; on the OS X side, your application can create an NSColor object from the CIColor object using the colorWithCIColor: class method. ● The default coordinate system for each platform is different, and this difference can affect how content is drawn. (See “Default Coordinate Systems and Drawing in iOS” in Drawing and Printing Guide for iOS for a discussion of this topic). ● If you archive a document’s model-object graph, partially or entirely, then you might have to perform platform-sensitive conversions using NSCoder methods when you encode and decode the model objects. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17For most developers, making a document-based application doesn’t require much more effort than making an application that isn’t document based. The basic difference is that you must create a custom subclass of UIDocument and then manage a document through the phases of its runtime life, including its integration with iCloud storage. This chapter outlines those document-specific tasks performed by most applications and describes the general steps for creating and configuring a document-based application project in iOS. What You Must Do to Make a Document-Based Application To create a document-based application, you should complete the following tasks: ● Create a custom subclass of UIDocument that provides the UIKit framework with a snapshot of document data and that initializes the document’s model objects from the contents of the document file. “Creating a Custom Document Object” (page 23) describesthe required method overrides and, if document data isto be stored as a file package, explains how to go about using NSFileWrapper objectsfor document data. ● Allow users to create new documents and select and open existing ones. You should also implement the complementary tasks of closing documents and deleting selected documents. Note that the follow-on task to creating or opening a document is displaying the document’s content in a view. “Creating a New Document” (page 31), “Opening and Closing a Document” (page 33), and “Deleting a Document” (page 45) describe the requirements and procedures for these tasks. These discussions also include examples of managing the display of document data. ● Implement undo management or change tracking to enable the automatic saving of document data (saveless model). See “Change Tracking and Undo Operations” (page 48) for details. ● Put documents—typically those selected by users—into iCloud storage. Also remove documents from iCloud storage when users request this. “Moving Documents to and from iCloud Storage” (page 39) discusses these procedures. ● Observe notifications of changes in document state and, if an error occurs, respond appropriately. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18 Document-Based Application Preflight“Monitoring Document-State Changes and Handling Errors” (page 43) describes the general procedure for doing this. ● If conflicts between different versions of a document occur, notify the user and offer ways to resolve the conflicts. “Resolving Document Version Conflicts” (page 51) describes how to notify users of version conflicts and discusses strategies for resolving these conflicts. You can also add extra features to your document-based application, such as the capability for printing the document, spell-checking it, or emailing it to others. If your application has advanced requirements—for example, incremental reading and writing of large document files or dealing with document-data formats other than the supported ones—see UIDocument Class Reference . All of these advanced tasks involve overriding UIDocument methods. Creating and Configuring the Project When you create the Xcode project for your document-based application, choose a suitable template. (Note that there is no template specifically for document-based applications.) Generally, you want the first view of the application to be one in which users can choose existing documents and create new ones. Because the Master-Detail Xcode template is suitable for this purpose, it is used in the code examples throughout this document. Thistemplate gives you an initial table view for the iPhone and a split view for the iPad. Your project should use a storyboard, so be sure to select this option. Note: If you are using Core Data to manage document data, be sure to select the “Use Core Data” option in the New Project assistant. Based on the design for your application (see “Designing a Document-Based Application” (page 10)), create the view-controller subclasses that your application requires. All you need are minimally declared header and source files at this point. Then, create the user interface of your application in the project storyboard (or storyboards, if yours is a universal application); associate your custom view controllers with the view-controller placeholders in the storyboard. Next, you need to configure the project for documents by specifying, in the Xcode target settings, the type or types of the documents that the application knows about. Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19How iOS Identifies Your Application’s Documents The most important attribute of a document object in iOS is its file URL (fileURL). The file URL is important, among other reasons, because it tells iOS which applications understand the document’s format. The file URL ends with an extension (for example, html) and this extension is matched with a Uniform Type Identifier (for example, public.html). The Uniform Type Identifier (UTI) is the principal identifier of document type. Using the extension, UIDocument looks up the document-type UTI (as shown in Figure 2-1) and assigns it to the fileType property. Unlike document-based applications in OSX, those in iOS don’t need to associate the UIDocument subclass with the document type. Figure 2-1 iOS looking up a document UTI from the extension of its file URL File /Documents/foo.mydoc Application File System Document fileURL CFBundleDocumentTypes (Document Type 1) CFBundleTypeExtensions mydoc LSItemContentTypes com.acme.app.mydoc ... A document-type UTI can be defined by the system; see “System-Declared Uniform Type Identifiers” in Uniform Type Identifiers Reference for a list of these common identifiers. A document-based application can also define its own proprietary UTI for its documents (and often does). If it does declare a custom UTI, it must also export that UTI to make the operating system aware of it. Declare a Document Type To declare a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Document Type from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-1. Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20Table 2-1 Properties for defining a document type (CFBundleDocumentTypes) Key Xcode field Value and comments An array of UTIstrings. Only one istypically specified per document type. LSItemContentTypes Types CFBundleTypeName Name An optional name for the document type. An array of paths to icon image files in the application bundle. CFBundleType- Icon IconFiles An array of filename extensions paired with the document UTI. In “Additional document type properties” table. CFBundleTypeExtensions Owner, Alternate, None. (Typically Owner). In “Additional document type properties” table. LSHandlerRank If document data isstored in a file package, set this property to YES. Otherwise omit. In “Additional document type properties” table. LSTypeIsPackage Formore information aboutthese keys,see “CFBundleDocumentTypes” in Information Property List Key Reference . When you have finished entering the properties for a document type, The Document Types area of Xcode should look similar to the example in Figure 2-2. Figure 2-2 Specification of a document type in Xcode An application could have multiple types of documents—for example, a word-processing application could have a type for regular (blank) documents and another type for pre-formatted documents. For each type, you need to go through the procedure given above . Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21Exporting the Document UTI If you define a custom UTI for your documents, you must also export it. To export a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Exported UTI from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-2. Note: The procedure for declaring and exporting UTIs is described in “Declaring New Uniform Type Identifiers” in Uniform Type Identifiers Overview. Table 2-2 Properties for exporting a document UTI (UTExportedTypeDeclarations) Key Xcode field Value and comments UITypeIdentifier Identifier The custom document UTI, a string. The UTI that the custom document UTI conforms to. If the data representation is a file package, specify com.apple.package. UTTypeConformsTo Conforms to UTTypeDescription Description Description of the exported type (optional). Create an array named public.filename-extension. Then add as items all extensions of the document file. In “Additional exported UTI properties” table. UTTypeTagSpecification Formore information aboutthese keys,see “CFBundleDocumentTypes” in Information Property List Key Reference . When you have finished entering the properties for a document type, The Exported UTIs area of Xcode should look similar to the example in Figure 2-3. Figure 2-3 Exporting a custom document UTI in Xcode Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22A document-based application must have an instance of a subclass of UIDocument that represents and manages document data. This chapter discusses the method overrides most applications need to make and offers suggestions for overriding other methods. For the core override points—the loadFromContents:ofType:error: and contentsForType:error: methods—examples are given for both NSData and NSFileWrapper astypes of document data read from and written to a file.“Storing Document Data in a File Package” (page 27) further explains how to use file-wrapper objects for document data. You can override methods of UIDocument other than the ones discussed in this chapter to read and write document data for particular purposes—for example, to write and read document data incrementally. However, these more advanced overrides have more complex requirements and should be avoided if possible. See UIDocument Class Reference for discussions of these overrides. Declaring the Document Class Interface In Xcode, add new Objective-C source and header files to your project, naming them appropriately (suggestion: work “Document” into the name). In the header file, change the superclass to UIDocument and add properties to hold the document data. In Listing 3-1, the document data is plain text, so an NSString property is all that is needed to hold it. (The text will be converted to an NSData object that is written to the document file.) Listing 3-1 Document subclass declarations (NSData) @interface MyDocument : UIDocument { } @property(nonatomic, strong) NSString *documentText; @end Listing 3-2 illustrates set of declarations for another application that uses an NSFileWrapper object as the data-representation type. (The code examples in the chapter alternate between the two applications.) Not only is there a property to hold the file-wrapper object, there are properties to hold the text and image components of the represented file package. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23 Creating a Custom Document ObjectListing 3-2 Document subclass declarations (NSFileWrapper) @interface ImageNotesDocument : UIDocument @property (nonatomic, strong) NSString* text; @property (nonatomic, strong) UIImage* image; @property (nonatomic, strong) NSFileWrapper *fileWrapper; @property (nonatomic, weak) id delegate; @end @protocol ImageNotesDocumentDelegate -(void)noteDocumentContentsUpdated:(ImageNotesDocument*)noteDocument; @end This code shows additional declarations for a delegate and the protocol that it adopts. The document object’s view controller makes itself the delegate of the document object (and adopts the protocol) so that it can be notified (via noteDocumentContentsUpdated: messages) of modifications to the document file. Listing 3-4 (page 25) shows when and how the noteDocumentContentsUpdated: message is sent. Loading Document Data When an application opens a document (at the user’srequest), UIDocument readsthe contents of the document file and calls the loadFromContents:ofType:error: method, passing in an object encapsulating the document data. That object can be an NSData object or an NSFileWrapper object. In your override of the method, initialize the document’s internal data structures (that is, its model objects) from the contents of the passed-in object. The example in Listing 3-3 creates a string from the passed-in NSData object and assigns it to the documentText property. It also informs its delegate (in this case, the document’s view controller) of the updated document contents by invoking a protocol method. The motivation behind this delegation message isthatthe loadFromContents:ofType:error:method is called not only asthe result of opening a document, but also because of iCloud updates and reversion operations (revertToContentsOfURL:completionHandler:). Creating a Custom Document Object Loading Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Listing 3-3 Loading a document’s data (NSData) - (BOOL)loadFromContents:(id)contents ofType:(NSString *)typeName error:(NSError **)outError { if ([contents length] > 0) { self.documentText = [[NSString alloc] initWithData:(NSData *)contents encoding:NSUTF8StringEncoding]; } else { self.documentText = @""; } if ([_delegate respondsToSelector:@selector(noteDocumentContentsUpdated:)]) { [_delegate noteDocumentContentsUpdated:self]; } return YES; } If you have more than one document type, check the typeName parameter; a different document type might affect how your code handles the document-data object. If your code experiences an error that prevents it from loading document data, return NO; optionally, you can return by reference an NSError object that describes the error. The example in Listing 3-4 handles document data in the form of an NSFileWrapper object. It simply assigns this object to its property. Listing 3-4 Loading a document’s data (NSFileWrapper) -(BOOL)loadFromContents:(id)contents ofType:(NSString *)typeName error:(NSError **)outError { self.fileWrapper = (NSFileWrapper *)contents; if ([_delegate respondsToSelector:@selector(noteDocumentContentsUpdated:)]) { [_delegate noteDocumentContentsUpdated:self]; } return YES; } In this code, the method implementation does not extract the text and image components of the file wrapper and assign them to their properties. That is done lazily in the getter methodsfor the text and image properties. Creating a Custom Document Object Loading Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25Supplying a Snapshot of Document Data When a document is closed or when it is automatically saved, UIDocument sends the document object a contentsForType:error: message. You must override this method to return a snapshot of the document’s data to UIDocument, which then writes it to the document file. Listing 3-5 gives an example of returning a snapshot of document data in the form of an NSData object. Listing 3-5 Returning a snapshot of document data (NSData) - (id)contentsForType:(NSString *)typeName error:(NSError **)outError { if (!self.documentText) { self.documentText = @""; } NSData *docData = [self.documentText dataUsingEncoding:NSUTF8StringEncoding allowLossyConversion:NO]; return docData; } If the documentText property has not yet been assigned any string value yet, it is assigned an empty string before it’s used to create an NSData object. Listing 3-6 shows an implementation of the same method that returns an NSFileWrapper object. Basically, if a top-level (directory) file-wrapper object doesn’t exist, the code creates it; and if the two contained (regular file) file-wrapper objects do not exist, the code createsthem from the values of the text and image properties. Then, it returns the top-level file wrapper to UIDocument, which creates a file package in the file system. See “Storing Document Data in a File Package” (page 27) for a more detailed explanation of file packages and documents. Listing 3-6 Returning a snapshot of document data (NSFileWrapper) -(id)contentsForType:(NSString *)typeName error:(NSError **)outError { if (self.fileWrapper == nil) { self.fileWrapper = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil]; } NSDictionary *fileWrappers = [self.fileWrapper fileWrappers]; if (([fileWrappers objectForKey:TextFileName] == nil) && (self.text != nil)) { NSData *textData = [self.text dataUsingEncoding:TextFileEncoding]; Creating a Custom Document Object Supplying a Snapshot of Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26NSFileWrapper *textFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:textData]; [textFileWrapper setPreferredFilename:TextFileName]; [self.fileWrapper addFileWrapper:textFileWrapper]; } if (([fileWrappers objectForKey:ImageFileName] == nil) && (self.image != nil)) { @autoreleasepool { NSData *imageData = UIImagePNGRepresentation(self.image); NSFileWrapper *imageFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:imageData]; [imageFileWrapper setPreferredFilename:ImageFileName]; [self.fileWrapper addFileWrapper:imageFileWrapper]; } } return self.fileWrapper; } Storing Document Data in a File Package A file package has an internal structure that is reflected in the methods of the NSFileWrapper class. A file wrapper is a runtime representation of a file-system node, which is either a directory, a regular file, or a symbolic link. As shown in Figure 3-1, a file package is a file-system node, typically a directory and its contents, that the operating system treats as a single, opaque entity. It is similar in concept to a bundle. Figure 3-1 Structure of a file package File File File Directory ArchivedObjects theImage.png Creating a Custom Document Object Storing Document Data in a File Package 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27You programmatically compose a file package by creating a top-level directory file wrapper and then adding to that container regular files and subdirectories, each represented by other NSFileWrapper objects. File wrappers inside the top-level directory should have preferred names associated with them. With this brief overview in mind, look again at the following lines of code from the contentsForType:error: method in Listing 3-6 (page 26). The file package created in this method has two components, a text file and an image file. (The creation of the image file wrapper is not shown in the snippet.) if (self.fileWrapper == nil) { self.fileWrapper = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil]; } NSDictionary *fileWrappers = [self.fileWrapper fileWrappers]; if (([fileWrappers objectForKey:TextFileName] == nil) && (self.text != nil)) { NSData *textData = [self.text dataUsingEncoding:TextFileEncoding]; NSFileWrapper *textFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:textData]; [textFileWrapper setPreferredFilename:TextFileName]; [self.fileWrapper addFileWrapper:textFileWrapper]; } The code creates a top-level directory if it doesn’t exist. If a file wrapper doesn’t exist for the text file, it creates one from the string contents of the text property. It gives this file wrapper a preferred filename and then adds it to the top-level directory file wrapper. Formore on NSFileWrapper,seeNSFileWrapper Class Reference ; also see “Exporting theDocumentUTI” (page 22) for the required Info.plist property for document file packages. Other Method Overrides You Might Make There are a few other UIDocument overrides that many document-based applications might want to make: ● disableEditing...enableEditing—UIDocument calls the first method when it is unsafe for the user to make changes to document content, such as when there are updates from iCloud or a revert operation is underway. You can implement this method to prevent editing during this period. When editing becomes safe again, UIDocument calls the second method. Creating a Custom Document Object Other Method Overrides You Might Make 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Note: As an alternative to these overrides, you can observe notifications posted when the document state changes and, if the new document state is UIDocumentStateEditingDisabled, prevent editing until the document state changes again. More more on this topic, see “Monitoring Document-State Changes and Handling Errors” (page 43). ● savingFileType—This method by default returns the value of the fileType property. If the current document should be saved under a different file type for any reason, you can override this method to return the replacement file-type UTI. An example (from Mac OS X) is that when an image is added to an RTF file, it should be saved as an RTFD file package. Creating a Custom Document Object Other Method Overrides You Might Make 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29A document goes through a typical life cycle. A document-based application is responsible for managing its progress through that cycle. As you can see from the following list, most of these life-cycle events are initiated by the user: ● The user first creates a document. ● The user opens an existing document and the application displays it in the document’s view or views. ● The user edits the document. ● A user may ask to put a document in iCloud storage or may request the removal of a document from iCloud storage. ● During editing, saving, or other actions, errors or conflicts can happen; the application should learn about these errors and conflicts and either attempt to handle them or inform the user. ● The user closes a selected document. ● The user deletes an existing document. The following sections discussthe procedures a document-based application must complete for these life-cycle operations. Setting the Preferred Storage Location for Document Files All documents of an application are stored either in the local sandbox or in an iCloud container directory. A user should not be able to select individual documents for storage in iCloud. When an application launches for the first time on a device, it should do the following: ● If iCloud is not configured, ask users if they want to configure it (and, preferably, transfer them to Launch Settings if they want to configure iCloud). ● If iCloud is configured but not enabled for the application, ask users if they want to enable iCloud—in other words, ask if they want all of their documentssaved to iCloud. Store the response as a user preference. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30 Managing the Life Cycle of a DocumentBased on this preference, an application writes document files either to the local application sandbox or the iCloud container directory. (For details, see “Moving Documents to and from iCloud Storage” (page 39).) An application should expose a switch in the Settings application that enables usersto move documents between local storage and iCloud storage. Creating a New Document A document object (that is, an instance of your custom UIDocument subclass) must have a file URL that locates the document file either in the local application sandbox or in an iCloud container directory, whichever is the user’s preference. In addition, a new document can be given a name. The following discusses guidelines and procedures related to file URLs, document names, and the creation of new documents. Document Filename Versus Document Name The UIDocument class assumes a correspondence between the filename of a document and the document name (also known the display name). By default, UIDocument stores the filename as the value of the localizedName property. However, an application should not require a user to provide the document filename or display name when he or she creates a new document. For your application, you should devise some convention for automatically generating the filenames for your new documents. Some suggestions are: ● Generate a UUID (universally unique identifier) for each document, optionally with an application-specific prefix. ● Generate a timestamp (date and time) for each document, optionally with an application-specific prefix. ● Use a sequential numbering system, for example: “Notes 1”, “Notes 2”, and so on. For the document (display) name, you might initially use the document filename if that makes sense (such as with “Notes 1”). Or, if the document contains text and the user enters some text in the document, you might use the first line (or some part of the first line) as the display name. Your application can give users some way to customize the document name after the document has been created. Composing the File URL and Saving the Document File You cannot create a document object without a valid file URL. The file URL has three parts of interest: the path to the Documents directory in the user’s preferred document location, the document filename, and the extension of the document file. You can get a URL representing the path to the Documents directory in the local application sandbox through a method such asthe one in “Document Filename Versus Document Name.” Managing the Life Cycle of a Document Creating a New Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31Listing 4-1 Getting a URL to the application’s Documents directory in the local sandbox -(NSURL*)localDocumentsDirectoryURL { static NSURL *localDocumentsDirectoryURL = nil; if (localDocumentsDirectoryURL == nil) { NSString *documentsDirectoryPath = [NSSearchPathForDirectoriesInDomains( NSDocumentDirectory, NSUserDomainMask, YES ) objectAtIndex:0]; localDocumentsDirectoryURL = [NSURL fileURLWithPath:documentsDirectoryPath]; } return localDocumentsDirectoryURL; } The file extension must be one that you specified for the document type (see “Creating and Configuring the Project” (page 19)). You can declare a global string to represent the extension. For example: static NSString *FileExtension = @"imageNotes"; The final part of a document’s file URL is the filename component. As “Document Filename Versus Document Name” (page 31) explains, the application should initially generate the document filename according to some convention that makes sense for the application. This generated filename can be used as the document name, or the first line (or part thereof) can be used as the document name. The application can give the user the option of customizing the document name after the document object has been created. After you concatenate the base URL, the document filename, and the file extension, you can allocate an instance of your custom UIDocument subclass and initialize it with the initWithFileURL: method, passing in the constructed file URL. The final step in creating a new document is to save it to the preferred document storage location (even though there is no content at this point). Asillustrated by “Setting the Preferred Storage Location for Document Files ,” you do this by calling the saveToURL:forSaveOperation:completionHandler: method on the document object. Listing 4-2 Saving a new document to the file system -(void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; if (_createFile) { [self.document saveToURL:self.document.fileURL Managing the Life Cycle of a Document Creating a New Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) { if (success) _textView.text = self.document.text; }]; _createFile = NO; } // ..... } The save-operation parameter of the method call should be UIDocumentSaveForCreating. The final parameter of the call is a completion hander: a block that is invoked after the save operation concludes. The parameter of the block tells you whether the operation succeeded. If it did succeed, this code assigns the document text to the text property of the text view displaying the document content. Note: If you want to save a new document to the application’s iCloud container directory, it is recommended that you first save it locally and then call the NSFileManager method setUbiquitous:itemAtURL:destinationURL:error: to move the document file to iCloud storage. (This call could be made in the completion handler of the saveToURL:forSaveOperation:completionHandler: method.) See “Moving Documents to and from iCloud Storage” (page 39) for further information. Opening and Closing a Document Opening a document might at first glance seem to be a fairly easy procedure. Your application scans the contents of its Documents directory for files having the document’s extension and presents those documents to the user for selection. However, when iCloud storage is factored in, things get a bit more complicated. Your application’s documents could be in the Documents directory of the application sandbox or they could be in the Documents directory of the iCloud container directory. Discovering an Application’s Documents To obtain a list of an application’s documents in iCloud storage, run a metadata query. A query is an instance of the NSMetadataQuery class. After creating a NSMetadataQuery object, you give it a scope and a predicate. For iCloud storage, the scope should be NSMetadataQueryUbiquitousDocumentsScope. A predicate is an NSPredicate object that, in this case, constrains a search by filename extension. Before you start running the Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33query, register to observe the NSMetadataQueryDidFinishGatheringNotification and NSMetadataQueryDidUpdateNotification notifications. The method accepting delivery of these notifications processes the results of the query. Listing 4-3 illustrates how you set up and run a metadata query to get the list of application documents in the iCloud mobile container. The method first tests the user’s preferred storage location for documents (the documentsInCloud property). If that location isthe mobile container, it runs a metadata query. If the location is the application sandbox, it iterates through the contents of the application’s Documents directory to get the names and locations of all local document files. Listing 4-3 Getting the locations of documents stored locally and in iCloud storage -(void)viewDidLoad { [super viewDidLoad]; // set up Add and Edit navigation items here.... if (self.documentsInCloud) { _query = [[NSMetadataQuery alloc] init]; [_query setSearchScopes:[NSArray arrayWithObjects:NSMetadataQueryUbiquitousDocumentsScope, nil]]; [_query setPredicate:[NSPredicate predicateWithFormat:@"%K LIKE '*.txt'", NSMetadataItemFSNameKey]]; NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter]; [notificationCenter addObserver:self selector:@selector(fileListReceived) name:NSMetadataQueryDidFinishGatheringNotification object:nil]; [notificationCenter addObserver:self selector:@selector(fileListReceived) name:NSMetadataQueryDidUpdateNotification object:nil]; [_query startQuery]; } else { NSArray* localDocuments = [[NSFileManager defaultManager] contentsOfDirectoryAtPath: [self.documentsDir path] error:nil]; for (NSString* document in localDocuments) { [_fileList addObject:[[[FileRepresentation alloc] initWithFileName:[document lastPathComponent] url:[NSURL fileURLWithPath:[[self.documentsDir path] stringByAppendingPathComponent:document]]] autorelease]]; Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34} } } In this example, the predicate format is @"%K LIKE '*.txt’", which means to return all filenames (the NSMetadataItemFSNameKey key) that have a extension of txt, the file extension of this application’s document files. After the initial query concludes, and again if there are subsequent updates, the notification method specified in Listing 4-3 (fileListReceived) isinvoked again. Listing 4-4 showsthis method’simplementation. If query updates arrive after the user has made a selection, the code also tracks the current selection. Listing 4-4 Collecting information about documents in iCloud storage -(void)fileListReceived { NSString* selectedFileName=nil; NSInteger newSelectionRow = [self.tableView indexPathForSelectedRow].row; if (newSelectionRow != NSNotFound) { selectedFileName = [[_fileList objectAtIndex:newSelectionRow] fileName]; } [_fileList removeAllObjects]; NSArray* queryResults = [_query results]; for (NSMetadataItem* result in queryResults) { NSString* fileName = [result valueForAttribute:NSMetadataItemFSNameKey]; if (selectedFileName && [selectedFileName isEqualToString:fileName]) { newSelectionRow = [_fileList count]; } [_fileList addObject:[[[FileRepresentation alloc] initWithFileName:fileName url:[result valueForAttribute:NSMetadataItemURLKey]] autorelease]]; } [self.tableView reloadData]; if (newSelectionRow != NSNotFound) { NSIndexPath* selectionPath = [NSIndexPath indexPathForRow:newSelectionRow inSection:0]; [self.tableView selectRowAtIndexPath:selectionPath animated:NO scrollPosition:UITableViewScrollPositionNone]; Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35} } The example application now has an array (_fileList) of custom model objects that encapsulate the name and file URL of each of the application’s documents. (FileRepresentation is the custom class of those objects.) The root view controller populates a plain table view with the document names Note: You should leave metadata queries running only while your application is in the foreground. You should stop the queries when your application moves to the background. Downloading Document Files from iCloud When you run a metadata query to learn about an application’s iCloud documents, the query results are placeholder items (NSMetadataItem objects) for document files. The items contain metadata about the file, such as its URL and its modification date. The document file is not in the iCloud container directory. The actual data for a document is not downloaded until one of the following happens: ● Your application attempts to open or access the file, such as by calling openWithCompletionHandler:. ● Your application callsthe NSFileManagermethod startDownloadingUbiquitousItemAtURL:error: to download the data explicitly. Because downloading large document files from iCloud might result in a perceptible delay in displaying the document data, you should indicate to the user that the download has begun (for example, show “loading” or “updating”) and that the file is not currently accessible. Remove this indication when the download has completed. Note: The NSURLUbiquitousItemIsDownloadedKey associated with the document file’s URL tells you the document’s current download status. You can retrieve the value of this key using the getResourceValue:forKey:error: method of the NSURL class. Other keys are also available to tell you related information about the upload and download status of the file. For more information, see NSURL Class Reference . Opening a Document The sample document-based application lists known documents in a table view. When the user taps a listed document to open it, UITableView invokes the tableView:didSelectRowAtIndexPath: method of its delegate. The implementation of this method, shown in Listing 4-5, is typical for the navigation pattern: The Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36root view controller allocates the next view controller in the sequence—in this case, the view controller presenting document data—and initializes with essential data—in this case, the document’s file URL. Based on whether the device idiom is iPad or iPhone (or iPhone touch), the root view controller adds the view controller to the split view or pushes it on the navigation controller’s stack. Listing 4-5 Responding to a request to open a document -(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath { [self selectFileAtIndexPath:indexPath create:NO]; } -(void)selectFileAtIndexPath:(NSIndexPath*)indexPath create:(BOOL)create { NSArray* fileList = indexPath.section == 0 ? _localFileList : _ubiquitousFileList; DetailViewController* detailViewController = [[DetailViewController alloc] initWithFileURL:[[fileList objectAtIndex:indexPath.row] url] createNewFile:create]; if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad) { self.splitViewController.viewControllers = [NSArray arrayWithObjects:self.navigationController, detailViewController, nil]; } else { [self.navigationController pushViewController:detailViewController animated:YES]; } [detailViewController release]; } In itsinitializer method (notshown), the document’s view controller (DetailViewController in the example) allocates an instance of the UIDocument subclass and initializesit by calling the initWithFileURL: method, passing in the file URL. It assigns the newly created document object to a document property. Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37The final step in opening a document is to call the openWithCompletionHandler: method on the UIDocument object; the document’s view controller in our sample application calls this method in viewWillAppear:, as shown in Listing 4-6. The code checks the document state to verify that the document is closed before attempting to open it—there’s no need to open an already opened document. Listing 4-6 Opening a document -(void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; if (_createFile) { [self.document saveToURL:self.document.fileURL forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) { _textView.text = self.document.text; }]; _createFile = NO; } else { if (self.document.documentState & UIDocumentStateClosed) { [self.document openWithCompletionHandler:nil]; } } } When openWithCompletionHandler: is called, UIDocument reads data from the document file, and the document object itself creates its model objects from the data. At the conclusion of this sequence of actions, the completion handler of the openWithCompletionHandler: method is executed. Although the view controller in the example does not implement the completion block, the completion handler is sometimes used to assign the document data to the document’s view or views for display. (To recall what DetailViewController doesinstead to update document views,see Listing 3-4 (page 25) and accompanying text.) Closing a Document To close a document,send a closeWithCompletionHandler: method to the document object. This method saves the document data, if necessary, and then executes the completion handler in its sole parameter. Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38A good time to close a document is when the document’s view controller is dismissed, such as when the user taps the back button. Before the view controller’s view disappears, the viewWillDisappear: method is invoked. Your view controller subclass can override this method in order to call closeWithCompletionHandler: on the document object, as shown in Listing 4-7. Listing 4-7 Closing a document -(void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.document closeWithCompletionHandler:nil]; } Moving Documents to and from iCloud Storage As noted in “Setting the Preferred Storage Location for Document Files ” (page 30), an application should give its users the option of storing all documents in the local file system (the application sandbox) or in iCloud (the container directory). It stores this option as a user preference and refers to this preference when saving and opening documents. When the user changes the preference, the application should move all document files in the application sandbox to iCloud or move all files in the other direction, depending on the nature of the change. Getting the Location of the iCloud Container Directory When you move a document file from local storage to the Documents subdirectory of the iCloud container directory, its filename is unchanged. The only part of the file-URL path that is different is the part leading up to Documents. To get that part of the path, you need to call the URLForUbiquityContainerIdentifier: method of NSFileManager. Most of the time, you pass nil to this method to get your app’s default container directory. If your app supports multiple containers, you can request containers explicitly by passing in a string with the corresponding iCloud container identifier—a concatenation of your team ID and an application bundle ID, separated by a period. These container identifier strings are the same ones you specify in the Identifier field of your app target’s Summary view in Xcode. It is a good idea to declare a string constant for each of your app’s container identifiers, as in this example: static NSString *UbiquityContainerIdentifier = @"A93A5CM278.com.acme.document.billabong"; The two methods in Listing 4-8 get the iCloud container identifier and append “/Documents” to it. Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39Listing 4-8 Getting the iCloud container directory URL -(NSURL*)ubiquitousContainerURL { return [[NSFileManager defaultManager] URLForUbiquityContainerIdentifier:nil]; } -(NSURL*)ubiquitousDocumentsDirectoryURL { return [[self ubiquitousContainerURL] URLByAppendingPathComponent:@"Documents"]; } Note: For an example of getting the base URL for the application sandbox, see “Composing the File URL and Saving the Document File” (page 31). Moving a Document to iCloud Storage Programmatically, you put a document in iCloud storage by calling the NSFileManager method setUbiquitous:itemAtURL:destinationURL:error:. This method requiresthe file URL of the document file in the application sandbox (source URL) and the destination file URL of the document file in the application’s iCloud container directory. The first parameter takes a Boolean value, which should be YES. Important: You should not call setUbiquitous:itemAtURL:destinationURL:error: from your application’s main thread, especially if the document is not closed. Because this method performs a coordinated write operation on the specified file, calling this method from the main thread can trigger a deadlock with any file presenter monitoring the file. (In addition, this method executing on the main thread can take an indeterminate amount of time to complete.) Instead, call the method in a block running in a dispatch queue other than the main-thread queue. You can always message your main thread after the call finishes to update the rest of your application’s data structures. The method in Listing 4-9 illustrates how to move a document file from an application sandbox to iCloud storage. In the sample application, when the user’s preferred storage location (iCloud or local) changes, this method is called for every document file in the application sandbox. There are roughly three parts to this method: ● Compose the source URL and the destination URL. ● On a secondary dispatch queue: Call the setUbiquitous:itemAtURL:destinationURL:error: method and cache the result, a Boolean value (success) that indicates whether the document file successfully moved to the iCloud container directory. Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40● On the main dispatch queue: If the callsucceeds, update the document’s model objects and its presentation of those objects; if the call does not succeed, log the error (or otherwise handle it). Listing 4-9 Moving a document file to iCloud storage from local storage - (void)moveFileToiCloud:(FileRepresentation *)fileToMove { NSURL *sourceURL = fileToMove.url; NSString *destinationFileName = fileToMove.fileName; NSURL *destinationURL = [self.documentsDir URLByAppendingPathComponent:destinationFileName]; dispatch_queue_t q_default; q_default = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_async(q_default, ^(void) { NSFileManager *fileManager = [[[NSFileManager alloc] init] autorelease]; NSError *error = nil; BOOL success = [fileManager setUbiquitous:YES itemAtURL:sourceURL destinationURL:destinationURL error:&error]; dispatch_queue_t q_main = dispatch_get_main_queue(); dispatch_async(q_main, ^(void) { if (success) { FileRepresentation *fileRepresentation = [[FileRepresentation alloc] initWithFileName:fileToMove.fileName url:destinationURL]; [_fileList removeObject:fileToMove]; [_fileList addObject:fileRepresentation]; NSLog(@"moved file to cloud: %@", fileRepresentation); } if (!success) { NSLog(@"Couldn't move file to iCloud: %@", fileToMove); } }); }); } Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41Removing a Document from iCloud Storage To move a document file from an iCloud container directory to the Documents directory of the application sandbox, follow the same procedure described in “Moving a Document to iCloud Storage” (page 40), except switch the source URL (now the document file in the iCloud container directory) and the destination URL (now the document file in the application sandbox). In addition, the first parameter of the setUbiquitous:itemAtURL:destinationURL:error: method should now be NO. Listing 4-10 shows a method implementing this procedure; it is called for each file in the iCloud container directory, moving it to the application sandbox. Listing 4-10 Moving a document file from iCloud storage to local storage - (void)moveFileToLocal:(FileRepresentation *)fileToMove { NSURL *sourceURL = fileToMove.url; NSString *destinationFileName = fileToMove.fileName; NSURL *destinationURL = [self.documentsDir URLByAppendingPathComponent:destinationFileName]; dispatch_queue_t q_default; q_default = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_async(q_default, ^(void) { NSFileManager *fileManager = [[[NSFileManager alloc] init] autorelease]; NSError *error = nil; BOOL success = [fileManager setUbiquitous:NO itemAtURL:sourceURL destinationURL:destinationURL error:&error]; dispatch_queue_t q_main = dispatch_get_main_queue(); dispatch_async(q_main, ^(void) { if (success) { FileRepresentation *fileRepresentation = [[FileRepresentation alloc] initWithFileName:fileToMove.fileName url:destinationURL]; [_fileList removeObject:fileToMove]; [_fileList addObject:fileRepresentation]; NSLog(@"moved file to local storage: %@", fileRepresentation); } if (!success) { NSLog(@"Couldn't move file to local storage: %@", fileToMove); Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42} }); }); } Monitoring Document-State Changes and Handling Errors A document can go through different states during its runtime life. A state can tell you whether a document is experiencing an error, a version conflict, or some other condition that is not normal. UIDocument declares constants (of type UIDocumentState) to represent document states and sets the documentState property with one of these constants when a change is a document’sstate occurs. Table 4-1 describesthe state constants. Table 4-1 UIDocumentState constants Document state constant What it means The document is open and is experiencing no conflicts or other problems. UIDocumentStateNormal The document is closed. A document is in this state if UIDocument cannot open a document, in which case document properties might not be valid. UIDocumentStateClosed UIDocumentStateInConflict There are versions of the document that are in conflict. UIDocumentStateSavingError An error prevents UIDocument from saving the document. UIDocumentStateEditingDisabled It is not currently safe to allow users to edit the document. UIDocument also posts a notification of type UIDocumentStateChangedNotification when a change in document state occurs. Your application should observe this notification and respond appropriately. The initializer method of the document’s view controller is a good place to add an observer, as shown in Listing 4-11. The observer in this case is the view controller. Listing 4-11 Adding an observer of the UIDocumentStateChangedNotification notification -(id)initWithFileURL:(NSURL*)url createNewFile:(BOOL)createNewFile { NSString* nibName = [[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad ? @"DetailViewController_iPad" : @"DetailViewController_iPhone"; Managing the Life Cycle of a Document Monitoring Document-State Changes and Handling Errors 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43self = [super initWithNibName:nibName bundle:nil]; if (self) { _document = [[ImageNotesDocument alloc] initWithFileURL:url]; // other code here.... [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(documentStateChanged) name:UIDocumentStateChangedNotification object:_document]; } return self; } Be sure to remove the observer from the notification center in the class’s dealloc method. When the document’s state changes, UIDocument posts the UIDocumentStateChangedNotification notification, and the notification center deliversit by invoking the notificationmethod (documentStateChanged in the example). In Listing 4-12, the observing view controller gets the current state from the documentState property and evaluates it. If the state is UIDocumentStateEditingDisabled, it hides the keyboard. If there are conflicts between different versions of the document (UIDocumentStateInConflict), it displays a Show Conflicts button in the document view’s toolbar. (For detailed information on handling document-version conflicts, see “Resolving Document Version Conflicts” (page 51).) Listing 4-12 Evaluating the current document state -(void)documentStateChanged { UIDocumentState state = _document.documentState; [_statusView setDocumentState:state]; if (state & UIDocumentStateEditingDisabled) { [_textView resignFirstResponder]; } if (state & UIDocumentStateInConflict) { [self showConflictButton]; } else { [self hideConflictButton]; [self dismissModalViewControllerAnimated:YES]; } Managing the Life Cycle of a Document Monitoring Document-State Changes and Handling Errors 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44} The notification-handling method also calls a setDocumentState: method implemented by a private view class. This method, shown in Listing 4-13, changes other items of the document view’s toolbar depending on the document state. Listing 4-13 Updating a document’s user interface to reflect its state -(void)setDocumentState:(UIDocumentState)documentState { if (documentState & UIDocumentStateSavingError) { self.unsavedLabel.hidden = NO; self.circleView.image = [UIImage imageNamed:@"Red"]; } else { self.unsavedLabel.hidden = YES; if (documentState & UIDocumentStateInConflict) { self.circleView.image = [UIImage imageNamed:@"Yellow"]; } else { self.circleView.image = [UIImage imageNamed:@"Green"]; } } } If the document could not be saved (UIDocumentStateSavingError), the view controller changesthe status indicator to red and displays Unsaved next to it. If there are conflicting document versions, it makes the status indicator yellow (this is in addition to the Show Conflicts button mentioned earlier). Otherwise, the status indicator is green. Deleting a Document Just as you want to allow users to create a document, you also want to let them delete selected documents. Deletion of a document requires you to do three things: ● Remove the document file from storage (either from the local sandbox or the iCloud container directory). ● Remove the model objects used to represent the document data in memory. Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45● Remove the document data presented in the document view. When you delete a document from storage, your code should approximate what UIDocument doesfor reading and writing operations. It should perform the deletion asynchronously on a background queue, and it should use file coordination. Listing 4-14 illustrates this procedure. It dispatches a task on a background queue that creates an NSFileCoordinator object and calls the coordinateWritingItemAtURL:options:error:byAccessor: method on it. The byAccessor block of this method calls the NSFileManager method for deleting the file, removeItemAtURL:error:. Listing 4-14 Deleting a selected document -(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath { NSMutableArray* fileList = nil; if (indexPath.section == 0) { fileList = self.localFileList; } else { fileList = self.ubiquitousFileList; } NSURL* fileURL = [[fileList objectAtIndex:indexPath.row] url]; dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) { NSFileCoordinator* fileCoordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil]; [fileCoordinator coordinateWritingItemAtURL:fileURL options:NSFileCoordinatorWritingForDeleting error:nil byAccessor:^(NSURL* writingURL) { NSFileManager* fileManager = [[NSFileManager alloc] init]; [fileManager removeItemAtURL:writingURL error:nil]; }]; }); [fileList removeObjectAtIndex:indexPath.row]; [tableView deleteRowsAtIndexPaths:[[NSArray alloc] initWithObjects:&indexPath count:1] withRowAnimation:UITableViewRowAnimationLeft]; } Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46In this example, the user triggers the invocation of the method when he or she taps the Delete button in a row while the table view is in editing mode. Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47The saveless-model feature of the UIDocument class ensures that document data is automatically saved at frequent intervals, relieving users of the need to explicitly save their documents. UIDocument implements much of the behavior for the saveless model, but a document-based application must play its own part to make the feature work. How UIKit Saves Document Data Automatically The saveless model implemented by the UIKit framework for documents has two main parts: a mechanism for marking a document as needing to be saved and a variable period for when the framework checks that flag. Periodically, UIKit callsthe hasUnsavedChanges method of a UIDocument object and evaluatesthe returned value. If the value is YES, it saves the document data to the document file. The period between checks of the hasUnsavedChanges value varies according to several factors, including the rate of input by the user. A document-based application sets the value returned by hasUnsavedChanges indirectly, either by implementing undo and redo or by tracking changesto the document. Change tracking requiresthe application to call the updateChangeCount: method, passing in UIDocumentChangeDone (a constant of type UIDocumentChangeKind). When an application registers an undo action and then sends undo or redo messages to the document’s undo manager, UIDocument calls updateChangeCount: on its behalf. Because giving users the ability to undo and redo changes can be a differentiating feature, that approach is recommended for most applications. Implementing Undo and Redo You can implement undo and redo operations in your application by following the procedures and recommendations in Undo Architecture . Note that UIDocument defines an undoManager property. You can get the default NSUndoManager object by accessing this property, or you can assign your own NSUndoManager object to it. The undo manager must be associated with the UIDocument object through the property in order to enable change tracking and thus automatic saving of document data. Listing 5-1 illustrates an implementation of undo and redo for a text field. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48 Change Tracking and Undo OperationsListing 5-1 Implementing undo and redo for a text field - (void)textFieldDidEndEditing:(UITextField *)textField { self.undoButton.enabled = YES; self.redoButton.enabled = YES; if (textField.tag == 1) { [self setLocationText:textField.text]; } // code for other text fields here.... } - (void)setLocationText:(NSString *)newText { NSString *currentText = _document.location; if (newText != currentText) { [_document.undoManager registerUndoWithTarget:self selector:@selector(setLocationText:) object:currentText]; _document.location = newText; self.locationField.text = newText; } } - (IBAction)handleUndo:(id)sender { [_document.undoManager undo]; if (![_document.undoManager canUndo]) self.undoButton.enabled = NO; } - (IBAction)handleRedo:(id)sender { [_document.undoManager redo]; if (![_document.undoManager canRedo]) self.redoButton.enabled = NO; } Change Tracking and Undo Operations Implementing Undo and Redo 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49Implementing Change Tracking To implement change tracking instead of implementing undo/redo, call the updateChangeCount: method on the UIDocument object at the appropriate points in your code. Just as when you register an undo action, it’s typically at the point where you update the document’s model object with data the user has just entered. The parameter passed in should be a UIDocumentChangeDone constant. Listing 5-2 shows how you might call updateChangeCount: from within a UITextViewDelegate method that is called when a change is made in a text view. Listing 5-2 Updating the change count of a document -(void)textViewDidChange:(UITextView *)textView { _document.documentText = textView.text; [_document updateChangeCount:UIDocumentChangeDone]; } Change Tracking and Undo Operations Implementing Change Tracking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50In an iCloud world, when a user has installed a document-based application on multiple devices or desktop systems, there can be conflicts between different versions of the same document. Recall that an application updates a document file in the local container directory and those changes are then transmitted—usually immediately—to iCloud. But what if this transmission is not immediate? For example, you edit a document using the Mac OS X version of your application, but you’ve also edited the same document using the iPad version of the application—and you did so while the device wasin Airplane Mode. When you switch off Airplane Mode, the local change to the document is transferred to iCloud. iCloud notices a conflict and notifies the application. Learning About Document Version Conflicts As “Monitoring Document-State Changes and Handling Errors” (page 43) describes, your application becomes aware of document-version conflicts by observing the UIDocumentStateChangedNotification notification. If the documentState property changes to UIDocumentStateInConflict, multiple versions of the same document exist. The application isresponsible for resolving those conflicts assoon as possible, with or without the user’s help. You learn about the conflicting versions of a document through two class methods of the NSFileVersion class. The currentVersionOfItemAtURL: method returns an NSFileVersion object representing what’s referred to as the current file ; the current file is chosen by iCloud on some basis as the current “conflict winner” and is the same across all devices. By calling the unresolvedConflictVersionsOfItemAtURL: method, you get an array of NSFileVersion objects; these objects are called conflict versions, and each represents an unresolved version conflict for the file located at the specified URL. NSFileVersion objects can give you information helpful in resolving conflicts, such as modification dates, localized document names, and localized names of saving computers. Strategies for Resolving Document Version Conflicts Your application can follow one of three strategies for resolving document-version conflicts: ● Merge the changes from the conflicting versions. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51 Resolving Document Version Conflicts● Choose one of the document versions based on some pertinent factor, such as the version with the latest modification date. ● Enable the user to view conflicting versions of a document and select the one to use. Which strategy is best to use depends a lot upon your document data. If you can merge the contents of different document versions without introducing contradictory elements, then follow that strategy. Or choose the document version with the latest modification date if your application doesn’tsuffer any loss of data as a result. Generally, you should try to resolve the conflict without involving the user, but for some applications that might not be possible. If an application takes the user-centered approach, it should discreetly inform the user about the version conflict and expose a button or other control that initiates the resolution procedure. “An Example: Letting the User Pick the Version” (page 53) examines the code of an application that lets the user select the document version to use. How to Tell iOS That a Document Version Conflict Is Resolved When your application or its users resolve a document version conflict by picking a version of a document, your application should complete the following steps: ● If the chosen version is a conflict version, replace the current document file with the conflict-version document file. To to this, call the replaceItemAtURL:options:error: method on the NSFileVersion object representing the version, passing in the document’s current-file URL. ● If the chosen version is a conflict version, revert the document so that it displays the new data in the document file To do this, call the UIDocument method revertToContentsOfURL:completionHandler: on the document object, passing in the document’s current-file URL. ● Disassociate all conflict versions with the document’s file URL. To do this, call the NSFileVersion class method removeOtherVersionsOfItemAtURL:error:, passing in the document’s file URL. ● Mark each conflict version as resolved so that iOS doesn’t raise it again as a conflicting version. To do this, set the resolved property of each NSFileVersion object representing a conflict version to YES. This step should always be done last. ● Remove the resolved versions of the document. For any versions you no longer need, call the removeAndReturnError: method of NSFileVersion to reclaim the storage for the file. Document revisions remain on the server until you delete them. Resolving Document Version Conflicts How to Tell iOS That a Document Version Conflict Is Resolved 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52An Example: Letting the User Pick the Version Our sample document-based application is a simple text editor. It would be difficult for such an application to locate and merge textual differences in conflicting versions of the document, and even if it did, the resulting document might not be what the user wants. The application could pick the document version with the most recent modification date, but then again there’s no way to be certain that is the version the user wants. A good conflict-resolution strategy in this case is to let the user, who is most familiar with the document’s contents, pick the version she or he wants. You might recall the code shown in Listing 6-1 from “Monitoring Document-State Changes and Handling Errors” (page 43). This code shows the method of the document’s view controller that handles the UIDocumentStateChangedNotification notification posted by UIDocument when there is a change in document state. If the new document state is UIDocumentStateInConflict, the view controller shows a Resolve Conflicts button in a custom status view. (It also sets the color of the status indicator to red.) Listing 6-1 Detecting a conflict in document versions -(void)documentStateChanged { UIDocumentState state = _document.documentState; [_statusView setDocumentState:state]; if (state & UIDocumentStateEditingDisabled) { [_textView resignFirstResponder]; } if (state & UIDocumentStateInConflict) { [self showConflictButton]; // <------ Shows "Resolve Conflicts" button } else { [self hideConflictButton]; [self dismissModalViewControllerAnimated:YES]; } } When the user taps the button, UIKit invokes the method in Listing 6-2. This method displays modally the view of a custom conflict-resolver view controller. Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53Listing 6-2 Showing the user interface for resolving document version conflicts -(void)conflictButtonPushed { ConflictResolverViewController* conflictResolver = [[ConflictResolverViewController alloc] initWithURL:_document.fileURL delegate:self]; [self presentViewController:conflictResolver animated:YES completion:nil]; [conflictResolver release]; } The ConflictResolverViewController object creates a page view controller (UIPageViewController object) that allows user to page between, and examine, the current-file document and each conflict-version document. In the tool bar of each document view is a Select Version button. If the user taps that button, one of the two custom delegation methods shown in Listing 6-3 is called, depending on whether the chosen document is the current-file document or a conflict-version document. Listing 6-3 Resolving a document version conflict -(void)conflictResolver:(ConflictResolverViewController *)conflictResolver didResolveWithFileVersion:(NSFileVersion *)fileVersion { [self dismissViewControllerAnimated:YES completion:nil]; [fileVersion replaceItemAtURL:_document.fileURL options:0 error:nil]; [NSFileVersion removeOtherVersionsOfItemAtURL:_document.fileURL error:nil]; [_document revertToContentsOfURL:_document.fileURL completionHandler:nil]; NSArray* conflictVersions = [NSFileVersion unresolvedConflictVersionsOfItemAtURL:_document.fileURL]; for (NSFileVersion* fileVersion in conflictVersions) { fileVersion.resolved = YES; } } -(void)conflictResolverDidResolveWithCurrentVersion:(ConflictResolverViewController*)conflictResolver { [self dismissViewControllerAnimated:YES completion:nil]; [NSFileVersion removeOtherVersionsOfItemAtURL:_document.fileURL error:nil]; NSArray* conflictVersions = [NSFileVersion unresolvedConflictVersionsOfItemAtURL:_document.fileURL]; Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54for (NSFileVersion* fileVersion in conflictVersions) { fileVersion.resolved = YES; } } These methods illustrate the steps described in “How to Tell iOS That a Document Version Conflict Is Resolved” (page 52). If the chosen document is a conflict version, the delegate calls replaceItemAtURL:options:error: on the passed-in NSFileVersion object to replace the document file in the iCloud container directory with the chosen document. The delegate then enumerates the array containing NSFileVersion objectsrepresenting all conflict versions of the document and setsthe resolved property of each object to YES. It then asks NSFileVersion to remove all other conflict versions of the document associated with the document’sfileURL and calls revertToContentsOfURL:completionHandler: to revert the displayed document to the new contents of the document file. The second delegation method, invoked when the current document file is selected, is much simpler. It sets the resolved property of all NSFileVersion objects representing conflict versions to YES and removes all conflict versions associated with the document file URL. Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55This table describes the changes to Document-Based App Programming Guide for iOS . Date Notes 2012-09-19 Updated the document's iCloud-related information. Changed the operator used in the predicate of metadata query searches to LIKE. 2012-01-09 New document that explains how to create an iOS application whose documents are integrated with iCloud storage. 2011-10-12 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, iPad, iPhone, Mac, Mac OS, Objective-C, OS X, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. iCloud is a service mark of Apple Inc., registered in the U.S. and other countries. OpenGL is a registered trademark of Silicon Graphics, Inc. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Core Text Programming GuideContents Introduction 4 Organization of This Document 4 See Also 4 Core Text Overview 6 OS X Text Technologies 6 Design Goals and Principles 7 Core Text Features and Capabilities 8 System Data Types and Services 8 Core Text Input 8 Characters and Glyphs 9 Core Text Objects 10 Layout Objects 10 Font Objects 13 Common Operations 15 Simple Paragraphs 15 Simple Text Labels 16 Columnar Layout 17 Manual Line Breaking 20 Font Creation and Storage 21 Accessing Font Metrics 25 Creating Related Fonts 27 Document Revision History 29 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 2Figures and Listings Core Text Overview 6 Figure 1-1 Glyphs of the character A 9 Figure 1-2 Ligatures 9 Figure 1-3 Text layout data flow 10 Figure 1-4 A frame object containing lines and glyph runs 12 Figure 1-5 Creating a font from a font descriptor 14 Common Operations 15 Listing 2-1 Typesetting a simple paragraph 15 Listing 2-2 Typesetting a simple text label 17 Listing 2-3 Performing columnar text layout 18 Listing 2-4 Performing manual line breaking 20 Listing 2-5 Creating a font descriptor from a name and point size 21 Listing 2-6 Creating a font descriptor from a family and traits 21 Listing 2-7 Creating a font from a font descriptor 23 Listing 2-8 Serializing a font 23 Listing 2-9 Creating a font from serialized data 24 Listing 2-10 Calculating line height 26 Listing 2-11 Getting glyphs for characters 26 Listing 2-12 Changing traits of a font 27 Listing 2-13 Converting a font to another family 28 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 3Core Text is an advanced, low-level technology for laying out text and handling fonts. It is designed for high performance and ease of use. The Core Text API, introduced in OS X v10.5, is accessible from all OS X application environments. It is also available in iOS 3.2. The Core Text layout engine is designed specifically to make simple text layout operations easy to do and to avoid side effects. The Core Text font programming interface is complementary to the Core Text layout engine and is designed to handle Unicode fonts natively, unifying disparate OS X font facilities into a single comprehensive programming interface. This document is intended for developers who need to do text layout and font handling at a low level. If you can develop your application using higher-level constructs, such as NSTextView, then you should use the Cocoa text system, introduced in Text System Overview. If, on the other hand, you need to render text directly into a Core Graphics context, then you should use Core Text. More information about the position of Core Text among other OS X text technologies is presented in “OS X Text Technologies” (page 6). Important: This document has not been updated to address the use of Core Text in iOS 3.2. Organization of This Document This document is organized into the following chapters: “Core Text Overview” (page 6) describes the Core Text system in terms of its design goals and feature set. It also introducesthe opaque typesthat encapsulate the text layout and font handling capabilities of the system. “Common Operations” (page 15) presents snippets of code with commentary illustrating typical uses of the main Core Text opaque types. See Also In addition to this document, there are several that cover more specific aspects of Core Text or describe the software services used by Core Text. 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 4 Introduction● Core Text Reference Collection provides complete reference information for the Core Text layout and font API. ● CoreTextTest is a sample code project thatshows how to use Core Text in the context of a complete Carbon application. ● CoreTextArcCocoa is a sample code project that illustrates the use of fonts, lines, and runs in a Core Text Cocoa application. ● Core Foundation Design Concepts and Core Foundation Framework Reference describe Core Foundation, a framework that provides abstractions for common data types and fundamental software services used by Core Text. The following documents provide entry points to the documentation describing the Cocoa text system. ● Text System Overview gives an introduction to the Cocoa text system. ● Text Layout Programming Guide for Cocoa describes the Cocoa text layout engine. Introduction See Also 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 5The Core Text framework is an advanced, low-level technology for laying out text and handling fonts. Designed for high performance and ease of use, the Core Text layout engine is up to twice as fast as ATSUI (Apple Type Services for Unicode Imaging). The Core Text layout API is simple, consistent, and tightly integrated with Core Foundation, Core Graphics, and Cocoa. The Core Text font API is complementary to the Core Text layout engine. Core Text font technology is designed to handle Unicode fonts natively, bridging the gap between Carbon and Cocoa font references, and providing efficient font handling for Core Text layout. Core Text brings the capabilities and coherent design of Cocoa text and fonts to a broader, lower-level client base. OS X Text Technologies The Macintosh operating system has provided sophisticated text handling and typesetting capabilities from its beginning. In fact, these features sparked the desktop publishing revolution. Core Text is the most modern text-handling technology on the platform. It is designed specifically for OS X and is written in C, so it can be called from any language in the system. It is positioned as a core technology to provide consistent, high-performance textservicesto other frameworksthroughout the system, and the Core Text API is accessible to applications that need to use it directly. Core Text resides in the Application Services umbrella framework (ApplicationServices) so that it is callable from both Carbon and Cocoa and has all of the lower-level services it needs. Core Text is not meant to replace the Cocoa text system, although it provides the underlying implementation for many Cocoa text technologies. If you can deal with high-level constructs, such as text views, you can probably use Cocoa. For this reason, Cocoa developers typically have no need to use Core Text directly. Carbon developers, on the other hand, will find Core Text faster and easier to use, in many cases, than preexisting OS X text layout and font APIs. To decide whether Core Text isthe right OS X text technology for your application, apply the following guidelines: ● If you can, use Cocoa text. The NSTextView class is the most advanced, full-featured, flexible text view in OS X. For small amounts of text, use NSTextField. ● To display web content in your application, use Web Kit. ● If you need to use Carbon only, consider using NSTextView with HICocoaView. 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 6 Core Text Overview● If you need a lower-level API for drawing any kind of text into a Quartz graphics context (CGContext), consider using Core Text directly. Generally speaking, Core Text is for applications that need a low-level text-handling technology correlating with the Core Graphics framework (Quartz). If you work directly with Quartz and you need to draw some text, use Core Text. If, for example, you have your own page layout engine—you have some text and you know where it needs to go in your view—you can use Core Text to generate the glyphs and position them relative to each other with all the features of fine typesetting,such as kerning, ligatures, line-breaking, and justification. Design Goals and Principles Core Text is designed to provide the following benefits: ● A comprehensive, unified set of text-layout and font APIs ● High performance and ease of use ● Tight integration with Cocoa, Core Foundation, and Core Graphics (Quartz) ● Native Unicode handling ● 64-bit application support ● Clean, simple, consistent API design ● Simple interfaces for simple operations ● A flexible interface to layout and glyph data ● A predictable cost structure and rational division of labor A primary design goal of Core Text layout is to make simple things easy to do. So, for example, if you want to draw a paragraph of text or a simple text label on the screen, you don’t need much code. A corollary principle of the Core Text design is that clients are not required to pay for features they don’t use. The objects defined by Core Text opaque types provide a progression from simplicity to complexity, in terms of their use and interface. That is, higher-level objects do more for you, and so they are easier to use (although they may be more complex internally). For example, the highest-level object in Core Text is the framesetter, which fills a path (defined by a CGPath object representing a rectangle) with text. The framesetter object uses other Core Text objects, such as typesetter, line, and glyph run objects, to accomplish its work: creating frame objects, which are lines of glyphs laid out within a shape. Clients who simply need to lay out a paragraph need only work with the framesetter. Clients who need to intervene in the text layout process at a lower level can deal with lower level objects, such as line objects. Line objects can draw themselves individually or be used to obtain glyph information. With Core Text you use the highest-level object you can to get your job done. Core Text Overview Design Goals and Principles 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 7Core Text Features and Capabilities Core Text performs text layout and font access. The text layout engine generates glyphs from characters and positionsthe glyphsinto glyph runs, lines, and multiline frames. It also provides glyph- and layout-related data, such as glyph positioning and measurement of lines and frames. The API handles character attributes and paragraph styles, including various types of tab styles and positioning. The Core Text font API bringsto Carbon developersthe same capabilities enjoyed by Cocoa developersthrough NSFont and NSFontDescriptor. The API provides font viewing and selecting. It provides font references, font descriptors (objects that encapsulate font data sufficient to instantiate a font reference), and easy access to font data. It also provides support for multiple master fonts, font variations, font cascading, and font linking. The Core Text font API is designed to be very complete, so that you don’t have to go to different layers to do what you need to do. System Data Types and Services Core Text uses system data types and services wherever possible, and you use the same conventions that pertain to the other core frameworks in OS X. So, for example, Core Text uses Core Foundation objects for many input and output parameters, enabling them to be retained, released, and stored in Core Foundation collection classes. Other objects handled by Core Text are provided by the Core Graphics framework, for example, CGPath objects. Moreover, because many Core Foundation objects are toll-free bridged with Cocoa Foundation objects, you can usually use Foundation objects in place of Core Foundation objects passed into Core Text functions. Use of these standard types and toll-free bridging ensure that you don’t have to perform expensive type conversions to get data into and out of Core Text. Core Text is built to work directly with Core Graphics, also known as Quartz, which is the high-speed graphics rendering engine that handles two-dimensional imaging at the lowest level in OS X. Quartz is the only way to get glyphs drawn at a fundamental level, and, because Core Text provides all data in a form directly usable by Quartz, the result is high-performance text rendering. Core Text Input The input type most basic to Core Text is the Core Foundation attributed string, represented by CFAttributedStringRef or its Cocoa counterpart, NSAttributedString, which are toll-free bridged. The attributes are key-value pairs that define style characteristics of the characters in the string, which are grouped in rangesthatshare the same attributes. Examples of text attributes are font and color. The attributesthemselves are passed into attributed strings, and retrieved from them, using CFDictionary objects. (Though CFDictionaryRef and NSDictionary are also toll-free bridged, the individual attribute objects stored in the dictionary may not be.) The typesetting mechanism in Core Text uses the information in the attributed string to perform character-to-glyph conversion. Core Text Overview Core Text Features and Capabilities 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 8Characters and Glyphs One of the most important capabilities of fine typesetting is character-to-glyph conversion. It is important to distinguish between characters and glyphsin discussing a text layout engine. Characters are essentially numbers representing code points in a character set or encoding scheme, such as Unicode, the character set used for all text in OS X. The Unicode standard provides a unique number for every character in every modern written language in the world, independent of the platform, program, and programming language being used. A glyph is a graphic shape used to depict a character. Glyphs are also represented by numeric codes, called glyph codes, that are indexesinto a particular font. Glyphs are selected during composition and layout processing by the character-to-glyph conversion process. There are any number of glyphs that correspond to a particular character. For example, the character“uppercase A” has different glyphsfor different typefaces(such as Helvetica and Times) and type styles (such as bold and italic). Figure 1-1 shows various glyphs, all of which represent an “uppercase A.“ Figure 1-1 Glyphs of the character A Moreover, the correspondence between characters and glyphs is not one to one, and the context within which a character appears can affect the glyph chosen to represent it. For example, in many fonts an “f” and “l” appearing side-by-side in a character string are replaced by a ligature, which is a single glyph depicting the letters joined together. Figure 1-2 shows two examples of individual characters and the single-glyph ligatures often used when they are adjacent. Character-to-glyph conversion is a complex and difficult task that Core Text performs quickly and efficiently. Figure 1-2 Ligatures + = + = Core Text Overview Core Text Features and Capabilities 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 9Core Text Objects Core Text objects are based on the corresponding opaque types defined by the framework. In the sections that follow, you learn how the primary Core Text objects interact to accomplish various client tasks. Layout Objects Layout objects make up the Core Text layout engine. This section discusses the primary layout objects: framesetter, frame, typesetter, line, and glyph run objects. In addition this section briefly discusses the other Core Text layout objects: paragraph styles, text tabs, and glyph info objects. Framesetters and Frames The framesetter is the highest-level object in the Core Text layout engine, represented by the CTFramesetter opaque type. A framesetter generates text frames by filling a path with text. That is, CTFramesetter is an object factory for CTFrame objects that are ready to draw. The framesetter takes an attributed string object (CFAttributedString) and a shape descriptor object (CGPath) and calls into the typesetter to create line objects that fill that shape. The output is a frame object containing an array of lines. This array of lines is a paragraph, a multiline layout. The frame can draw itself directly into a graphic context. You can also retrieve the lines to manipulate before drawing. For example, you might adjust their positioning. Figure 1-3 shows the data flow among objects performing text layout. Figure 1-3 Text layout data flow CFAttributedString CTFramesetter CTTypesetter CTFrame CGPath The framesetter applies paragraph styles to the frame text as it is laid out. Paragraph styles are represented in Core Text by objects storing attributes that affect paragraph layout. Among these attributes are alignment, tab stops, writing direction, line-breaking mode, and indentation settings. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 10It’s advantageousto use the framesetter to perform the common operation of typesetting a multiline paragraph because it handles all of the details of producing frames, instantiating other objects, such as the typesetter, as needed. The CTFramesetter opaque type provides functions to create a framesetter with an attributed string, to create frame objects, and to return itstypesetter. As with all Core Text objects, CTFramesetter can also return its Core Foundation type identifier. Typesetters A typesetter performsthe fundamental text layout operations of character-to-glyph conversion and positioning of those glyphs into lines. That is, it determines which glyphs to use and where to place them relative to each other, producing line objects. Typesetters are represented by the CTTypesetter opaque type. The typesetter also suggests line breaks. It finds how many glyphs can fit within a single line within a given space. It then determines the length of the line by using word breaks, word wrapping, or finer-grained cluster breaks. Simple word wrapping is the default method of creating line breaks. The framesetter instantiates a typesetter and uses it to create the line objects used to fill a frame. You can also use a typesetter directly, as described in “Manual Line Breaking” (page 20). Lines and Glyph Runs A line object represents a line of text and is represented in Core Text by the CTLine opaque type. A CTLine object contains an array of glyph runs. Line objects are created by the typesetter during a framesetting operation and, like frames, can draw themselves directly into a graphics context. Line objects hold the glyphs that are the result of the text layout process, created from text and style information. A line corresponds to a range of characters. It could be miles long or, more often, one of a series of lines contained within a paragraph. The paragraph is represented in Core Text by a CTFrame object, which contains the paragraph’s line objects. Accordingly, you can retrieve line objects from their frame object. A line object contains glyph-run objects, represented by the CTRun opaque type. A glyph run is a set of consecutive glyphs sharing the same attributes and direction. The typesetter creates glyph runs as it produces lines from character strings, attributes, and font objects. That is, a line is constructed of one or more glyphs Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 11runs. Glyph runs can draw themselves into a graphic context, if desired, although most clients have no need to interact directly with glyph runs. Figure 1-4 shows the conceptual hierarchy of a frame object containing line objects that, in turn, contain glyph-run objects. Figure 1-4 A frame object containing lines and glyph runs CTRun CTLine CTFrame a glyph run CTLine has a convenience method for creating a freestanding line independent of a frame, CTLineCreateWithAttributedString. You can use this method to create a line object directly from an attributed string without needing to create and manage a typesetter. Without a typesetter, however, there’s no way to calculate line breaks, so this method is meant for a single line only (for example, creating a text label). After you have a line object, you can do a number of things with it. For example, you can have the line create a justified or truncated copy of itself, and you can ask the line for pen offsets for various degrees of flushness. You can use these pen offsets to draw the line with left, right, or centered alignments. You can also ask the line for measurements, such as its image bounds and typographic bounds. Image bounds represent the rectangle tightly enclosing the graphic shapes of the glyphs actually appearing in the line. Typographic bounds include the height of the ascenders in the font and the depth of its descenders, regardless of whether those features appear in the glyphs in a given line. Like a frame object, a line object is ready to draw. You simply set the text position in a Core Graphics context and have the line draw itself. Core Text uses the same placement strategy as Quartz, setting the origin of the text on the text baseline. In Quartz, you specify the location of text in user-space coordinates. The text matrix specifies the transform from text space to user space. The text position is stored in the tx and ty variables of the text matrix. When you first create a graphics context, it initializesthe text matrix to the identity matrix; thustext-space coordinates are initially the same as user-space coordinates. Quartz conceptually concatenates the text matrix with the current transformation matrix and other parametersfrom the graphicsstate to produce the final text-rendering matrix, that is, the matrix actually used to draw the text on the page. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 12Other Layout Objects In addition to the framesetter, frame, typesetter, and line objects, Core Text provides other objects to complete the text layout process: paragraph style, text tab, and glyph info objects. Paragraph style objects encapsulate paragraph or ruler attributes in an attributed string and are represented by the CTParagraphStyle opaque type. A paragraph style object is a complex attribute value in an attributed string, storing a number of subattributes that affect paragraph layout for the characters of the string. Among these subattributes are alignment, tab stops, writing direction, line-breaking mode, and indentation settings. The CTTextTab opaque type represents a tab stop in a paragraph style, storing an alignment type and location. The CTGlyphInfo opaque type enables you to override a font's specified mapping from Unicode to the glyph ID. Font Objects Font objects are those Core Text objects dealing directly with fonts: the font reference itself, font descriptor objects, and font collection objects. Fonts Fonts provide assistance in laying out glyphs relative to one another and are used to establish the current font when drawing in a graphics context. The Core Text font opaque type (CTFont) is a specific font instance that encapsulates a lot of information. Its reference type, CTFontRef, is toll-free bridged with NSFont. When you create a CTFont object, you typically specify (or use a default) pointsize and transformation matrix, which gives the font instance specific characteristics. You can then query the font object for many kinds of information about the font at that particular point size, such as character-to-glyph mapping, encodings, font metric data, and glyph data, among other things. Font metrics are parameters such as ascent, descent, leading, cap height, x-height, and so on. Glyph data includes parameters such as bounding rectangles and glyph advances. There are many ways to create font references. The preferred method is from a font descriptor using CTFontCreateWithFontDescriptor. You can also use a number of conversion APIs, depending on what you have to start with. For example, you can use the PostScript name of the typeface (CTFontCreateWithName), an ATS font reference (CTFontCreateWithPlatformFont), a Core Graphics font reference (CTFontCreateWithGraphicsFont), or a QuickDraw font reference (CTFontCreateWithQuickdrawInstance). There’s also CTFontCreateUIFontForLanguage, which creates a reference for the user-interface font for the application you’re using in the localization you’re using. Core Text font references provide a sophisticated, automatic font-substitution mechanism called font cascading. This mechanism takes font traits into account, so it does a better job than previous schemes of picking an appropriate font to substitute for a missing font. Font cascading is based on cascade lists, which are arrays of ordered font descriptors. There is a system default cascade list (which is polymorphic, based on the user's language setting and current font) and a font cascade list that is specified at font creation time. Using the Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 13information in the font descriptors, the cascading mechanism can match fonts according to style as well as matching characters. The CTFontCreateForString function uses cascade lists to pick an appropriate font to encode a given string. You specify and retrieve font cascade lists using the kCTFontCascadeListAttribute property. Font Descriptors Font descriptors, represented by the CTFontDescriptor opaque type, provide a mechanism to describe a font completely with a dictionary of attributes. CTFontDescriptorRef istoll-free bridged to NSFontDescriptor. The attributes are properties such as PostScript name, family, and style, and traits such as bold, italic, and monospace. The font descriptor can then be used to create or modify a CTFont object. Font descriptors can be serialized and stored in a document to provide persistence for fonts. Figure 1-5 illustrates the font system using a font descriptor to create a specific font instance. Figure 1-5 Creating a font from a font descriptor Font System CTFontDescriptor CTFont A font descriptor can also be considered as a query into the font system. You can create a font descriptor with an incomplete specification, that is, with one or just a few values in the attribute dictionary, and the system will choose the most appropriate font from those available. The system can also give you a complete list of font descriptors matching your query via CTFontDescriptorCreateMatchingFontDescriptors. Font Collections Font collections are unions of font descriptors, that is, groups of font descriptors taken as a single object. A font collection is represented by the CTFontCollection opaque type. Font collections provide the capabilities of font enumeration, accessto global and custom font collections, and accessto the font descriptors comprising the collection. You can, for example, create a font collection of all the fonts available in the system by calling CTFontCollectionCreateFromAvailableFonts, and you can use the collection to obtain an array of all of the member font descriptors. There is also a function that takes a callback parameter used to sort the returned array of font descriptors. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 14This chapter describes some common text-layout and font-handling operations and shows, through portions of sample code, how they can be accomplished using Core Text. In addition to the code fragments in this chapter, see the following sample code applications that use Core Text: ● CoreTextTest shows how to use Core Text to typeset blocks of text with varying attributes in the context of a complete Carbon application. ● CoreTextArcCocoa illustrates the use of Core Text fonts, lines, and runs in a Cocoa application that sets type along an arched path. Simple Paragraphs One of the most common operations in typesetting is laying out a multiline paragraph within an arbitrarily sized rectangular area. Core Text makes this operation easy, requiring only a few lines of Core Text–specific code. To lay out the paragraph, you need a graphics context to draw into, a rectangular path to provide the area where the text is laid out, and an attributed string. Most of the code in this example is required to create and initialize the context, path, and string. After that is done, Core Text requires only three lines of code to do the layout. Listing 2-1 uses Cocoa to simplify initialization of the graphics context. To see how that operation is done in Carbon, see the CoreTextTest sample code or “Graphics Contexts“ in the Quartz 2D Programming Guide . Listing 2-1 Typesetting a simple paragraph // Initialize a graphics context and set the text matrix to a known value. CGContextRef context = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGContextSetTextMatrix(context, CGAffineTransformIdentity); // Initialize a rectangular path. CGMutablePathRef path = CGPathCreateMutable(); CGRect bounds = CGRectMake(10.0, 10.0, 200.0, 200.0); CGPathAddRect(path, NULL, bounds); 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 15 Common Operations// Initialize an attributed string. CFStringRef string = CFSTR("We hold this truth to be self-evident, that everyone is created equal."); CFMutableAttributedStringRef attrString = CFAttributedStringCreateMutable(kCFAllocatorDefault, 0); CFAttributedStringReplaceString (attrString, CFRangeMake(0, 0), string); // Create a color and add it as an attribute to the string. CGColorSpaceRef rgbColorSpace = CGColorSpaceCreateDeviceRGB(); CGFloat components[] = { 1.0, 0.0, 0.0, 0.8 }; CGColorRef red = CGColorCreate(rgbColorSpace, components); CGColorSpaceRelease(rgbColorSpace); CFAttributedStringSetAttribute(attrString, CFRangeMake(0, 50), kCTForegroundColorAttributeName, red); // Create the framesetter with the attributed string. CTFramesetterRef framesetter = CTFramesetterCreateWithAttributedString(attrString); CFRelease(attrString); // Create the frame and draw it into the graphics context CTFrameRef frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(0, 0), path, NULL); CFRelease(framesetter); CTFrameDraw(frame, context); CFRelease(frame); Simple Text Labels Another very common typesetting operation is drawing a single line of text to use as a label for a user-interface element. In Core Text thisrequires only two lines of code, one to create the line object with an attributed string and another to draw the line into a graphic context. Common Operations Simple Text Labels 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 16Listing 2-2 omits initialization of the plain text string, font, and graphics context, but it shows how to create an attributes dictionary and use it to create the attributed string. To see how to create a Core Text font, see “Font Creation and Storage” (page 21). Listing 2-2 Typesetting a simple text label CFStringRef string; CTFontRef font; CGContextRef context; // Initialize string, font, and context CFStringRef keys[] = { kCTFontAttributeName }; CFTypeRef values[] = { font }; CFDictionaryRef attributes = CFDictionaryCreate(kCFAllocatorDefault, (const void**)&keys, (const void**)&values, sizeof(keys) / sizeof(keys[0]), &kCFTypeDictionaryCallBacks, &kCFTypeDictionaryValueCallbacks); CFAttributedStringRef attrString = CFAttributedStringCreate(kCFAllocatorDefault, string, attributes); CFRelease(string); CFRelease(attributes); CTLineRef line = CTLineCreateWithAttributedString(attrString); // Set text position and draw the line into the graphics context CGContextSetTextPosition(context, 10.0, 10.0); CTLineDraw(line, context); CFRelease(line); Columnar Layout Laying out text in multiple columns is another common typesetting operation. Strictly speaking, Core Text itself only performs the layout of one column at a time and does not calculate the column sizes or locations. You do those operations before calling Core Text to lay out the text within the rectangular path area you’ve calculated. In this sample, Core Text, in addition to laying out the text in each column, also provides the subrange within the text string for each column. Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 17Listing 2-3 mixes Cocoa method calls in Objective-C with function calls into Carbon frameworks and Core Text. It includes an implementation of the drawRect: method of NSView, which calls the local createColumns function, defined first in this listing. This code resides in an NSView subclass in a Cocoa document-based application. The NSView subclassincludes an attributedString accessor method, which is notshown here but is called in this listing to return the attributed string to be laid out. Listing 2-3 Performing columnar text layout - (CFArrayRef)createColumns { CGRect bounds = CGRectMake(0, 0, NSWidth([self bounds]), NSHeight([self bounds])); int column; CGRect* columnRects = (CGRect*)calloc(_columnCount, sizeof(*columnRects)); // Start by setting the first column to cover the entire view. columnRects[0] = bounds; // Divide the columns equally across the frame's width. CGFloat columnWidth = CGRectGetWidth(bounds) / _columnCount; for (column = 0; column < _columnCount - 1; column++) { CGRectDivide(columnRects[column], &columnRects[column], &columnRects[column + 1], columnWidth, CGRectMinXEdge); } // Inset all columns by a few pixels of margin. for (column = 0; column < _columnCount; column++) { columnRects[column] = CGRectInset(columnRects[column], 10.0, 10.0); } // Create an array of layout paths, one for each column. CFMutableArrayRef array = CFArrayCreateMutable(kCFAllocatorDefault, _columnCount, &kCFTypeArrayCallBacks); for (column = 0; column < _columnCount; column++) { CGMutablePathRef path = CGPathCreateMutable(); CGPathAddRect(path, NULL, columnRects[column]); CFArrayInsertValueAtIndex(array, column, path); CFRelease(path); Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 18} free(columnRects); return array; } - (void)drawRect:(NSRect)rect { // Draw a white background. [[NSColor whiteColor] set]; [NSBezierPath fillRect:[self bounds]]; // Initialize the text matrix to a known value. CGContextRef context = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGContextSetTextMatrix(context, CGAffineTransformIdentity); CTFramesetterRef framesetter = CTFramesetterCreateWithAttributedString( (CFAttributedStringRef)[self attributedString]); CFArrayRef columnPaths = [self createColumns]; CFIndex pathCount = CFArrayGetCount(columnPaths); CFIndex startIndex = 0; int column; for (column = 0; column < pathCount; column++) { CGPathRef path = (CGPathRef)CFArrayGetValueAtIndex(columnPaths, column); // Create a frame for this column and draw it. CTFrameRef frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(startIndex, 0), path, NULL); CTFrameDraw(frame, context); // Start the next frame at the first character not visible in this frame. CFRange frameRange = CTFrameGetVisibleStringRange(frame); startIndex += frameRange.length; Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 19CFRelease(frame); } CFRelease(columnPaths); } Manual Line Breaking You usually don't need to do manual line breaking unless you have a special hyphenation process or a similar requirement. A framesetter performs line breaking automatically. Listing 2-4 shows how to create a typesetter, an object used by the framesetter, and use it directly to find appropriate line breaks and create a typeset line manually. This sample also shows how to center the line before drawing. Listing 2-4 Performing manual line breaking double width; CGContextRef context; CGPoint textPosition; CFAttributedStringRef attrString; // Initialize those variables. // Create a typesetter using the attributed string. CTTypesetterRef typesetter = CTTypesetterCreateWithAttributedString(attrString); // Find a break for line from the beginning of the string to the given width. CFIndex start = 0; CFIndex count = CTTypesetterSuggestLineBreak(typesetter, start, width); // Use the returned character count (to the break) to create the line. CTLineRef line = CTTypesetterCreateLine(typesetter, CFRangeMake(start, count)); // Get the offset needed to center the line. float flush = 0.5; // centered double penOffset = CTLineGetPenOffsetForFlush(line, flush, width); // Move the given text drawing position by the calculated offset and draw the line. CGContextSetTextPosition(context, textPosition.x + penOffset, textPosition.y); CTLineDraw(line, context); Common Operations Manual Line Breaking 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 20// Move the index beyond the line break. start += count; Font Creation and Storage The example function in Listing 2-5 creates a font descriptor from a PostScript font name and a float specifying the point size. Listing 2-5 Creating a font descriptor from a name and point size CTFontDescriptorRef CreateFontDescriptorFromName(CFStringRef iPostScriptName, CGFloat iSize) { assert(iPostScriptName != NULL); return CTFontDescriptorCreateWithNameAndSize(iPostScriptName, iSize); } The example function in Listing 2-6 creates a font descriptor from a font family name and font traits. Listing 2-6 Creating a font descriptor from a family and traits CTFontDescriptorRef CreateFontDescriptorFromFamilyAndTraits(CFStringRef iFamilyName, CTFontSymbolicTraits iTraits, CGFloat iSize) { CTFontDescriptorRef descriptor = NULL; CFMutableDictionaryRef attributes; assert(iFamilyName != NULL); // Create a mutable dictionary to hold our attributes. attributes = CFDictionaryCreateMutable(kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); check(attributes != NULL); if (attributes != NULL) { CFMutableDictionaryRef traits; Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 21CFNumberRef symTraits; // Add a family name to our attributes. CFDictionaryAddValue(attributes, kCTFontFamilyNameAttribute, iFamilyName); // Create the traits dictionary. symTraits = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &iTraits); check(symTraits != NULL); if (symTraits != NULL) { // Create a dictionary to hold our traits values. traits = CFDictionaryCreateMutable(kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); check(traits != NULL); if (traits != NULL) { // Add the symbolic traits value to the traits dictionary. CFDictionaryAddValue(traits, kCTFontSymbolicTrait, symTraits); // Add the traits attribute to our attributes. CFDictionaryAddValue(attributes, kCTFontTraitsAttribute, traits); CFRelease(traits); } CFRelease(symTraits); } // Create the font descriptor with our attributes and input size. descriptor = CTFontDescriptorCreateWithAttributes(attributes); check(descriptor != NULL); CFRelease(attributes); } // Return our font descriptor. return descriptor; Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 22} The example function in Listing 2-7 creates a font from a provided font descriptor. It calls CTFontCreateWithFontDescriptor, passing NULL for the matrix parameter to specify the default (identity) matrix. Listing 2-7 Creating a font from a font descriptor CTFontRef CreateFont(CTFontDescriptorRef iFontDescriptor, CGFloat iSize) { check(iFontDescriptor != NULL); // Create the font from the font descriptor and input size. Pass // NULL for the matrix parameter to use the default matrix (identity). return CTFontCreateWithFontDescriptor(iFontDescriptor, iSize, NULL); } The example function in Listing 2-8 creates XML data to serialize a font for embedding in a document. Alternatively, and preferably, NSArchiver could be used. This is just one way to accomplish this task, but it preserves all data from the font needed to re-create the exact font at a later time. Listing 2-8 Serializing a font CFDataRef CreateFlattenedFontData(CTFontRef iFont) { CFDataRef result = NULL; CTFontDescriptorRef descriptor; CFDictionaryRef attributes; check(iFont != NULL); // Get the font descriptor for the font. descriptor = CTFontCopyFontDescriptor(iFont); check(descriptor != NULL); if (descriptor != NULL) { Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 23// Get the font attributes from the descriptor. This should be enough // information to recreate the descriptor and the font later. attributes = CTFontDescriptorCopyAttributes(descriptor); check(attributes != NULL); if (attributes != NULL) { // If attributes are a valid property list, directly flatten // the property list. Otherwise we may need to analyze the attributes // and remove or manually convert them to serializable forms. // This is left as an exercise for the reader. if (CFPropertyListIsValid(attributes, kCFPropertyListXMLFormat_v1_0)) { result = CFPropertyListCreateXMLData(kCFAllocatorDefault, attributes); check(result != NULL); } } } return result; } The example function in Listing 2-9 creates a font reference from flattened XML data. Itshows how to unflatten font attributes and create a font with those attributes. Listing 2-9 Creating a font from serialized data CTFontRef CreateFontFromFlattenedFontData(CFDataRef iData) { CTFontRef font = NULL; CFDictionaryRef attributes; CTFontDescriptorRef descriptor; check(iData != NULL); // Create our font attributes from the property list. We will create // an immutable object for simplicity, but if you needed to massage Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 24// the attributes or convert certain attributes from their serializable // form to the Core Text usable form, you could do it here. attributes = (CFDictionaryRef)CFPropertyListCreateFromXMLData(kCFAllocatorDefault, iData, kCFPropertyListImmutable, NULL); check(attributes != NULL); if (attributes != NULL) { // Create the font descriptor from the attributes. descriptor = CTFontDescriptorCreateWithAttributes(attributes); check(descriptor != NULL); if (descriptor != NULL) { // Create the font from the font descriptor. We will use // 0.0 and NULL for the size and matrix parameters. This // causes the font to be created with the size and/or matrix // that exist in the descriptor, if present. Otherwise default // values are used. font = CTFontCreateWithFontDescriptor(descriptor, 0.0, NULL); check(font != NULL); } } return font; } Accessing Font Metrics For every font, glyph designers provide a set of measurements, called metrics, which describe the spacing around each glyph in the font. The typesetter uses these metrics to determine glyph placement. Font metrics are parameters such as ascent, descent, leading, cap height, x-height, and so on. The sample functionsin thissection illustrate how to query a font for itsfont metric data. The example function in Listing 2-10 shows how to use line metrics accessors to calculate the line height for a font. In most cases you should not need to do this yourself. If you have a CTLineRef object for a line of text , you could call CTLineGetTypographicBounds to get the line metrics for the line. Common Operations Accessing Font Metrics 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 25Listing 2-10 Calculating line height CGFloat GetLineHeightForFont(CTFontRef iFont) { CGFloat lineHeight = 0.0; check(iFont != NULL); // Get the ascent from the font, already scaled for the font's size lineHeight += CTFontGetAscent(iFont); // Get the descent from the font, already scaled for the font's size lineHeight += CTFontGetDescent(iFont); // Get the leading from the font, already scaled for the font's size lineHeight += CTFontGetLeading(iFont); return lineHeight; } The example function in Listing 2-11 demonstrates how to get glyphsfor the charactersin a string with a single font. Most of the time you should just use a CTLine object to get this information because one font may not encode the entire string. In addition, simple character-to-glyph mapping will not get the correct appearance for complex scripts. Thissimple glyph mapping may be appropriate if you are trying to display specific Unicode characters for a font. Listing 2-11 Getting glyphs for characters void GetGlyphsForCharacters(CTFontRef iFont, CFStringRef iString) { UniChar *characters; CGGlyph *glyphs; CFIndex count; assert(iFont != NULL && iString != NULL); Common Operations Accessing Font Metrics 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 26// Get our string length. count = CFStringGetLength(iString); // Allocate our buffers for characters and glyphs. characters = (UniChar *)malloc(sizeof(UniChar) * count); assert(characters != NULL); glyphs = (CGGlyph *)malloc(sizeof(CGGlyph) * count); assert(glyphs != NULL); // Get the characters from the string. CFStringGetCharacters(iString, CFRangeMake(0, count), characters); // Get the glyphs for the characters. CTFontGetGlyphsForCharacters(iFont, characters, glyphs, count); // Do something with the glyphs here, if a character is unmapped // Free our buffers free(characters); free(glyphs); } Creating Related Fonts The example functions in this section show how to query fonts for their attributes. The example function in Listing 2-12 makes a font bold or unbold based on the value of the Boolean parameter passed with the function call. If the current font family does not have the requested style, the function returns NULL. Listing 2-12 Changing traits of a font CTFontRef CreateBoldFont(CTFontRef iFont, Boolean iMakeBold) { CTFontSymbolicTraits desiredTrait = 0; Common Operations Creating Related Fonts 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 27CTFontSymbolicTraits traitMask; // If we are trying to make the font bold, set the desired trait // to be bold. if (iMakeBold) desiredTrait = kCTFontBoldTrait; // Mask off the bold trait to indicate that it is the only trait // desired to be modified. As CTFontSymbolicTraits is a bit field, // we could choose to change multiple traits if we desired. traitMask = kCTFontBoldTrait; // Create a copy of the original font with the masked trait set to the // desired value. If the font family does not have the appropriate style, // this will return NULL. return CTFontCreateCopyWithSymbolicTraits(iFont, 0.0, NULL, desiredTrait, traitMask); } The example function in Listing 2-13 converts a given font to a similar font in another font family, preserving traits if possible. It may return NULL. Listing 2-13 Converting a font to another family CTFontRef CreateFontConvertedToFamily(CTFontRef iFont, CFStringRef iFamily) { // Create a copy of the original font with the new family. This call // attempts to preserve traits, and may return NULL if that is not possible. // Pass in 0.0 and NULL for size and matrix to preserve the values from // the original font. return CTFontCreateCopyWithFamily(iFont, 0.0, NULL, iFamily); } Common Operations Creating Related Fonts 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 28This table describes the changes to Core Text Programming Guide . Date Notes 2010-03-03 Added this document for iOS 3.2. 2010-01-20 Removed links to deprecated documents and sample code. Revised Figure 1-3 "Text layout data flow" to show that a CGPath object is provided in the creation of a CTFrame object. 2008-06-09 2008-02-08 Fixed bad link to sample code in Introduction. 2007-12-11 Made minor editorial corrections. New document that explains how to perform text layout and font-related operations using the Core Text programming interfaces. 2007-07-16 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 29 Document Revision HistoryApple Inc. © 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, Mac, Macintosh, Objective-C, OS X, Quartz, and QuickDraw are trademarks of Apple Inc., registered in the U.S. and other countries. Helvetica and Times are registered trademarks of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. OpenCL Programming Guide for MacContents About Open CL for OS X 7 At a Glance 7 Prerequisites 8 See Also 8 Developing OpenCL Programs Using Xcode 9 Concepts 9 Essential Development Tasks 11 Hello World! 12 Creating An Application That Uses OpenCL In Xcode 12 Compiling From the Command Line 18 Debugging 19 Basic Programming Sample 20 Basic Kernel Code Sample 20 Basic Host Code Sample 21 Identifying Parallelizable Routines 29 Using Grand Central Dispatch With OpenCL 32 Discovering Available Compute Devices 32 Enqueueing A Kernel To A Dispatch Queue 33 Determining the Characteristics Of A Kernel On A Device 34 Obtaining the Kernel’s Workgroup Size 35 Sample Code: Creating a Dispatch Queue 37 Creating and Managing Memory Objects in OS X OpenCL 43 Overview 43 Workflow 43 Memory Visibility 44 Memory Consistency 46 Creating and Using Buffers in OpenCL 46 Representing Data With Buffer Objects 46 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 2Allocating Memory For Buffer Objects In OS X v10.7 47 Reading, Writing, and Copying Buffer Objects 48 Kernel Support For Data Processing In OpenCL-C 48 Releasing Buffer Objects 49 Setting the finalizer 49 Example: Allocating, Using, Releasing Buffer Objects 50 Creating and Using Images in OpenCL 54 Image Objects 54 Example 59 IOSurface and GL: What OpenCL Supports 64 How the Kernel Interacts With Data 64 Passing Data To a Kernel 64 Accessing Buffer Objects From a Kernel 64 Retrieving Results From a Kernel 65 OpenCL/ OpenGL Interoperation: Data Sharing 66 Sharegroups 67 Synchronizing Access To Shared OpenCL/OpenGL Objects 68 Example 68 Controlling OpenCL/OpenGL Interoperation With GCD 69 Using GCD To Synchronize A Host With OpenCL 69 Synchronizing A Host With OpenCL Using A Dispatch Semaphore 70 Synchronizing Multiple Queues 75 Using IOSurfaces With OpenCL 76 Creating Or Obtaining An IOSurface 76 Creating An Image Object from An IOSurface 76 Sharing the IOSurface With An OpenCL Device 77 Autovectorizer 79 Features 79 Without the Autovectorizer 79 Writing Optimal Code For the CPU: Let the autovectorizer do the work for you 81 Do 81 Don’t 81 What the autovectorizer does 81 Vectorization Example 81 Xcode 81 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsImproving Performance 82 Before Optimizing Code 82 Reducing Overhead 82 Measuring Performance 86 Measuring Performance On the Host 86 Measuring Performance On Devices 86 Estimating Optimal Performance 87 Tuning OpenCL Code For the CPU 89 In Practice 90 Tuning OpenCL Code For the GPU 99 In Practice 100 Document Revision History 108 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures, Tables, and Listings Developing OpenCL Programs Using Xcode 9 Figure 1-1 OpenCL Development Process 11 Hello World! 12 Figure 2-1 A simple OpenCL kernel in Xcode 12 Figure 2-2 Build settings for kernel files 13 Figure 2-3 OpenCL host code in Xcode 16 Figure 2-4 Adding the OpenCL framework 17 Figure 2-5 OpenCL framework was added 17 Figure 2-6 Results 18 Basic Programming Sample 20 Listing 3-1 Kernel code sample 20 Listing 3-2 Host code sample 21 Identifying Parallelizable Routines 29 Listing 4-1 Pseudocode that computes the final grade for each student 29 Listing 4-2 The isolated grade average task 30 Using Grand Central Dispatch With OpenCL 32 Listing 5-1 Creating a dispatch queue 37 Listing 5-2 Obtaining workgroup information 40 Creating and Managing Memory Objects in OS X OpenCL 43 Figure 6-1 Physical memory of an OpenCL system 45 Listing 6-1 Sample host function creates buffers then calls kernel function 50 Listing 6-2 Sample kernel squares an input array 54 Listing 6-3 Creating a 2D image object 55 Listing 6-4 An image-processing kernel function 58 Listing 6-5 Sample host function creates images then calls kernel function 59 Listing 6-6 Sample kernel swaps the red and green channels 63 OpenCL/ OpenGL Interoperation: Data Sharing 66 Figure 7-1 OpenGL and OpenCL share data using sharegroups 67 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 5Controlling OpenCL/OpenGL Interoperation With GCD 69 Figure 8-1 Rendering loop - each pass on the main thread creates a new frame for display 71 Listing 8-1 Synchronizing the host with OpenCL processing 70 Listing 8-2 Synchronizing a host with OpenCL using a dispatch semaphore 71 Listing 8-3 Synchronizing multiple queues 75 Using IOSurfaces With OpenCL 76 Listing 9-1 Creating an IOSurface-backed CL Image 77 Listing 9-2 Extracting an Image From an IOSurface 77 Autovectorizer 79 Figure 10-1 Before autovectorization: A simple float sent to the CPU and the GPU 80 Listing 10-1 Passing single floats into a kernel 80 Improving Performance 82 Figure 11-1 Memory copy speed in GB/s (read+write) vs buffer size 88 Table 11-1 Benchmarks of boxAvgH5 variants: 103 Table 11-2 Benchmarks of boxAvgH5 variants where each work item processes 4 columns: 106 Listing 11-1 Using the gettimeofday function 86 Listing 11-2 Sample benchmarking loop on the kernel 87 Listing 11-3 Kernel for estimating performance 87 Listing 11-4 The boxAvg kernel in two passes 91 Listing 11-5 Modify the horizontal pass to compute one row per work item instead of one pixel 92 Listing 11-6 Modify the algorithm to read fewer values per pixel and to incrementally update the sum 94 Listing 11-7 Modify the horizontal pass by moving division and conditionals out of the inner loop 95 Listing 11-8 Modify vertical pass to combine rows; each work item computes a block of rows 96 Listing 11-9 Ensure the image width is always a multiple of 4 97 Listing 11-10 A safer variant that will work for any image width 97 Listing 11-11 Fused kernel 98 Listing 11-12 Kernel before optimization 101 Listing 11-13 Move the data to local memory 102 Listing 11-14 Modify the kernel to compute several rows in each work item 103 Listing 11-15 Provide a dedicated kernel for each value of RANGE 104 Listing 11-16 Fastest variant: Unroll the inner loop and convert float data to float4 106 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 6 Figures, Tables, and ListingsOpenCL™ (Open Computing Language) is an open standard for cross-platform, parallel programming of modern processors such as multicore CPUs and programmable GPUs. Introduced with OS X v10.6, OpenCL lets your application tap into the parallel computing power of these processors to improve performance and deliver features made possible by compute-intensive algorithms. OpenCL is comprised of thee parts: a C99-based kernel programing language, a powerful scheduling API and a runtime that efficiently executes kernels on the CPU or GPU. Going beyond the standard, OS X v10.7 adds integration between OpenCL, Grand Central Dispatch and Xcode making it even easer take advantage of the power of the OpenCL in your application. At a Glance Using OpenCL is easier than ever in OS X v10.7: ● OpenCL is fully supported by Xcode. The Xcode offline compiler removes a configuration step that used to have to be performed before the kernel could be run and aids in debugging earlier in the development process. See “Hello World!” (page 12). ● You can write OpenCL functions in separate files and include them in your Xcode project. These files can be compiled as your application is built. This improves application performance because kernels need not be compiled when the application is running ● OpenCL now integrates with Grand Central Dispatch, making it easier for you to focus on making your OpenCL kernels more efficient. See “Using Grand Central Dispatch With OpenCL” (page 32). ● The autovectorizer is used for compiling kernels that will run on the CPU. It accelerates performance up to four times without additional effort. The autovectorizer allows you to write one kernel that runs efficiently on both a CPU and a GPU. It is invoked regardless of whether the openclc compiler is called from Xcode or if the kernel is built at runtime. See “Autovectorizer” (page 79). ● You can, of course, continue to use code you’ve already written to the OpenCL 1.1 standard. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 7 About Open CL for OS XPrerequisites This guide assumes that you program in C and have access to The OpenCL Specification . Although this guide discusses many key OpenCL API functions, it does not provide detailed information on the OpenCL API or the OpenCL-C programming language. See Also The OpenCL Specification , available from the Khronos Group at http://www.khronos.org/registry/cl/ provides information on the OpenCL standard. The OpenCL Programming Guide by Aaftab Munshi, Benedict Gaster, Timothy G. Mattson, James Fung, and Dan Ginsburg, available from Pearson Education, Inc. For more information about Grand Central Dispatch queues, see Concurrency Programming Guide: Dispatch Queues. About Open CL for OS X Prerequisites 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 8This chapter describes a streamlined process in which, using tools provided by OS X v10.7, you can include OpenCL kernels as resources in Xcode projects, compile them along with the rest of your application, and use Grand Central Dispatch as the queuing API for executing OpenCL commands and kernels on the CPU and GPU. If you need to create OpenCL programs at run-time, with source loaded as a string or from a file, or if you want API-level control over queueing, see The OpenCL Specification , available from the Khronos Group at http://www.khronos.org/registry/cl/. Concepts In the OpenCL specification, computational processors are called devices. An OpenCL device has one or more compute units. A workgroup executes on a single compute unit. A compute unit is composed of one or more processing elements and local memory. A Macintosh computer has a single CPU and GPUs. The CPU on a Macintosh has multiple compute units, which is why it is called a multi-core CPU. The number of compute units in a CPU limits the number of workgroups that can execute concurrently. CPUs commonly contain two to eight compute units, with the maximum increasing year-to-year. A graphics processing unit (GPU) typically contains many compute units—the GPUs in current Macintosh systems feature tens of compute units, and future GPUs may contain hundreds. As used by OpenCL, a CPU with eight compute units is considered a single device, as is a GPU with 100 compute units. The OS X v10.7 implementation of the OpenCL API facilitates designing and coding data parallel programs to run on both CPU and GPU devices. In a data parallel program, the same program (or kernel) runs concurrently on different pieces of data and each invocation is called a work item and given a work item ID. The work item IDs are organized in up to three dimensions (called an N-D range). A kernel is essentially a function written in the OpenCL language that enables it to be compiled for execution on any device thatsupports OpenCL. Although kernels are enqueued for execution by host applications written in C, C++, or Objective C, a kernel must be compiled separately to be customized for the device on which it is going to run. You can write your OpenCL kernel source code in a separate file or include it inline in your host application source code. OpenCL kernels can be: 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 9 Developing OpenCL Programs Using Xcode● Compiled at compile time, then run when queued by the host application or ● Compiled and then run at runtime when queued by the host application or ● Run from a previously-built binary A work item is a parallel execution of a kernel on some data. It is analogousto a thread. Each kernel is executed upon hundreds of thousands of work items A workgroup is set of work items. Each workgroup is executed on a compute unit. Workgroup dimensions determine how the input is operated upon in parallel. The application usually specifies the dimensions based on the size of the input. There are constraints: for example, there may be a maximum number of work items that can be launched for a certain kernel on a certain device. The program that calls OpenCL functions to set up the context in which kernels run and enqueue the kernels for execution is known asthe host application. The application isrun by OS X on the CPU. The device on which the host application executes is known as the host device. Before kernels can be run, the host application typically completes the following steps: 1. Determine what compute devices are available, if necessary. 2. Select compute devices appropriate for the application. 3. Create dispatch queues for selected compute devices. 4. Allocate the memory objects needed by the kernels for execution. (This step may occur earlier in the process, as convenient.) Note that the host device (the CPU) can itself be an OpenCL device and can be used to execute kernels. The host application can enqueue commands to read from and write to memory objects. See “Creating and Managing Memory Objects in OS X OpenCL” (page 43). Memory objects are used to manipulate device memory. There are two types of memory objects used in OpenCL: buffer objects and image objects. Buffer objects can contain any type of data; image objects contain data organized into pixels in a given format. Developing OpenCL Programs Using Xcode Concepts 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 10Essential Development Tasks In OS X v10.7, the OpenCL development process includes these major steps: Figure 1-1 OpenCL Development Process Step 1: Parallelize. Step 2: Code kernel. Step 3: Code host. Step 4: Compile. Step 5: Execute. Step 6: Debug. Step 7: Optimize. 1. Identify the tasks to be parallelized. Determining how to parallelize your program effectively is often the hardest part of developing an OpenCL program. See “Identifying Parallelizable Routines” (page 29). 2. In Xcode, write your kernel functions. See “Basic Kernel Code Sample” (page 20). 3. In Xcode, write the host code that will be calling the kernel(s). See “Basic Host Code Sample” (page 21). 4. Compile using Xcode. See “Creating An Application That Uses OpenCL In Xcode” (page 12). 5. Execute. 6. Debug (if necessary). See “Debugging” (page 19). 7. Improve performance (if necessary). See “Improving Performance” (page 82). Developing OpenCL Programs Using Xcode Essential Development Tasks 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 11Creating an OpenCL program in OS X v10.7 is easy with support built into Xcode. This chapter describes step-by-step how to create an OpenCL project in Xcode. If you already have a working OpenCL project, you need not regenerate it, but you can find information in this chapter about support for OpenCL now built into Xcode. Creating An Application That Uses OpenCL In Xcode To create a project that uses OpenCL in OS X v10.7: 1. Create your OpenCL project in Xcode as a new OS X project (empty is fine). 2. Place your kernel code in one or more .cl files in your Xcode project. You can place all your kernels into a single .cl file, or you can separate them as you choose. You can also include non-kernel code that will run on the same OpenCL device as the kernel in each .cl file. Each .cl file is compiled by default into three files containing bitcode for i386, x86_64, and gpu_32 architectures. You can change this using the OpenCL Architectures Build Setting.) At runtime your host application discovers what kind(s) of devices are available, and determines which of the compiled kernels to enqueue and execute. Figure 2-1 A simple OpenCL kernel in Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 12 Hello World!3. You can set the following build settings for your kernel (.cl) files: Figure 2-2 Build settings for kernel files ● OpenCL Compiler Version ● Compiler Version The OpenCL C compiler version supported by the platform. The default is OpenCL C 1.1. To set this parameter from the command line, use: -cl-std=CL1.1 ● OpenCL - Architectures ● Valid Architectures A StringList specifying the list of the architectures for which the product will be built. This is usually set to a predefined build setting provided by the platform. The default is that the product is built for all three architectures. To set this parameter from the command line, use: ● -triple i386-applecl-darwin ● -triple x86_64-applecl-darwin ● -triple gpu_32-applecl-darwin (So to compile for the first two, the command line would read: -triple i386-applecl-darwin -triple x86_64-applecl-darwin ● OpenCL - Preprocessing ● Preprocessor Macros Space-separated list of preprocessor macros of the form "foo" or "foo=bar". To set this parameter from the command line, use: -D Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 13● OpenCL - Code Generation ● Use MAD Boolean. If true, allow expressions of the type a * b + c to be replaced by a Multiply-Add (MAD) instruction. If MAD is enabled, multistep instructions in the form a * b + c are performed in a single step, but the accuracy of the results may be compromised. For example, to optimize performance, some OpenCL devices implement MAD by truncating the result of the a * b operation before adding it to c. The default for this parameter is NO. To set this parameter from the command line, use: -cl-mad-enable ● Relax IEEE Compliance Boolean. If true, allows optimizations for floating-point arithmetic that may violate the IEEE 754 standard and the OpenCL numerical compliance requirements defined in in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5 of the OpenCL 1.1 specification. This is intended to be a performance optimization. This option causes the preprocessor macro __FAST_RELAXED_MATH__ to be defined in the OpenCL program. The default is NO. To set this parameter from the command line, use: -cl-fast-relaxed-math ● Double as single Boolean. If true, double precision floating-point expressions are treated as single precision floating-point expressions. This option is available for GPUs only. The default is NO. To set this parameter from the command line, use: -cl-double-as-single ● Flush denorms to zero Boolean that controls how single precision and double precision denormalized numbers are handled. Ifspecified as a build option, the single precision denormalized numbers may be flushed to zero; double precision denormalized numbers may also be flushed to zero if the optional extension for double precision is supported. This is intended to be a performance hint and the OpenCL compiler can choose not to flush denorms to zero if the device supports single precision (or double precision) denormalized numbers. This option isignored forsingle precision numbersif the device does notsupportsingle precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_SINGLE_FP_CONFIG. This option isignored for double precision numbersif the device does notsupport double precision or if it does support double precision but not double precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_DOUBLE_FP_CONFIG. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 14This flag only applies for scalar and vector single precision floating-point variables and computations on these floating-point variables inside a program. It does not apply to reading from or writing to image objects. The default is NO. To set this parameter from the command line, use: -cl-denorms-are-zero ● Auto-vectorizer Auto-vectorizes the OpenCL kernels for the CPU. This setting takes effect only for the CPU. This makes it possible to write a single kernel that is portable and performant across CPUs and GPUs. The default is YES. To set this parameter from the command line, use: -cl-auto-vectorize-enable or -cl-autovectorize-disable ● Optimization Level You can choose whether to optimize for smallest code size or not. The default is fast O1 optimization. To set this parameter from the command line, use: ● -Os sets it to optimize for smallest code size ● -O, O1 sets it to fast ● -O2 sets it to faster ● -O3 sets it to fastest ● -O0 sets it to not optimize Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 154. Place your host code in one or more .c files in your Xcode project. Figure 2-3 OpenCL host code in Xcode 5. Link to the OpenCL framework. a. Click on the target. b. Click the Build Phases tab. c. Open Link Binary With Libraries. d. Click the + sign. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 16e. Select OpenCL.framework from the dropdown. Figure 2-4 Adding the OpenCL framework f. Press Add. Figure 2-5 OpenCL framework was added 6. Build. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 177. Run. Figure 2-6 Results See “Basic Programming Sample” (page 20) for a line-by-line description of the host and kernel code in the Hello World sample project. Compiling From the Command Line To compile from the command line, call openclc. Hello World! Compiling From the Command Line 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 18Debugging Here are a few hints to help you debug your OpenCL application: ● Run your kernel on the CPU first. There is no memory protection on GPUs. If an index goes out of bounds on the GPU, it is likely to take the whole system down. If an index goes out of bounds on the CPU, it may crash the program that’s running, but it will not take the whole system down. ● You can use the printf function from within your kernel. ● You can use the gdb debugger to look at the assembly code once you’ve built your program. See GDB website. ● On the GPU, use explicit addressrange checksto look for out-of-range address accesses. (Remember: there is no memory protection on current GPUs.) Hello World! Debugging 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 19This chapter provides a tour through the code of a simple OpenCL application that performs calculations on a test data set. The code in Listing 3-2 (page 21) calls the kernel defined in Listing 3-1 (page 20). The kernel squares each value. Once the kernel completes its work, the host validates that every value was processed by the kernel. Basic Kernel Code Sample Listing 3-1 (page 20) is example kernel code. See to download the project. Listing 3-1 Kernel code sample //////////////////////////////////////////////////////////////////////////////// // Simple OpenCL kernel that squares an input array. // This code is stored in a file called mykernel.cl. kernel void square(global float* input, global float* output) [1] { size_t i = get_global_id(0); output[i] = input[i] * input[i]; } Notes: 1. Wrap your kernel code into a kernel block: kernel void kernelName ( global float* inputParameterName, global float* [anotherInputParameter] , …, global float* outputParameterName) 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 20 Basic Programming Sample{ ... } Note: Kernels always return void. Basic Host Code Sample Listing 3-2 (page 21) is example code that would run on a host. It calls a kernel to square a set of values, then tests to ensure that the kernel processed all the data. See to download the project. Listing 3-2 Host code sample //////////////////////////////////////////////////////////////////////////////// #include #include // This include pulls in everything you need to develop with OpenCL on OS X v10.7. #include // Include the header file generated by Xcode. This header file contains the // kernel block declaration. #include "mykernel.cl.h" [1] // Hardcoded number of values to test, for convenience. #define NUM_VALUES 1024 // A utility function that checks that our kernel execution performs the // requested work over the entire range of data. static int validate(cl_float* input, cl_float* output) { int i; for (i = 0; i < NUM_VALUES; i++) { Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 21// The kernel was supposed to square each value. if ( output[i] != (input[i] * input[i]) ) { fprintf(stdout, "Error: Element %d did not match expected output.\n", i); fprintf(stdout, " Saw %1.4f, expected %1.4f\n", output[i], input[i] * input[i]); fflush(stdout); return 0; } } return 1; } int main (int argc, const char * argv[]) { int i; char name[128]; // First, try to obtain a dispatch queue that can send work to the // GPU in our system. [2] dispatch_queue_t queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // In the event that our system does NOT have an OpenCL-compatible GPU, // we can use the OpenCL CPU compute device instead. if (queue == NULL) { queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); } // This is not required, but let's print out the name of the device // we are using to do work. We could use the same function, // clGetDeviceInfo, to obtain all manner of information about the device. cl_device_id gpu = gcl_get_device_id_with_dispatch_queue(queue); clGetDeviceInfo(gpu, CL_DEVICE_NAME, 128, name, NULL); fprintf(stdout, "Created a dispatch queue using the %s\n", name); Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 22// Now we gin up some test data. This is typically the case: you have some // data in your application that you want to process with OpenCL. This // test_in buffer represents such data. Normally, this would come from // some REAL source, like a camera, a sensor, or some compiled collection // of statistics -- it just depends on the problem you want to solve. float* test_in = (float*)malloc(sizeof(cl_float) * NUM_VALUES); for (i = 0; i < NUM_VALUES; i++) { test_in[i] = (cl_float)i; } // Once the computation using CL is done, we'll want to read the results // back into our application's memory space. Allocate some space for that. float* test_out = (float*)malloc(sizeof(cl_float) * NUM_VALUES); // Our test kernel takes two parameters: an input float array and an // output float array. We can't send the application's buffers above, since // our CL device operates on its own memory space. Therefore, we allocate // OpenCL memory for doing the work. Notice that for the input array, // we specify CL_MEM_COPY_HOST_PTR and provide the fake input data we // created above. This tells OpenCL to copy over our data into its memory // space before it executes the kernel. [3] void* mem_in = gcl_malloc(sizeof(cl_float) * NUM_VALUES, test_in, CL_MEM_READ_ONLY | CL_MEM_COPY_HOST_PTR); // The output array is not initalized; we're going to fill it up when // we execute our kernel. [4] void* mem_out = gcl_malloc(sizeof(cl_float) * NUM_VALUES, NULL, CL_MEM_WRITE_ONLY); // Dispatch your kernel block using one of the dispatch_ commands and the // queue we created above. [5] dispatch_sync(queue, ^{ // Though we COULD pass NULL as the workgroup size, which would tell Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 23// OpenCL to pick the one it thinks is best, we can also ask // OpenCL for the suggested size, and pass it ourselves. [6] size_t wgs; gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(wgs), &wgs, NULL); // The N-Dimensional Range over which we'd like to execute our // kernel. In our example case, we're operating on a 1D buffer, so // it makes sense that our range is 1D. cl_ndrange range = { 1, // The number of dimensions to use. {0, 0, 0}, // The offset in each dimension. We want to // process ALL of our data, so this is 0 for // our test case. [7] {NUM_VALUES, 0, 0}, // The global range -- this is how many items // IN TOTAL in each dimension you want to // process. {workgroup_size, 0, 0} // The local size of each workgroup. This // determines the number of workitems per // workgroup. It indirectly affects the // number of workgroups, since the global // size / local size yields the number of // workgroups. So in our test case, we will // have NUM_VALUE / wgs workgroups. }; // Calling the kernel is easy; you simply call it like a function, // passing the ndrange as the first parameter, followed by the expected // kernel parameters. Note that we case the 'void*' here to the // expected OpenCL types. Remember -- if you use 'float' in your // kernel, that's a 'cl_float' from the application's perspective. [8] Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 24square_kernel(&range,(cl_float*)mem_in, (cl_float*)mem_out); // Getting data out of the device's memory space is also easy; we // use gcl_memcpy. In this case, we take the output computed by the // kernel and copy it over to our application's memory space. [9] gcl_memcpy(test_out, mem_out, sizeof(cl_float) * NUM_VALUES); }); // Now we can check to make sure our kernel really did what we asked // it to: if ( validate(test_in, test_out)) { fprintf(stdout, "All values were properly squared.\n"); } // Don't forget to free up the CL device's memory when you're done. [10] gcl_free(mem_in); gcl_free(mem_out); // And the same goes for system memory, as usual. free(test_in); free(test_out); // Finally, release your queue just as you would any GCD queue. [11] dispatch_release(queue); } Notes: Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 251. Include the header file that contains the kernel block declaration. The name of the header file for a .cl file will be the name of the .cl file with .h appended to it. For example, if the .cl file is named mykernel.cl, the header file you must include will be mykernel.cl.h. 2. Call gcl_create_dispatch_queue to create the dispatch queue. 3. Create memory objects to hold input and output data and write input data to the input objects. Allocate an array on the OpenCL device from which to read kernel results back into host memory. Use gcl_malloc and make sure to use the OpenCL size of the datatype being returned (e.g., gcl_malloc(sizeof(cl_float) * NUM_VALUES). Because the CL device operates on its own memory space, allocate OpenCL memory for the input data upon which the kernel will work. Specify CL_MEM_COPY_HOST_PTR to tell OpenCL to copy over the input data from host memory into its memory space before it executes the kernel. 4. Allocate OpenCL memory in which the kernel will store its results. 5. Dispatch your kernel block using one of the dispatch commands and the queue you created above. In your dispatch call, you can specify workgroup parameters. 6. Describe the data parallel range over which to execute the kernel. You will describe the data-parallel range for the OpenCL kernel in the host code. The cl_ndrange structure is used to specify the data parallel range. OpenCL always executes kernels in a data parallel fashion—that is, instances of the same kernel (work items) execute on different portions of the total data set. See “Representing Data With Buffer Objects” (page 46). (If you want task-parallel execution you must enqueue multiple kernels on different devices.) Each work item is responsible for executing the kernel once and operating on its assigned portion of the data set. It is your responsibility to tell OpenCL the total number of work items that you need to process all of your data. Because data sets are commonly organized in one, two, or three dimensions (representing such things as audio data streams, two- or three-dimensional images, or three-dimensional objects), you also need to indicate to OpenCL in how many dimensions your data extends (that is, how many coordinates to use for each data point). ● Determining the Data Dimensions The first step in preparing a kernel for execution is to identify the number of dimensions that you want to use to represent your data. For example, if your data represents a flat image that is m pixels wide by n pixels high, then you have a two-dimensional data set with each data pointed represented by its coordinates on the m and n axes. On the other hand, if you’re dealing with spatial data that involves the (x, y, z) position of nodes in three-dimensional space, you have a three-dimensional data set. Another way to look at the dimensionality of your data is in terms of nested loops in a traditional, non-parallel processing model. If you can loop through your entire data set with a single loop, then your data is one-dimensional. If you would use one loop nested in another, your data is Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 26two-dimensional, and if you would have loops nested three deep to cycle through all your data, your data is three-dimensional. Whatever your data is, it’s up to you to determine how many dimensions to use. As of OpenCL 1.0, dimensions greater than three are not supported. ● Determining the Number of Work Items The next step in preparing your kernel for execution is determining how many work items you'll need to process all of your data. This is known as the global work size, and it defines the total number of work items needed for all dimensions combined. For one-dimensional data, the global work size equals the number of data items. For two-dimensional data with m data items in one dimension and n items in the second dimension, the global work size is n * m. Similarly, for three-dimensional data with x , y , and z work itemsin the three dimensions, the global work size is x * y * z . There is practically no limit on the number of work items, and this should be a large number (over 1000) for good performance on GPUs. ● Choosing a Workgroup Size When enqueuing a kernel to execute on a device, you can specify the size of the workgroup that you’d like OpenCL to use during execution. A workgroup is a collection of work items that execute on the same compute unit on the same OpenCL device. By providing OpenCL with a suggested workgroup size, you are telling it how you would like it to delegate the work items to the various computational units on the device. The work items executing in the same workgroup can share memory and execute synchronously. In order to take advantage of these features, however, you have to know the maximum workgroup size allowed by the OpenCL device on which your work items are executing. To get this information, use the gcl_get_kernel_block_workgroup_info function and request the CL_KERNEL_WORK_GROUP_SIZE property. This API isrequired to query the workgroup size of a kernel block to use in cl_ndrange.local_work_size. Thisis needed for good performance across devices asthe workgroup sizes vary across devices. This API must be called inside a block submitted to a Grand Central Dispatch queue created using gcl_create_dispatch_queue. If you don’t need to share data among work items, pass a NULL value to the local_work_size parameter when you enqueue your kernel for execution to have OpenCL determine the workgroup size for you. Doing so will ensure the most efficient use of the available devices. Note that you also need to use clGetDeviceInfo with the selector CL_DEVICE_MAX_WORK_ITEM_SIZES to get the maximum workgroup size in each dimension, and call the gcl_get_kernel_block_workgroup_info function with the selector CL_KERNEL_WORK_GROUP_SIZE to get the total workgroup size. Three conditions must be met for the local dimensions to be valid: a. The number of work items in each dimension (local_x, local_y, and local_z) in a single workgroup must be less than the values returned for the device from clGetDeviceInfo(CL_DEVICE_MAX_WORK_ITEM_SIZES). Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 27b. The total number of work items in a workgroup (local_x times local_y times local_z ) must be less than or equal to the value returned by the gcl_get_kernel_block_workgroup_info(CL_KERNEL_WORK_GROUP_SIZE) function. c. The number of work items in each dimension in a single workgroup must divide evenly into the total number of work items in that dimension ( global_n mod local_n = 0). 7. Always pass an offset for each of three dimensions even though the workgroup may have fewer than three dimensions. 8. Call the kernel as you would call a function. Pass the ndrange as the first parameter, followed by the expected kernel parameters. Case the void* types to the expected OpenCL types. Remember -- if you use float in your kernel, that's a cl_float from the application's perspective. The call to the kernel will look something like this: kernelName( &range, (cl_datatype*)inputArray, (cl_datatype *)outputArray ); 9. Retrieve the data from the OpenCL device's memory space with gcl_memcpy. The output computed by the kernel is copied over to the host application's memory space. 10. Free OpenCL memory objects. 11. Call dispatch_release(...) on the dispatch queue you created with gcl_create_dispatch_queue(...) once you are done with it. Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 28The first step in using OpenCL to improve your application’s performance is to identify what portions of your application are appropriate for parallelization. Whereas in a general application you can spawn a separate thread for a task as long as the functions in the thread are re-entrant and you’re careful about how you synchronize data access, to achieve the level of parallelism for which OpenCL isideal, it is much more important for the work items to be independent of each other. Although work items in the same workgroup can share local data, they execute synchronously and so no work item’s calculations depend on the result from another work item. Parallelization works only when the tasks that you run in parallel do not depend on each other. For example, assume that you are writing a simple application that keeps track of the grades for students in a class. The application consists of two main tasks: 1. Compute the final grade for each student, assuming the final grade is the average of all the students’ grades. 2. Obtain a class average by averaging the final grades of all students. You cannot perform these two tasks in parallel because they are not independent of each other: to calculate the class average, you must have already calculated the final grade for each student. Despite the fact that you cannot perform task 1 and task 2 simultaneously, there is still an opportunity for parallelization. To see how it can be broken down, it helpsto look at a basic pseudocode example for computing the final grade for each student serially. Listing 4-1 Pseudocode that computes the final grade for each student // assume 'class' is a collection of 'student' objects foreach(student in class) { // assume getGrades() returns a collection of integer grades grades = student.getGrades(); sum = 0; count = 0; 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 29 Identifying Parallelizable Routines// iterate through each grade, adding it to sum foreach(grade in grades) { sum += grade; count++; } // cache the average grade in the student object student.averageGrade = sum / count; } The pseudocode in Listing 4-1 (page 29) proceeds through each student in the class, one by one, calculating the average of each student’s grades and caching it in the student object. Although this example computes each grade average one at a time, there’s no reason that the grade averages for all the students couldn’t be calculated at the same time. Because the grades of one student do not affect the grades of another, you can calculate the grade averages for all the students at the same time instead of looping through the same set of instructions for each student, one at a time. This is the idea behind data parallelism. Data parallelism consists of taking a single task (in this case, calculating a student’s average grade), and repeating it over multiple sets of data. Students’ grades do not affect each other, therefore you can process them in parallel. To express this programmatically, you must first separate your task (calculating the grade average of a student) from your data (the students in the class). Listing 4-2 (page 30) shows how you can isolate the grade-averaging task. Listing 4-2 The isolated grade average task task calculateAverageGradeForStudent( student ) { // assume getGrades() returns a collection of integer grades grades = student.getGrades(); sum = 0; count = 0; // iterate through each grade, adding it to sum foreach(grade in grades) Identifying Parallelizable Routines 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 30{ sum += grade; count++; } // store the average grade in the student object student.averageGrade = sum / count; } Now that you have the task isolated, you need to apply it to allstudentsin the classin parallel. Because OpenCL has native support for parallel computing, you can rewrite the task shown in Listing 4-2 (page 30) as an OpenCL kernel function. Using the OpenCL framework API, you can enqueue this kernel to run on a device where each compute unit on the device can apply an instance of the kernel (that is, a work item) to a different set of data. The challenge in parallelizing your application is identifying the tasks that you can distribute across multiple compute units. Sometimes, asin this example, the identification isrelatively trivial and requiresfew algorithmic changes. Other times, it might require designing a new algorithm from scratch that lends itself more readily to parallelization. Although there is no universal rule for parallelizing your application, there are a few tips you can keep in mind: ● Pay attention to loops. Often the opportunities for parallelization lie within a subroutine that is repeated over a range of results. ● Nested loops might be restructured as multi-dimensional parallel tasks. ● Find as many tasks as possible that do not depend on each other. Finding a group of routines that do not share memory or depend on each other’s results is usually a good indicator that you can perform them in parallel. If you have enough such tasks, you can consider writing a task-parallel OpenCL program. ● Due to the overhead of setting up a context and transferring data over a PCI bus, you must be processing a fairly large data set before you see any benefits from using OpenCL. The exact point at which you start to see benefits depends on the OpenCL implementation and the hardware being used, so you will have to experiment to see how fast you can get your algorithm to execute. In general, a high ratio of computation to data access and lots of mathematical computations are good for OpenCL programs. Identifying Parallelizable Routines 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 31Developers already use Grand Central Dispatch (GCD) queues to implement concurrency in their applications. OS X v10.7 adds the ability to enqueue work coded as OpenCL kernels to GCD queues backed by OpenCL compute devices. You can use GCD with OS X v10.7 OpenCL to: ● Investigate the computational environment in which your OpenCL application is running. You can use OS X v10.7 OpenCL to learn about the devicesin the system that would be best for performing particular OpenCL computations and to enqueue kernels to devices: ● You can find out about the computational power and technical characteristics of each OpenCL-capable device in the system. See “Discovering Available Compute Devices” (page 32). ● GCD can suggest which OpenCL device(s) would be best for running a particular kernel. ● You can obtain recommendations about how to configure the kernel - get the suggested optimal size of the workgroup for each kernel on any particular device. See “Obtaining the Kernel’s Workgroup Size” (page 35). ● Enqueue the kernel. ● Synchronize work between the host and OpenCL devices and synchronize work between devices. Your host can wait on completion of work in all queues (See “Using GCD To Synchronize A Host With OpenCL” (page 69)) or one queue can wait on completion of another queue (See “Synchronizing Multiple Queues” (page 75)). Discovering Available Compute Devices OpenCL kernels assume a Single instruction, Multiple Data (SIMD) parallel model of computation. This means (roughly) that you have a large amount of data divided into chunks, and you want the kernel to perform the same computation on each chunk. Some SIMD algorithms will execute better on a CPU rather than on a GPU, or on one GPU rather than another, depending on many factors. Tools in OS X version 7 and later facilitate discovery of the types of devices that are available to process data. A context is needed to share memory objects between devices. If you use The OS X v10.7 gcl_ APIs, you can just retrieve and use the default global context; no context creation is needed. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 32 Using Grand Central Dispatch With OpenCLNote: If you are using APIs defined in the OpenCL specification, you do need to create your own contexts. An OpenCL context is similar to an OpenGL sharegroup. A sharegroup is a set of tools that allow blocks of memory to be accessed by both a GPU and a CPU. See “OpenCL/ OpenGL Interoperation: Data Sharing” (page 66). When you retrieve the default global context in OS X v10.7 OpenCL, you can find out about the environment in which OpenCL kernels execute. The context includes the set of devices, the memory accessible to those devices, and one or more queues used to schedule execution of one or more kernels. From the context, you can discover the types of devices in the system and can obtain recommendations as to the optimal configuration for running a kernel. Your application can call on GCD to create a queue for a particular type of device or to create a queue for a specific device. 1. Call the gcl_get_context function to get the "global" OpenCL context that OS X v10.7 creates for you. Note: Since this context is created by the OpenCL, you should not retain / release it. (You should retain/release any contexts that you explicitly create.) 2. Call the clGetDeviceIds( ... ) function (an API in the OpenCL standard API), specifying the context you just obtained asthe context parameter. This call will return a list of the IDs of the OpenCL devices attached. 3. When you have the IDs of the devices in the context, you can call the clGetDeviceInfo() function for each of the devices to obtain information about the device. The sample code in Listing 5-1 (page 37) requeststhe vendor (the manufacturer) and the device name. You could also use the clGetDeviceInfo() function to request more technical information like the number of compute cores, the cache line size and so on. The types of information you can obtain are described in the OpenCL 1.1 specification. You can choose to send different types of work to a device depending upon its characteristics and capabilities. Enqueueing A Kernel To A Dispatch Queue You must use an OpenCL-compatible dispatch queue for your OpenCL work. You can create a queue for a particular device in the system or you can create a queue for a particular type of device. You can enqueue as many kernels on each queue as you choose. You can create as many different queues as you would like: ● To create a dispatch queue to run on any device so long as it’s of a particular type, call the gcl_create_dispatch_queue function passing CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, or CL_DEVICE_TYPE_ACCELERATOR as the first parameter. Using Grand Central Dispatch With OpenCL Enqueueing A Kernel To A Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 33Note: The dispatch queue you create must be attached to a particular device type. You cannot create an OpenCL-compatible dispatch queue for the default device type (CL_DEVICE_TYPE_DEFAULT). OS X v10.7 OpenCL will create a dispatch queue that uses a GPU or CPU, depending upon the device type you specified. If more than one GPU is available, OS X v10.7 OpenCL will give enqueue the kernel on the device of the type you specify that has the largest number of compute cores. Note: If you've created your dispatch queue specifying CL_DEVICE_TYPE_GPU, you won't know whichGPUis being used. Callthe gcl_get_device_id_with_dispatch_queue function to find out which device is actually attached to a given dispatch queue. ● If you know exactly which OpenCL device id you want to use because you've obtained it with the clGetDeviceIds function and found out about it using the clGetDeviceInfo function, call the cl_create_dispatch_queue function with CL_DEVICE_TYPE_USE_ID and pass the id of the device you want to use. Both of these methods are illustrated in the sample code. See Listing 5-1 (page 37). Note: Always call the dispatch_release(...) function on the dispatch queue you created with the gcl_create_dispatch_queue(...) function once you are done with it. All of the example code contains this call. Once you have created a queue, you can enqueue as many kernels onto that queue as necessary. Or, you can create additional queues with different characteristics. For more information about Grand Central Dispatch queues, see Concurrency Programming Guide: Dispatch Queues. Determining the Characteristics Of A Kernel On A Device To obtain information specific to a kernel/device pair, including how much private and local memory the kernel will consume (on that device), as well as the workgroup size OpenCL thinks will be most optimal for execution, call the gcl_get_kernel_block_workgroup_info function. Thisinformation is useful when you are tuning performance for a particular device or debugging performance issues. Using Grand Central Dispatch With OpenCL Determining the Characteristics Of A Kernel On A Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 34Obtaining the Kernel’s Workgroup Size To find out what OpenCL thinks is the best workgroup size for executing a kernel on a particular device, call the gcl_get_kernel_block_workgroup_info function. You can use this value as the cl_ndrange.local_work_size for a kernel on a particular device. Note: You must call this API inside a block submitted to a GCD dispatch queue created using the gcl_create_dispatch_queue function. In Listing 5-1 (page 37), notice that we first execute this method in a block on a dispatch queue we've created with OpenCL requesting the local memory size: gcl_get_kernel_block_workgroup_info( square_kernel, CL_KERNEL_LOCAL_MEM_SIZE, sizeof(local_memsize), &local_memsize, NULL); Then, in Listing 5-2 (page 40), we call the gcl_get_kernel_block_workgroup_info function to ask OpenCL to return what it considers to be the optimal workgroup size for this kernel, on this device: gcl_get_kernel_block_workgroup_info( square_kernel, // this kernel CL_KERNEL_WORK_GROUP_SIZE, sizeof(workgroup_size), &workgroup_size, NULL); fprintf(stdout, "Workgroup size: %ld\n", workgroup_size); Finally, we call the gcl_get_kernel_block_workgroup_info function to once more to ask OpenCL for a workgroup size multiple. This is a performance hint based on the capabilities of the underlying device: gcl_get_kernel_block_workgroup_info( square_kernel, // this kernel CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE, sizeof(preferred_workgroup_size_multiple), &preferred_workgroup_size_multiple, NULL); Using Grand Central Dispatch With OpenCL Obtaining the Kernel’s Workgroup Size 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 35You can now use these workgroup valuesto craft an appropriate cl_ndrange structure to use in launching your kernel. cl_ndrange range = { 1, // The number of dimensions to use. {0, 0, 0}, // The offset in each dimension. We want to // process ALL of our data, so this is 0 for // our test case. // Always pass an offset for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. {NUM_VALUES, 0, 0}, // The global range -- this is how many items // IN TOTAL in each dimension you want to // process. // Always pass the global range for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. {workgroup_size, 0, 0 } // The local size of each workgroup. This // determines the number of workitems per // workgroup. It indirectly affects the // number of workgroups, since the global // size / local size yields the number of // workgroups. So in our test case, we will // have NUM_VALUE/workgroup_size workgroups. // Always pass the workgroup size for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. }; Using Grand Central Dispatch With OpenCL Obtaining the Kernel’s Workgroup Size 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 36Sample Code: Creating a Dispatch Queue Listing 5-1 (page 37) demonstrates how to get the global OpenCL context, and how to ask that context about the devices it contains. It also shows how to create a dispatch queue by asking for a device type (CPU or GPU), and by specifying the queue's OpenCL device directly. Listing 5-2 (page 40) shows how to obtain workgroup information -- useful for obtaining peak performance -- from the kernel block. Listing 5-1 Creating a dispatch queue #include // Include OpenCL/opencl.h to include everything you need for OpenCL //development on OS X v10.7. #include // In this example, mykernel.cl.h is the header file that contains our kernel block // declaration. // This header file is generated by Xcode. #include "mykernel.cl.h" static void print_device_info(cl_device_id device) { char name[128]; char vendor[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, 128, name, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, 128, vendor, NULL); fprintf(stdout, "%s : %s\n", vendor, name); } #pragma mark - #pragma mark Hello World - Sample 1 // Demonstrates how to get the global OpenCL context, and how to ask that // context about the devices it contains. It also shows how // to create a dispatch queue by asking for a device type (CPU or GPU) and Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 37// by specifying the queue's OpenCL device directly. static void hello_world_sample1 () { int i; // Ask for the global OpenCL context: // Note: If you will not be enqueing to a specific device, you do not need // to retrieve the context. cl_context context = gcl_get_context(); // Query this context to see what kinds of devices are available to us. size_t length; cl_device_id devices[8]; clGetContextInfo( context, CL_CONTEXT_DEVICES, sizeof(devices), devices, &length); // Walk over these devices, printing out some basic information. We could // query any of the information available about the device here. fprintf(stdout, "The following devices are available for use:\n"); int num_devices = (int)(length / sizeof(cl_device_id)); for (i = 0; i < num_devices; i++) { print_device_info(devices[i]); } // To do any work, you need to create a dispatch queue associated // with some OpenCL device. You can either let the system give you // a GPU -- perhaps the only GPU -- or the CPU device. Or, you can // create a dispatch queue with a cl_device_id you specify. This // device id comes from the OpenCL context, as above. Below are three // examples. Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 38// 1. Ask for a GPU-based dispatch queue; notice that we do not provide a // device id - we let the system give us the most capable GPU. dispatch_queue_t gpu_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Get the device from the queue, so we can ask OpenCL questions about it. // Note that we check to make sure there WAS an OpenCL-capable GPU in the // system by checking against a NULL return value. if (gpu_queue != NULL) { cl_device_id gpu_device = gcl_get_device_id_with_dispatch_queue(gpu_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_GPU gives us:\n"); print_device_info(gpu_device); } else { fprintf(stdout, "\nYour system does not contain an OpenCL-compatible " "GPU\n."); } // 2. Let's try the same thing for CL_DEVICE_TYPE_CPU. All Macintosh // systems will have a CPU OpenCL device, so we don't have to worry about // checking for NULL, as we did in the case of a GPU. dispatch_queue_t cpu_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); cl_device_id cpu_device = gcl_get_device_id_with_dispatch_queue(cpu_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_CPU gives us:\n"); print_device_info(cpu_device); // 3. Or perhaps you are in a situation where you want a specific device // from the list of devices you found on the context. Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 39// Notice the difference here: // We pass CL_DEVICE_TYPE_USE_ID and a device_id. We'll just use the // first device on the context from above, whatever that might be. dispatch_queue_t custom_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_USE_ID, devices[0]); cl_device_id custom_device = gcl_get_device_id_with_dispatch_queue(custom_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_USE_ID and our own device gives us:\n"); print_device_info(custom_device); // Now we could use any of these dispatch queues to run some kernels! // Use the GCD API to free your queues. dispatch_release(custom_queue); dispatch_release(cpu_queue); if (gpu_queue != NULL) dispatch_release(gpu_queue); } Listing 5-2 Obtaining workgroup information #pragma mark - #pragma mark Hello World - Sample 2 // This listing shows how to obtain workgroup info – // useful for obtaining peak performance - from the kernel block. static void hello_world_sample2() { // Get a queue backed by a GPU for running our squaring kernel. dispatch_queue_t queue = Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 40gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Did we get a GPU? If not, fall back to the CPU device. if (queue == NULL) { gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); } // In any case, print out the device we're using: fprintf(stdout, "\nExamining workgroup info for square_kernel on device "); print_device_info(gcl_get_device_id_with_dispatch_queue(queue)); // Now find out what OpenCL thinks is the best workgroup size for // executing this kernel on this particular device. Notice that we have // to execute this method in a block, on a dispatch queue we've created // with OpenCL. dispatch_sync(queue, ^{ size_t wgs, preferred_wgs_multiple; cl_ulong local_memsize, private_memsize; // The next two calls give us information about how much // memory, local and private, is used by the kernel on this // particular device. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_LOCAL_MEM_SIZE, sizeof(local_memsize), &local_memsize, NULL); fprintf(stdout, "Local memory size: %lld\n", local_memsize); gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_PRIVATE_MEM_SIZE, sizeof(private_memsize), &private_memsize, NULL); Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 41fprintf(stdout, "Private memory size: %lld\n", private_memsize); // Here we ask OpenCL what it considers the optimal workgroup // size for this kernel on this device. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(wgs), &wgs, NULL); fprintf(stdout, "Workgroup size: %ld\n", wgs); // Finally, we can ask OpenCL for a workgroup size multiple. // This is a performance hint. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE, sizeof(preferred_wgs_multiple), &preferred_wgs_multiple, NULL); fprintf(stdout, "Preferred workgroup size multiple: %ld\n", preferred_wgs_multiple); // You could now use these workgroup values to craft an // appropriate cl_ndrange structure for use in launching your kernel. }); dispatch_release(queue); } int main(int argc, const char* argv[]) { hello_world_sample1(); hello_world_sample2(); } Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 42This chapter provides an overview of how memory is used with OpenCL (since this differsfrom the way memory is used in conventional programs), describes how buffers are created and used in OpenCL, describes how images are created and used in OpenCL, and provides information about using memory in situations such as with IOSurfaces and OpenGL textures. Overview Like all computational processes, processes that run on OpenCL devices consist of: ● Data The data accessed by OpenCL instructions exists as memory buffers and cl_image memory objects. Use image objects for representing 2D or 3D images (see “Creating and Using Images in OpenCL” (page 54)); use buffer objects for containing other types of generic data (see “Creating and Using Buffers in OpenCL” (page 46)). ● Instructions (in kernel functions) that manipulate the data. Even if they are physically contiguous, host memory is distinct from OpenCL memory. Kernel instructions can only access data in the memory of OpenCL devices. The host computer can read and write to device memory, but only to set it up and retrieve results. During computation, a device looks only in device memory, and the host stays out of its way. In other words, in OpenCL, you launch a set of work items against a bolus of data. While this data might have been passed to the OpenCL device by the host, the data resides on the OpenCL device at the time of execution. A kernel cannot read or write to the host memory; it can only access data its own separate memory area. For many devices(like GPUs), the OpenCL is actually a physically distinct piece ofsilicon. For other devices, although the memory is physically on the same chip, it can only be read/written by the OpenCL kernel code. Workflow The basic workflow with OpenCL is: 1. Create memory objects for use by OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 43 Creating and Managing Memory Objects in OS X OpenCLThe host requests that memory be set aside for it on the device. The host can ask for as many memory objects as it wants, up to the memory available. 2. Initialize the contents of the memory objects a. The host can pass data to the device to be stored in its memory objects. Thisisthe data that the kernel will process. The host can also instruct the device to leave some memory objects uninitialized so that when the kernel runs on the device, it can fill up these memory objects as its output. b. The host instructs the device to execute the kernel, passing it the memory objects it has created on the OpenCL device as arguments. The host will wait until the kernel is done. 3. Execute the kernel The kernel runs on the device, processing the data in the input memory, producing output to be stored in the designated output memory. 4. Read results from the memory objects When the host detects that the kernel has completed its tasks, it copies the results the kernel stored in the designated output memory into memory the host can access." 5. Destroy the memory objects Once the host has retrieved the output data, it instructs the device to free up the memory it had set aside for the kernel to use. Memory Visibility In a typical multi-device environment, memory is distributed between devices. No device can access all memory. For example, an OpenCL kernel resides in a separate memory space from the host that calls it. In order for the kernel to accessthe data it isto process, the data must be moved into the device’s memory. However, transferring data between memory areas to allow different devices to work can result in considerable overhead. Minimize the amount of data being transferred to optimize performance. The host specifies the memory space for a given buffer when it declares each kernel argument. Creating and Managing Memory Objects in OS X OpenCL Overview 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 44The memory spaces as an OpenCL device would see them are: Figure 6-1 Physical memory of an OpenCL system OpenCL Device Host Work Item Local Memory Workgroup Global/Constant Memory Host Memory Private Memory Work Item Private Memory Work Item Local Memory Workgroup Private Memory Work Item Private Memory ● Private memory Each work item has memory that only it can see. This is its private memory. ● Local memory Local memory is memory that work items WITHIN a work group can share. Local memory is useful if more than one work item in a group needs to use a particular chunk of global memory. You can write your OpenCL program so that one work item loads from global memory to local memory, and then the rest of the work items that need that piece of data can use the "local" copy. It takes GPU devices much less time to access local memory than to access global memory. ● Global memory This is the (relatively) massive chunk of device memory that ALL work items can "see". Any work item can read / write to a buffer declared to be in global memory. ● Constant memory Creating and Managing Memory Objects in OS X OpenCL Overview 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 45Thisis a specialized section of global memory for data that you the programmer know will remain constant throughout the execution of your kernel. It is more limited in size than global memory (typically), but is faster to access on many devices than other global memory. Memory Consistency Changes a work item has made to global or local memory may not immediately become visible to other work items within a workgroup. An system’s consistency has to do with when changes a work item has made to global or local memory become visible to other work items within a workgroup. OpenCL uses what is called a relaxed memory consistency model, which means that: ● Work items can access data within their own private memory, local memory, constant memory, and global memory. ● Work items can share local memory during the execution of a workgroup. However, memory is only guaranteed to be consistent after specific synchronization points. If a work item needs to read something that another work item has written, then you will need to place a barrier in your OpenCL code at the point where you want the memory to be consistent. The barrier will stop any work item at the barrier until all other work items have "caught up". That's why it works -- every work item in the workgroup has written its memory by that point, so it's safe to go on and read anything any work item in the group has written. See “Using GCD To Synchronize A Host With OpenCL” (page 69). Note: You can create a barrier that appliesto local memory or to global memory, but consistency only appliesto work items within a work group. There is no such thing as a global memory barrier that will make all threads in an execution wait. OpenCL only guarantees memory consistency at a barrier within a work group. Creating and Using Buffers in OpenCL Representing Data With Buffer Objects The OpenCL programming interface provides buffer objects for representing generic data in your OpenCL programs. Instead of having to convert your data to the domain of a specific type of hardware, OpenCL enables you to transfer your data as is to an OpenCL device via buffer objects and operate on the data using the same language features that you are accustomed to in C. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 46OpenCL is designed to share efficiently with OpenGL. Wherever possible, data is shared between OpenCL and OpenGL programs; it is not copied. Because transmitting data is costly, it is best to minimize reads and writes as much as possible. By packaging all of your host data into a buffer object that can remain on the device, you reduce the amount of data traffic necessary to process your data. Allocating Memory For Buffer Objects In OS X v10.7 If you need a cl_mem object, (you will need one of these if you are going to be using a standard OpenCL API call), call the gcl_malloc function to allocate the memory, then call the gcl_create_buffer_from_ptr function to convert the handle gcl_malloc returns for use with the standard OpenCL API. To create buffer objects: ● void * gcl_malloc(size_t bytes, void *host_ptr, cl_malloc_flags flags) The gcl_malloc function returns a void * which is a memory object handle. The bytes parameter is the number of bytes to be allocated. The host_ptr parameter . The flags parameter and can be 0 or CL_MEM_USE_HOST_PTR. Note: The void * value returned cannot be used to directly access the memory region on the host CPU. To access this memory region for reading and writing on the host CPU, use APIs such as cl_memcpy that can be passed in a block to GCD APIs that queue tasks for dispatch. ● cl_mem gcl_create_buffer_from_ptr(void *ptr) The cl_mem gcl_create_buffer_from_ptr function creates a cl_mem buffer object from a ptr returned by cl_malloc. The cl_mem object returned can be used by CL API calls to enable sharing of objects between Grand CL and the OpenCL API. The cl_mem object returned references the data store associated with the ptr parameter. Note: Be sure to release cl_mem objects created using gcl_create_buffer_from_ptr before freeing this pointer using gcl_free. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 47Reading, Writing, and Copying Buffer Objects You can create memory objects outside a dispatch queue and the memory objects you create do not have to be associated with any particular device. But before the memory object is accessed by OpenCL, it must be associated with the device the data will be moving into and out of. You associate a memory object with its device in the dispatch queue.. After you’ve created a buffer object, you can enqueue reads, writes, and copies. You can call the following functions from your host application. These can be passed in a block(s) to the Grand Central Dispatch APIs that queue tasks for dispatch such as dispatch_async. They enable you to move data to and from a host. void gcl_memcpy(void *dst, const void *src, size_t size); void gcl_memcpy_rect(void *dst, const void *src, const size_t dst_origin[3], const size_t src_origin[3], const size_t region[3], size_t dst_row_pitch, size_t dst_slice_pitch, size_t src_row_pitch, size_t src_slice_pitch); void *gcl_map_ptr(void *ptr, cl_map_flags map_flags, size_t cb); void *gcl_map_image(cl_image image, cl_map_flags map_flags, const size_t origin[3], const size_t region[3]); void gcl_unmap(void *ptr); Kernel Support For Data Processing In OpenCL-C By associating your buffer object with specific kernel arguments, you make it possible to process your data from the context of a kernel function. For example, in “Example: Allocating, Using, Releasing Buffer Objects” (page 50), notice how the code sample treats the input data pointer much as you would treat a pointer in C. In this example the input data is an array of float values, and you can process each element of the float array by indexing into the pointer. “Example: Allocating, Using, Releasing Buffer Objects” (page 50) does little more than multiply a value by itself using the * operator, but OpenCL-C provides a wide array of data types and operators that enable you to perform more complex arithmetic. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 48Because OpenCL-C is based on C99, you are free to process your data in OpenCL-C functions as you would in C with few limitations. Aside from support for recursion and function pointers, there are not many language features that C has that OpenCL-C doesn’t have. In fact, OpenCL-C provides several beneficial features that the C programming language does not offer natively, such as optimized image access functions. OpenCL-C has built-in support for vector intrinsics and offers vector data types. The operators in OpenCL-C are overloaded, and performing arithmetic between vector data typesissyntactically equivalent to performing arithmetic between scalar values. Refer to the TheOpenCL Specification for more details on the built-in functions and facilities of the OpenCL-C language. Releasing Buffer Objects To avoid memory leaks, free buffer objects when they are no longer needed. Call gcl_free to free buffer objects created using gcl_malloc. void gcl_free(void *ptr); The ptr parameter is the handle of the buffer object to be released. OpenCL uses a reference counting system to keep track of the memory objects currently being used. The reference count represents how many other objects hold referencesto the particular memory object. Any time you create a buffer object, it immediately receives a reference count of 1. Any time another object would also like to maintain a reference to it, it should increment the buffer object’s reference count by calling the clRetainMemObject function. When an object wishes to relinquish its reference to a buffer object, it should call clReleaseMemObject. When the reference count for a buffer object reaches zero, OpenCL frees it, returning the memory to the system and making any persisting references to the buffer object invalid. Setting the finalizer A finalizer is a function member of a reference class that is called automatically by the garbage collector when destroying an object. To specify which finalizer function the garbage collector calls for any objects created by gcl_malloc or gcl_create_*** APIs (such as gcl_create_image), call: void gcl_set_finalizer(void *object, void (*gcl_pfn_finalizer)(void *object, void *user_data), void *user_data); Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 49Example: Allocating, Using, Releasing Buffer Objects In the following example, the host creates one input buffer and one output buffer, initializes the input buffer, calls the kernel to square each value in the input buffer, then checks the results. Listing 6-1 Sample host function creates buffers then calls kernel function #include #include #include // Include the automatically-generated header which provides the kernel block // declaration. #include "kernels.cl.h" #define COUNT 2048 static void display_device(cl_device_id device) { char name_buf[128]; char vendor_buf[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, sizeof(char)*128, name_buf, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, sizeof(char)*128, vendor_buf, NULL); fprintf(stdout, "Using OpenCL device: %s %s\n", vendor_buf, name_buf); } static void buffer_test(const dispatch_queue_t dq) { unsigned int i; // We'll use a semaphore to synchronize the host and OpenCL device. dispatch_semaphore_t dsema = dispatch_semaphore_create(0); // Create some input data on the _host_ ... Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 50cl_float* host_input = (float*)malloc(sizeof(cl_float) * COUNT); // ... and fill it with some initial data. for (i=0; i #include #include // Include the automatically-generated header which provides the kernel block // declaration. #include "kernels.cl.h" #define COUNT 2048 static void display_device(cl_device_id device) { char name_buf[128]; Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 59char vendor_buf[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, sizeof(char)*128, name_buf, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, sizeof(char)*128, vendor_buf, NULL); fprintf(stdout, "Using OpenCL device: %s %s\n", vendor_buf, name_buf); } static void image_test(const dispatch_queue_t dq) { // As before, we use a dispatch semaphore to achieve synchronization between // the host application and the work done for us by the OpenCL device. dispatch_semaphore_t dsema = dispatch_semaphore_create(0); // Let's create a "fake" RGBA, 8-bit-per channel image, solid red. // In a real program, you would use some real raster data. // Most OpenCL devices support a wide-variety of image formats. unsigned int i; size_t height = 2048, width = 2048; unsigned int *pixels = (unsigned int*)malloc( sizeof(unsigned int) * width * height ); for (i = 0; i < width*height; i++) pixels[i] = 0xFF0000FF; // 0xAABBGGRR: 8bits per channel, all red. // This image data is on the host side. // We need to create two OpenCL images in order to perform some // manipulations: one for the input and one for the ouput. // This describes the format of the image data. cl_image_format format; format.image_channel_order = CL_RGBA; Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 60format.image_channel_data_type = CL_UNSIGNED_INT8; cl_mem input_image = gcl_create_image(&format, width, height, 1, NULL); cl_mem output_image = gcl_create_image(&format, width, height, 1, NULL); dispatch_async(dq, ^{ // Our kernel is written such that each work item processes one pixel. // Thus, we execute over a two-dimensional range, // with the width and height of the image determining the dimensions // of execution. cl_ndrange range = { 2, // We're using a 2-dimensional execution. {0}, // Start at the beginning of the range. {width, height}, // Execute width * height work items. {0} // And let OpenCL decide how to divide the work items // into work-groups. }; // Copy the host-side, initial pixel data to the image memory object on // the OpenCL device. We copy the whole image, but you could use the // origin and region parameters to specify an offset and sub-region of // the image, if you'd like. const size_t origin[3] = { 0, 0, 0 }; const size_t region[3] = { width, height, 1 }; gcl_copy_ptr_to_image(input_image, pixels, origin, region); // Do it! red_to_green_kernel(&range, input_image, output_image); // Read back the results; let's reuse the host-side buffer we started with. gcl_copy_image_to_ptr(pixels, output_image, origin, region); Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 61// Let the host know we're done. dispatch_semaphore_signal(dsema); }); // Do other work, if you'd like... // ... but eventually, you will want to wait for OpenCL to finish up. dispatch_semaphore_wait(dsema, DISPATCH_TIME_FOREVER); // Alright - we expect '0xFF00FF00' for each pixel. Solid green, all the way. int results_ok = 1; for (i = 0; i < width*height; i++) { if (pixels[i] != 0xFF00FF00) { fprintf(stdout, "Oh no. Pixel %d was not correct. Expected 0xFF00FF00, saw %x\n", i, pixels[i]); results_ok = 0; break; } } if (results_ok) fprintf(stdout, "Image results OK!\n"); // Clean up device-size allocations. // Note that we use the "standard" OpenCL API here. clReleaseMemObject(input_image); clReleaseMemObject(output_image); // Clean up host-side allocations. free(pixels); } int main (int argc, const char * argv[]) Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 62{ // Grab a CPU-based dispatch queue. dispatch_queue_t dq = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); if (!dq) { fprintf(stdout, "Unable to create a CPU-based dispatch queue.\n"); exit(1); } // Display the OpenCL device associated with this dispatch queue. display_device(gcl_get_device_id_with_dispatch_queue(dq)); image_test(dq); fprintf(stdout, "\nDone.\n\n"); dispatch_release(dq); } Listing 6-6 Sample kernel swaps the red and green channels // A simple kernel that swaps the red and green channels. const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE | CLK_FILTER_NEAREST; kernel void red_to_green(read_only image2d_t input, write_only image2d_t output) { size_t x = get_global_id(0); size_t y = get_global_id(1); uint4 tap = read_imageui(input, sampler, (int2)(x,y)); write_imageui(output, (int2)(x,y), tap.yxzw); } Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 63IOSurface and GL: What OpenCL Supports How the Kernel Interacts With Data Passing Data To a Kernel Xcode uses your kernel code to automatically generate the kernel function prototype in the kernel header file. To pass data to a kernel, when you call the kernel from your host code, passthe memory objects as parameters, just as you would pass parameters to any other function. OpenCL kernel arguments can be scoped with a local or global qualifier, designating the memory storage for these arguments. In OS X v10.7, for arguments to OpenCL kernels that would have been declared with the local or __local address qualifier, the argument type used in the block declaration of the kernel will be a size_t. Consider the following kernel that has an argument declared with the local address qualifier: kernel void foo(global float *a, local float *shared); The extern declaration of this kernel block that will be generated for you in the host code will be: extern void (^foo_kernel)(const cl_ndrange *ndrange, float *a, size_t shared); Accessing Buffer Objects From a Kernel Once the data has been enqueued, in order for a device to actually process this data, you have to make this data available to the work items that execute on the device. The following sections show you how to pass your data to the compute kernels for further processing. In your host application source code, it’s your responsibility to: ● Prepare the input data. ● Create a buffer object of the appropriate size. ● Move the input data from host memory. You can do this using the clCreateBuffer function by pointing to the data on the host, or you can use the clEnqueueWriteBuffer function to enqueue a write from host memory. ● Associate the input data with the kernel’s arguments. Use the clSetKernelArg function to do this. Creating and Managing Memory Objects in OS X OpenCL IOSurface and GL: What OpenCL Supports 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 64Kernels written in OpenCL-C need a data structure to describe the data parallel range over which to execute the kernel. In OS X v10.7, you’ll use the cl_ndrange structure for this purpose: typedef struct _cl_ndrange { size_t work_dim; size_t global_work_offset[3]; size_t global_work_size[3]; size_t local_work_size[3]; } cl_ndrange; Retrieving Results From a Kernel To read the results back, call dispatch_sync. For example, dispatch_sync(queue, ^{ gcl_memcpy(ptr_c, device_c,num_floats * sizeof(float)); }); Creating and Managing Memory Objects in OS X OpenCL How the Kernel Interacts With Data 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 65OpenGL (Open Graphics Library) is an API for writing applications that produce 2D and 3D computer graphics. See OpenGL. OpenCL / OpenGL interoperability enables applicationsto share data between OpenCL and OpenGL efficiently. You do not have to create multiple copies of the same content in OpenCL and OpenGL. An OpenCL memory object created from an OpenGL object and the original OpenGL object both refer to the same memory and both GLSL (OpenGL Shading Language) shaders and OpenCL kernels can access the shared data. Another advantage of using OpenCL / OpenGL interoperability isthat the overhead of passing data for compute/display purposes is greatly reduced. If the computation and rendering are performed on the GPU, the data need not be moved between the host and the GPU. This chapter describes the OpenCL APIs that can be used to create OpenCL memory objects from OpenGL vertex buffer objects(VBOs), texture objects, and renderbuffer objects. An OpenCL buffer object may be created from an OpenGL buffer object. An OpenCL image object may be created from an OpenGL texture or renderbuffer object. To create an OpenCL memory object from an OpenGL object, an OpenCL context has to be created from an OpenGL share group (CGLShareGroup) object. An OpenGL share group object manages the OpenGL objects on the devices in the rendering context. When an OpenCL context is connected to an OpenGL share group object, both the OpenCL context and the OpenGL context can reference the same data objects. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 66 OpenCL/ OpenGL Interoperation: Data SharingSharegroups In the example illustrated in Figure 7-1 (page 67), OpenCL is used to generate geometry on the GPU and OpenGL is used to render the shared geometry, also using the GPU. The OpenCL and OpenGL contextsreference the same sharegroup (CGLShareGroupObj). Both OpenCL and OpenGL see the same devices and can access the shared geometry. OpenGL sees the data as a VBO and OpenCL sees it as a buffer memory object. Figure 7-1 OpenGL and OpenCL share data using sharegroups CPU GPU OpenCL CGLShareGroupObj cl_context cl_mem VBO gl_context To use OpenCL / OpenGL interoperability: 1. Set the sharegroup: CGLContextObj cgl_context = CGLGetCurrentContext(); CGLShareGroupObj sharegroup = CGLGetShareGroup(cgl_context); gcl_gl_set_sharegroup(sharegroup); ... 2. After the sharegroup has been set, you can create OpenCL memory objects from the existing OpenGL objects: ● Use the following API to create an OpenCL buffer object from an OpenGL buffer object: void * gcl_gl_create_ptr_from_buffer(GLuint bufobj); ● Use the following API to create an OpenCL image object from an OpenGL texture object: OpenCL/ OpenGL Interoperation: Data Sharing Sharegroups 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 67cl_image gcl_gl_create_image_from_texture( GLenum texture_target, GLint mip_level, GLuint texture); ● Use the following API to create an OpenCL 2D image object from an OpenGL render buffer object: cl_image gcl_gl_create_image_from_renderbuffer(GLuint render_buffer); Synchronizing Access To Shared OpenCL/OpenGL Objects To ensure data integrity, the application is responsible for synchronizing access to shared OpenCL/OpenGL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations. For information about synchronizing OpenCL and OpenGL events and fences, see “Controlling OpenCL/OpenGL Interoperation With GCD” (page 69). Example OpenCL/ OpenGL Interoperation: Data Sharing Synchronizing Access To Shared OpenCL/OpenGL Objects 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 68An application running on a host (a CPU) can route work or data (possibly in disparate chunks) to a device using the standard OpenCL and OpenGL APIs and OS X v10.7 extensions. While the device does the work it has been assigned, the host can continue working asynchronously. But at a certain point, the host will need to wait for the results generated by the device performing the work it was assigned,so it will wait for the device to notify it that the assigned work has been completed. OpenCL and OpenGL can also share work and data. Typically, OpenCL will be used to generate or modify buffer data which will then be rendered by OpenGL. Or, you might use OpenGL to create an image and then post-process it using OpenCL. In either case, you have to make sure you synchronize correctly. This chapter describes how to use GCD to synchronize: ● A host with OpenCL See “Using GCD To Synchronize A Host With OpenCL” (page 69). ● A host with OpenCL using a dispatch semaphore See “Synchronizing A Host With OpenCL Using A Dispatch Semaphore” (page 70). ● Multiple OpenCL Queues See “Synchronizing Multiple Queues” (page 75). You can still use the standard OpenCL and OpenGL APIs to obtain fine-grained synchronization when working on shared data, where you either: ● Call OpenGL then OpenCL ● Call OpenCL then OpenGL See the OpenGL and OpenGL specifications for more information. Using GCD To Synchronize A Host With OpenCL In Listing 8-1 (page 70), the host enqueues data in two queues to Grand Central Dispatch. The queued data is processed while the host continues to do its own work. When the host needs the results, it waits for both queues to complete their work. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 69 Controlling OpenCL/OpenGL Interoperation With GCDListing 8-1 Synchronizing the host with OpenCL processing // Create a workgroup so host can wait for results from more than one kernel. dispatch_group_t group = dispatch_group_create(); // Enqueue some of the data to the add_arrays_kernel on q0. dispatch_group_async(group, q0, ^{ // Because the call is asynchronous, // the host will not wait for the results cl_ndrange ndrange = { 1, {0}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Enqueue some of the data to the add_arrays_kernel on q1. dispatch_group_async(group, q1, ^{ // Because the call is asynchronous, // the host will not wait for the results cl_ndrange ndrange = { 1, {N/2}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Perform more work independent of the work being done by the kernels. ... // At this point, the host needs the results before it can proceed. // So it waits for the entire workgroup (on both queues) to complete its work. dispatch_group_wait(group, DISPATCH_TIME_FOREVER); Synchronizing A Host With OpenCL Using A Dispatch Semaphore The sample Listing 8-2 (page 71) illustrates how you can use OpenCL and OpenGL together in an application. In this example, we create two vertex buffer objects (VBOs) using OpenGL (not shown). These VBOs represent the positions of some objects in an N-body simulation. We then create OpenCL memory objects from these VBOs (line [2]), which allows us to operate directly on the device memory containing this data in our OpenCL kernel. We update these positions according to our desired algorithm, expressed as a per-object operation in the included kernel, and then render the resulting VBO using OpenGL (commented, but not shown, at [4]). Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 70Since we are updating positions using OpenCL on a dispatch queue that runs asynchoronously with respect to the thread that does the OpenGL rendering, we need to take action to ensure that we do not render before the kernel has finished updating the positions. We utilize a mechanism that is common in applications that require synchronization in GCD-compatible applications: a dispatch semaphore. Before entering the main loop, we create a dispatch_semaphore_t (line [1]). In the block that we submit to the dispatch queue created in OpenCL, just after our kernel call, we signal the semaphore. Meanwhile, the "main" thread of execution has been rolling along -- perhaps doing more work -- eventually arriving at the call to dispatch_semaphore_wait(...) (line [3]). The main thread stops at this point and waits until the post-kernel signal "flips" the semaphore. Once that occurs, the code can continue to the OpenGL rendering portion of the code, safe in the knowledge that the position update for this round is complete. Figure 8-1 Rendering loop - each pass on the main thread creates a new frame for display Synchronization point “I’m done” OpenCL-created Dispatch Queue integration_kernel(…) Just might take a bit of time dispatch_semaphore_wait(…) “Main” Thread of Execution dispatch_async(…) Note: that the main thread could do other work here before stopping to wait. But eventually, we call: dispatch_semaphore_wait(…) Here we sit and wait on CL to be done. render_with_OpenGL(…) glFlush(…) Listing 8-2 Synchronizing a host with OpenCL using a dispatch semaphore // In this case, the kernel code will update the position of the vertex. ... // The host code is: // Create the dispatch semaphone. [1] Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 71dispatch_queue_t queue; dispatch_semaphore_t cl_gl_semaphore; void *pos_gpu[2], *vel_gpu[2]; GLuint vbo[2]; float *host_pos_data, *host_vel_data; int num_bodies; int curr_read_index, curr_write_index; // Extern OpenCL kernel declarations extern void (^integrateNBodySystem_kernel)(const cl_ndrange *ndrange, float4 *newPos, float4 *newVel, float4 *oldPos, float4 *oldVel, float deltaTime, float damping, float softening, int numBodies, size_t sharedPos); void initialize_cl() { gcl_gl_set_sharegroup(CGLGetShareGroup(CGLGetCurrentContext()); // Create a CL dispatch queue. queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Create a dispatch semaphore used for CL / GL sharing. cl_gl_semaphore = dispatch_semaphore_create(0); // Create CL objects from GL VBOs that have already been created. [2] pos_gpu[0] = gcl_gl_create_ptr_from_buffer(vbo[0]); pos_gpu[1] = gcl_gl_create_ptr_from_buffer(vbo[1]); vel_gpu[0] = gcl_malloc(sizeof(float4)*num_bodies, NULL, 0); vel_gpu[1] = gcl_malloc(sizeof(float4)*num_bodies, NULL, 0); Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 72// Allocate and generate position and velocity data // in host_pos_data and host_vel_data. // ... // Initialize CL buffers with host position and velocity data. dispatch_async(queue, ^{gcl_memcpy(pos_gpu[curr_read_index], host_pos_data, sizeof(float4)*num_bodies); gcl_memcpy(vel_gpu[curr_read_index], host_vel_data, sizeof(float4)*num_bodies);}); } void execute_cl_gl_main_loop() { // Queue CL kernel to dispatch queue. dispatch_async(queue, ^{ ndrange_t ndrange = { 1, {0}, {num_bodies} } ; // Get local workgroup size that kernel can use for // device associated with queue. gcl_get_kernel_block_workgroup_info( integrateNBodySystem_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(size_t), &nrange.local_work_size[0], NULL); // Queue CL kernel to dispatch queue. integrateNBodySystem_kernel(&ndrange, pos_gpu[curr_write_index], vel_gpu[curr_write_index], pos_gpu[curr_read_index], vel_gpu[curr_read_index], Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 73damping, softening, num_bodies, sizeof(float4)*ndrange.local_work_size[0]); // Signal the dispatch semaphore to indicate that // GL can now use resources. dispatch_semaphore_signal(cl_gl_semaphore);}); // Do work not related to resources being used by CL in dispatch block. // Need to use VBOs that are being used by CL so wait for the CL commands // in dispatch queue to be issued to the GPU’s command-buffer. [3] dispatch_semaphore_wait(cl_gl_semaphore, DISPATCH_TIME_FOREVER); // Bind VBO that has been modified by CL kernel. glBindBuffer(GL_ARRAY_BUFFER, pos_gpu[curr_write_index]); // Now render with GL. [4] // Flush GL commands. glFlush(); } void release_cl() { gcl_free(pos_gpu[0]); gcl_free(pos_gpu[1]); gcl_free(vel_gpu[0]); gcl_free(vel_gpu[1]); dispatch_release(cl_gl_semaphore); dispatch_release(queue); } Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 74Synchronizing Multiple Queues In Listing 8-3 (page 75), the host enqueues data in two queues to Grand Central Dispatch. The second queue waits for the first queue to complete its processing before doing its work. The host application does not wait for completion of either queue. Listing 8-3 Synchronizing multiple queues // Create the workgroup which will consist of just the work items // that must be completed first. dispatch_group_t group = dispatch_group_create(); dispatch_group_enter(group); // Start work on the workgroup. dispatch_async(q0, ^{ cl_ndrange ndrange = { 1, {0}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); dispatch_group_leave(group); }); // Simultaneously enqueue data on q1, // but immediately wait until the workgroup on q0 completes. dispatch_async(q1, ^{ // Wait for the work of the group to complete. dispatch_group_wait(group, DISPATCH_TIME_FOREVER); cl_ndrange ndrange = { 1, {N/2}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Host application does not wait. Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing Multiple Queues 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 75An IOSurface is an abstraction for sharing image data. IOSurfaces are an efficient way to manage image memory because when you use an IOSurface, if no copy is necessary, no time is wasted on making a copy. An IOSurface transcends APIs, architectures, address spaces, and processes. You can get an ID for an IOSurface that can be passed around from process to process, so that each of these completely separate programs can use one single IOSurface. This makessharing an IOSurface between devices very easy. If you create an OpenCL image memory object from an existing IOSurface, you can modify the data contained in the IOSurface either in your "main program" running on the CPU, or in an OpenCL kernel running on either a GPU or a CPU. Creating Or Obtaining An IOSurface You can either create an IOSurface in code (see for an example) or you can request an IOSurface from another running process such as Photo Booth. The underlying texture transfer mechanism for an IOSurface combines GL_UNPACK_CLIENT_STORAGE_APPLE and GL_STORAGE_HINT_CACHED_APPLE together. The transfer is done as a straight DMA to/from system memory and video memory with no format conversions of any kind (other than some GPU-specific memory layout details). No matter how many different OpenGL contexts (in the same process or not) bind a texture to an IOSurface, they all share the same system memory and GPU memory copies of the data. Creating An Image Object from An IOSurface Once you’ve created or obtained an IOSurface, before you use it in OpenCL, you need to create an OpenCL image memory object using the IOSurface. When you create the memory object, you are not making a copy; the image memory object points at the same memory asthe original IOSurface. This makes using the IOSurface very efficient. If you are using GCD to interact with the IOSurface, create the IOSurface-backed CL image as shown in Listing 9-1 (page 77). 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 76 Using IOSurfaces With OpenCLListing 9-1 Creating an IOSurface-backed CL Image cl_image gcl_create_image( const cl_image_format *image_format, size_t image_width, size_t image_height, size_t image_depth, IOSurfaceRef io_surface); // create a 2D image (depth = 0 or 1) or a 3D image (depth > 1). // can also be used to create an image from an IOSurfaceRef. If you are using the standard OpenCL API and not using GCD to create an IOSurface-backed CL object, use clCreateImageFromIOSurface2D as shown in Listing 9-2 (page 77). Listing 9-2 Extracting an Image From an IOSurface cl_image_format image_format; image_format.image_channel_order = CL_RGBA; image_format.image_channel_data_type = CL_UNORM_INT8; cl_mem image = clCreateImageFromIOSurface2D( context, flags, image_format, width, height, surface, &err ); Sharing the IOSurface With An OpenCL Device Sharing an IOSurface in OpenCL is very simple. The key is to lock the IOSurface properly. If your CPU (host) is going to modify the IOSurface and then share it with an OpenCL device, you should lock the IOSurface before reading or writing to it, then unlock it before passing it to a kernel: ● The host creates or obtains the IOSurface and creates its CL image object . ● If the host will be writing to the IOSurface, the host write-locks the IOSurface: IOSurfaceLock(..., write type lock). If the host will only read from the IOSurface, the host read-locks it. ● The host writes to/reads from the IOSurface as necessary. ● The host unlocks the IOSurface: IOSurfaceUnlock(...). This tells the system that you changed the data. You can then use the IOSurface-backed image in OpenCL -- the IOSurface object will handle any necessary read locking internally for you. Using IOSurfaces With OpenCL Sharing the IOSurface With An OpenCL Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 77● The host enqueues the OpenCL kernel, passing it the IOSurface. The locking and unlocking are simply the minimal calls needed to give OS X enough information to ensure that each device always gets the latest, correct data. If you will be using OpenCL to modify the IOSurface, you don't have to lock it. Just access the image memory object directly. Using IOSurfaces With OpenCL Sharing the IOSurface With An OpenCL Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 78The autovectorizer detects operations in a scalar program that can be run in parallel and converts them into sequential operations that can be handled efficiently by today's CPUs. The autovectorizer frees you to write simple scalar code. It then vectorizes that code for you so that its performance on the CPU is maximized while the same code runs on the GPU as well. Note: Some GPUs also give higher performance when your code is vectorized. The autovectorizer does not operate on GPU code, but you can vectorize your GPU code manually. If you do manually vectorize your GPU code, test both vectorized and unvectorized versions to see which gives better performance on specific hardware. Features ● Runs by default when compiling to the CPU. ● Packs work items together. ● Generates a loop over the entire workgroup. ● Can provide performance improvement of up to the vector width of the CPU without additional effort. ● Allows you to write one scalar kernel that runs on CPU or GPU. Without the Autovectorizer The issue is that a GPU will process scalar data efficiently, but the CPU needs vectorized data to keep it fully busy. Which means that, without the autovectorizer, you either have to write multiple device-specific kernels that all perform the same function, or your performance will suffer. OpenCL sees devices as having a number of compute cores and within them a number of processing elements. When scalar code runs on the CPU, it will run on each core but will not take advantage of the vector unit. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 79 AutovectorizerFor example, on a SSE4 machine, scalar code would run in one lane of the vector unit when it could be running in four lanes. The monitor would report that the CPU is completely busy because all the cores are running, but the CPU is actually only using a quarter of its vector width. Figure 10-1 Before autovectorization: A simple float sent to the CPU and the GPU CPU GPU If you pass simple floats into a kernel: Listing 10-1 Passing single floats into a kernel kernel void add_arrays(global float* a, global float* b, global float* c) { size_t i = get_global_id(0); c[i] = a[i] + b[i]; } The kernel will be doing a scalar addition; operating on one data element at a time. If you send the scalar float to the CPU and the GPU, the GPU will become fully engaged in processing the data. In the CPU, although all the cores are busy, only one quarter of the vector width of the processing element in each core is used. If you instead passin float4* parametersto the kernel, that makesthe addition a vector addition. The addition is now CPU-only, specialized for that device. That would extract as much work as possible from the CPU but leave the GPU idle. In other words, without the autovectorizer, you would have to write multiple device-specific, non-scalar kernels, one for each type of device. Autovectorizer Without the Autovectorizer 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 80Writing Optimal Code For the CPU: Let the autovectorizer do the work for you Do ● Write one simple (non-vectorized) kernel that can run on any device. Don’t ● Write device-specific optimizations. ● Write work item ID-dependent control flow, if possible. (If this occurs in many places in the code, it would likely prevent autovectorization from succeeding.) What the autovectorizer does ● Runs by default whenever compiling kernels to a CPU. ● Packs work items together into vector instructions. ● Workgroup size can be increased if autovectorization is successful. ● Achieves performance improvements of up to the vector width of the CPU without additional effort on your part. Vectorization Example Xcode Setting Type Default Command Line Flag -cl-auto-vectorize-enable If this is set to NO, the command line flag should be -cl-autovectorize- disable Auto-vectorizer Boolean YES Autovectorizer Writing Optimal Code For the CPU: Let the autovectorizer do the work for you 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 81This chapter providessuggestions asto how to structure OpenCL code so that it runs most efficiently, describes how to measure performance of OpenCL applications, and what to expect - how to set performance objectives. It also provides an example of an iterative process of performance tuning of a simple image filter application. Before Optimizing Code Before you decide to optimize code, it is important to answer the following questions: 1. Does the code really need to be optimized? This is the most important question, and answering it is not trivial when the OpenCL code is used inside a large application. Answering this question is out of the scope of this document, but it should be considered seriously before starting any optimization effort. 2. How to measure the performance of the code? 3. What is the expected performance? Reducing Overhead Here are some general principles you can follow to improve the efficiency of your OpenCL code: ● Choose an efficient algorithm. OpenCL can take advantage of all the devices in the system, but only if the algorithms in your program are written to allow parallel processing. Consider the following when choosing an algorithm: ● The algorithm should be massively parallel, so that the computation can be carried out by a large number of independent work items: For data parallel calculations on a GPU, OpenCL works best where many work items are submitted to the device.. When sending work to a CPU, which typically has fewer cores than the GPU, it is important to match the number of work items to the number of threads the CPU can effectively support. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 82 Improving Performance● Most algorithms are memory-bound. Consequently, algorithms with the fewest memory accesses or algorithms with a high compute:memory ratio are usually best for OpenCL applications. The compute:memory ratio is the ratio between the number of floating-point operations and the number of bytes transferred to and from memory. ● OpenCL is most efficient on large datasets. If possible, select an algorithm that works on large chunks of data or merge several smaller tasks into one. ● For data parallel calculations on a GPU, OpenCL works best where there are a lot of work items submitted to the device; however, some algorithms are much more efficient than others. ● Building an OpenCL program is computationally expensive and should ideally occur only once in a process. Be sure to take advantage of tools in OS X v10.7 that allow you to compile once and then run many times. If you do choose to compile a kernel during runtime, you will need to execute that kernel many times to amortize the cost of compiling it. You can save the binary after the first time the program is run and reuse the compiled code on subsequent invocations, but be prepared to recompile the kernel if the build fails because of an OpenCL revision or a change in the hardware of the host machine. You can also use bitcode generated by the OpenCL compiler instead of source code; compilation will be much faster and you won’t have to ship source code with your application. ● Moving data to or from OpenCL devices is expensive. OpenCL gives you complete control over allocation of memory and host-device memory transfers. Your program will run much faster if you allocate memory on the OpenCL device, move your data to the device, do as much computation as possible on the device, then move it off—rather than repeatedly going through write-compute-read cycles. ● Allocating and freeing OpenCL resources (memory objects, kernels, etc.) takes time. Reuse these objects whenever possible instead of releasing them and recreating them repeatedly. Note, however, that image objects can be reused only if they are the same size and pixel format as needed by the new image. ● Local memory is faster than global memory and private memory is even faster. When using memory on an OpenCL device, the local memory shared by all the work items in a single workgroup is faster than the global memory shared by all the workgroups on the device. Private memory, available only to a single work item, is even faster. ● Experiment with your code to find the kernel size that works best. Using smaller kernels can be efficient because each tiny kernel uses minimal resources and breaking a job down into many small kernels can allow for the creation of very large and efficient workgroups. On the other hand, starting each kernel does take between 10-100 µs. When each kernel exits, the the results must be stored in global memory. Because reading and writing to global memory is expensive, concatenating many small kernels into one large kernel may save considerable overhead. What kernel size is ideal for your application? To figure that out, you will have to experiment with your code to find the kernel size that provides optimal performance. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 83● OpenCL events on the GPU are expensive. You can use eventsto coordinate execution between queues, but there is overhead to doing so. Use events only where needed; otherwise take advantage of the in-order properties of queues. ● When tuning for performance, it's really easy to introduce subtle errors that make the code run faster but produce bad output. After each iteration, always compare the output to a reference output computed on the host. For the same reason, be sure to keep all revisions in case you realize that you need to revert your code. ● Benchmark simple kernelsto estimate upper bounds and set optimization targets. See “Estimating Optimal Performance” (page 87). ● Use OpenCL built-in functions whenever possible. Optimal code will be generated for these functions. ● Balance precision and speed. GPUs are designed for graphics, where the requirements for precision are lower. The fastest variants are exposed in the OpenCL built-ins as fast_, half_, native_ functions. The program build options allow control of some speed optimizations. ● Take advantage of the memory subsystem of the device: ● When writing for the CPU, take advantage of the memory subsystem: reuse data while it’s still in L1 or L2 cache. To achieve this, use loop blocking and access memory in a cache-friendly pattern. ● On the GPU, the memory access pattern is the most important factor. Use faster memory levels (local memory, registers) to counter the effects of a sub-optimal pattern and to minimize accesses to the slower global memory. ● Avoid divergent execution: ● The CPU predicts the result of conditional jump instructions (corresponding to if, for, while, etc.) and starts processing the selected branch before knowing the effective result of the test. If the prediction is wrong, the entire pipeline needs to be flushed, and we lose some cycles. If possible, use conditional assignment instead. ● On the GPU, all threads scheduled together must execute the same code. As a consequence, when executing a conditional, all threads execute both branches, with their output disabled when they are in the wrong branch. It is best to avoid conditionals (replace them with a?x:y operators) or use built-in functions. ● Know what kind of device your code is executing on. OpenCL enables you to determine whether a device is a GPU or a CPU and how many devices are available. You can optimize your code for the hardware on which it is running. The same OpenCL code may run efficiently on both CPU and GPU, but optimal performance will usually require different code for each device. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 84GPUs and CPUs have fundamentally different architectures and so require different optimizations for OpenCL. For example, whereas a CPU has a relatively small number of processing elements and a large amount of memory (both a large cache and a much larger amount of RAM available on the circuit board), a GPU has a relatively large number of processing elements and a comparatively small amount of memory. ● When writing for the CPU: ● Write simple scalar code first. The compiler and the autovectorizer work best on linear code and can generate near-optimal code with no effort required from you. If the autovectorizer providessub-optimal results, add vectors to the code by hand. ● Use the -cl-denorms-are-zero option in clBuildProgram, unless you need to use denormals (denormals are very small numbers with a slightly different floating-point representation). Denormals handling can be extremely slow (100x slower) and can lead to puzzling benchmark results. ● CPUs are not optimized for graphics processing. Avoid using images. CPUs provide no hardware acceleration for images, and image access is slower than the equivalent buffer access. See “Tuning OpenCL Code For the CPU” (page 89) for specific optimization strategies for CPUs. ● When writing for the GPU: ● Keep in mind that each family of GPUs has a unique architecture. To get the best possible performance from a GPU, you need to understand that GPU’s architecture. For example, for a particular GPU it might be more efficient to write to memory in blocks of a certain size, or it might be desirable to have the number of work items in each workgroup a multiple of a particular number. Consult the literature of the manufacturer of any GPU you wish to support to get details about that GPU’s architecture. This document considers only general principles that should be true for any GPU. ● Avoid slow host-device transfers: ● Aggregate several transfers into a single, larger one. ● Design algorithms to keep the data on the device as long as possible. ● Try to maximize the compute/memory ratio and the number of independent dependency chains by grouping the computation of several output elements into one single work item. The GPU has huge computing power and kernels will usually be memory-bound. ● Try to use image objectsinstead of buffers. For certain memory access patterns, the different hardware data path used when accessing images may be more efficient. This is especially the case when you use 16-bit floating-point data (half). See “Tuning OpenCL Code For the GPU” (page 99) for specific optimization strategies for GPUs. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 85Measuring Performance Execution time of OpenCL commands can be measured on the host or on the device. It is best to measure performance on the host, because it is closer to the user-perceived execution time. Measuring Performance On the Host To measure OpenCL command execution time on the host: 1. Call the gettimeofday function to determine the start time. The gettimeofday function provides wall clock time with microsecond granularity: Listing 11-1 Using the gettimeofday function #include // Return wall clock time (s). double getRealTime() { struct timeval tv; gettimeofday(&tv,0); return (double)tv.tv_sec+1.0e-6*(double)tv.tv_usec; } 2. Call clFinish(queue) to block the host thread until all the OpenCL commandsin the queue are executed. 3. When OpenCL processing completes, call the getTimeOfDay function to determine the elapsed time. Measuring Performance On Devices The following APIs allows you to measure time taken for various OpenCL commands and kernels queued in a block to a dispatch queue. ● Start a timer Call this function to start the timer: cl_timer gcl_start_timer(void); ● Stop the timer Call this function to stop the timer and return the elapsed time in seconds between when the call to cl_start_timer associated with the timer parameter and when commands & kernelsin the block have finished execution: Improving Performance Measuring Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 86double gcl_stop_timer(cl_timer timer); Measuring execution time of several consecutive calls to the same kernel(s) usually gives more reliable results. “Warming-up” the device also improves consistency of benchmarking results. Listing 11-2 (page 87) shows an example of benchmarking loop that can be included in kernel code: Listing 11-2 Sample benchmarking loop on the kernel const int iter = 10; // number of iterations to benchmark cl_timer blockTimer; for (int it=-2; it } clFinish(queue); gcl_stop_timer(blockTimer); // t = execution time for one iteration (s) Estimating Optimal Performance Before optimizing code, it is best to know what kind of performance is achievable. The main factor determining the execution speed of an OpenCL kernel is memory usage. This is the case for both CPU and GPU devices. Benchmarking the speed of the kernel function in Listing 11-3 (page 87) provides a way to estimate the memory speed of an OpenCL device. Listing 11-3 Kernel for estimating performance kernel void copyBuffer(global const float * in,global float * out) { int i = get_global_id(0); out[i] = in[i]; // R+W one float } Improving Performance Estimating Optimal Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 87On our test machine we measured the following memory copy speeds for buffer sizes ranging from 1KiB to 16MiB: Figure 11-1 Memory copy speed in GB/s (read+write) vs buffer size 100 1 KiB 4 KiB 16 KiB 64 KiB 256 KiB 1 MiB 4 MiB 16 MiB 75 50 25 0 Standard C library memcpy (running on one single thread) The OpenCL code running on the CPU The OpenCL code running on the GPU Several interesting observations can be made from these curves: ● The measured cost of invoking the OpenCL kernels is in the 10-20 µs range, something like 50,000 CPU clock cycles. For small tasks, it will be larger or comparable to the actual cost of the computation. ● The memcpy curve showsthe 4 different levels of the CPU memory hierarchy: L1 cache (90 GB/s), L2 cache (50 GB/s), L3 cache (30 GB/s), and external memory (12 GB/s). ● The OpenCL GPU curve shows how GPU memory runs much faster than the CPU external memory. We reach 36 GB/s for this mobile GPU, and some desktop GPUs can reach 160 GB/s. Important: OpenCL is more efficient when data size increases. Try to process larger problems in fewer kernel calls. The asymptotic (maximum) value memory speed can be used to estimate the speed of a memory-bound algorithm on large data. Improving Performance Estimating Optimal Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 88Take, for example, the following boxAvg kernel. It takes a single channel floating point image as input, and computes a single channel floating point image where each output pixel (x,y) is the average value of all pixels in a square box centered at (x,y). A w by h image is stored in a buffer float * A, where pixel (x,y) is stored in A[x+w*y]. Here is a first version of the code, before optimization: constant int RANGE = 2; kernel void boxAvg1(int w, int h, global const float * in, global float * out) { int x = get_global_id(0); // pixel to process is (x,y) int y = get_global_id(1); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dy=-RANGE;dy<=RANGE;dy++) for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; int yy = y + dy; // Accumulate if inside image if (xx>=0 && xx=0 && yy=0 && xx=0 && yy=0 && xx= 0) { sumA -= inRow[x-RANGE-1]; sum1 -= 1.0f; } if (x+RANGE < w) { sumA += inRow[x+RANGE]; sum1 += 1.0f; } // insert x+RANGE // Store current value out[x+w*y] = sumA/sum1; Improving Performance Tuning OpenCL Code For the CPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 94} } In this variant, we have reduced the memory accesses from 6 to 3 per iteration of the x loop. The execution speed of this variant is now 1366 Mpix/s (and only 822 Mpix/s without the autovectorizer). This is 91% of our upper bound. We can move the conditionals and the division out of the x loop by splitting it into three parts: Listing 11-7 Modify the horizontal pass by moving division and conditionals out of the inner loop // Horizontal pass v4. Global work size: H kernel void boxAvgH4(int w, int h, global const float * in, global float * out) { int y = get_global_id(0); // row to process is y global const float * inRow = in + y*w; // beginning of input row global float * outRow = out + y*w; // beginning of output row float sumA = 0.0f; float sum1 = 0.0f; // Left border int x = -RANGE; for (; x<=RANGE; x++) { // Here, sumA corresponds to segment 0..x+RANGE-1, update to 0..x+RANGE. sumA += inRow[x+RANGE]; sum1 += 1.0f; if (x >= 0) outRow[x] = sumA/sum1; } // x is RANGE+1 here // Internal pixels float k = 1.0f/(float)(2*RANGE+1); // constant weight for internal pixels for (; x+RANGE= number of CPU cores. kernel void boxAvgV3(int w,int h,global const float * in,global float * out) { // Numer of rows to process in each work item (rounded up) int rowsPerItem = (h+get_global_size(0)-1)/get_global_size(0); int y0 = rowsPerItem * get_global_id(0); // we update the range Y0..Y1-1 int y1 = min(h, y0 + rowsPerItem); for (int y=y0; y= number of CPU cores. // AUX[w*global_size(0)] is temporary storage, 1 row for each work item. kernel void boxAvg2(int w, int h, global const float * in, global float * out, global float * aux) { // Number of rows to process in each work item (rounded up) int rowsPerItem = (h+get_global_size(0)-1)/get_global_size(0); int y0 = rowsPerItem * get_global_id(0); // we update the range Y0..Y1-1 int y1 = y0 + rowsPerItem; aux += get_global_id(0) * w; // point to our work item’s row of temporary storage float k = 1.0f/(float)(2*RANGE+1); // constant weight for internal pixels // Process our rows. We need to process extra RANGE rows before and after. for (int y=y0-RANGE; y=h) continue; // out of range // Compute horizontal pass in AUX. // The boxAvg4 code goes here on input row y // The output is stored in AUX[W]. // Accumulate this row on output rows Y-RANGE..Y+RANGE for (int dy=-RANGE; dy<=RANGE; dy++) { int yy = y + dy; if (yy < max(0, y0) || yy >= min(h, y1)) continue; // out of range // Get number of rows accumulated in row YY, to get the weight int nr = 1 + min(h-1, yy+RANGE)-max(0, yy-RANGE); float u = 1.0f/(float)nr; // Accumulate AUX in row YY global float4 * outRow4 = (global float4 *)(out + w*yy); global float4 * aux4 = (global float4 *)(aux); for (int x=0; x<(w/4); x++) outRow4[x] += u * aux4[x]; } } } Thisfused version runs at 1166 Mpix/s. Some rows will be processed twice,since we have to compute horizontal filters on rows y0-RANGE to y1+RANGE-1 to update output rows y0 to y1-1. At any given time during the execution, we will access one row in aux, one input row, and 2*RANGE+1 output rows. For a 4096x4096 image, each row is 16 KiB, and all 7 rows fit in L2 cache. Important: Merging two kernels called one after the other can reduce memory accesses, and works on smaller data chunks fitting in faster cache levels, instead of of forcing the two kernels to resort to communicate via via full round trips to external memory. Tuning OpenCL Code For the GPU The conditions to efficiently use a modern GPU are similar to the conditions we listed for the CPU, but with a few notable differences. Efficient GPU optimization requires: ● Scheduling a large number of work items to use all resources and hide execution latency. ● Using the GPU memory hierarchy efficiently. Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 99The number of workgroups and work items required to efficiently utilize a GPU is much higher than for a CPU. Inside the GPU we have a few cores (typically 2 to 16). Each core schedules work items in small groups (64 work items in the test machine). All these items are executed at the same time and can issue up to five independent arithmetic ops. Instruction latency is much higher for the GPU. When all work items managed by the core are waiting for the result of a previously issued instruction still in the pipeline, the GPU core stalls, and we lose efficiency. One way to avoid this is to increase the number of work items; another solution is to have more independent dependency chains inside each work item. The GPU memory hierarchy can be seen as four levels with the following orders of magnitude for access bandwidth: ● Host memory accessed from the GPU through the PCI-Express bus, 10 GB/s ● OpenCL global memory, VRAM attached to the GPU, 100 GB/s ● OpenCL local memory, attached to each core, 1,000 GB/s ● OpenCL private memory, registers, 10,000 GB/s Memory management is explicit: the host code manages host-device transfers and each variable belongs to a unique address space (global, local, private, constant). The most important factor in OpenCL efficiency is the memory access pattern: at a given time, we may have hundreds of work items issuing a memory access instruction, each one with a different address. The hardware is optimized to processsome of these patterns very quickly. Other access patterns can lead to hardware conflicts. Hardware conflicts are resolved by serializing the accesses: they can’t occur in parallel,so the hardware schedules them one after the other. A bad access pattern can make code run up to 30x slower. A pattern where work item i accesses element x[i] of an array is fast. On the contrary, any pattern with a large stride (especially a power of 2), x[s*i], will be extremely slow when s becomes large enough. With such a large difference of bandwidth between the different layers, keeping reused data in the fastest levels is another key to efficiency. In particular, it is best to avoid host-device transfers: keep data resident on the GPU until it needs to be transferred to the host. If the output of OpenCL needs to be displayed, it is best to use CL/GL interoperability and have the output image mapped to an OpenGL texture. In Practice We will tune the same boxAvg code we used in “Tuning OpenCL Code For the CPU” (page 89), but this time for the GPU. We start from the same initial code for the horizontal pass as we did for the CPU: Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 100Listing 11-12 Kernel before optimization // Horizontal pass v1. Global work size: w x h kernel void boxAvgH1(int w,int h,global const float * in,global float * out) { int x = get_global_id(0); // pixel to process is (x,y) int y = get_global_id(1); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; // Accumulate if inside image if (xx>=0 && xx= 0 && xx < w)?in[xx+w*y]:0.0f; } // Block until all work items in the group finished updating AUX barrier(CLK_LOCAL_MEM_FENCE); // Compute our value float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 102sumA += aux[iid+dx+RANGE]; // will add 0 if out or range sum1 += (xx >= 0 && xx < w)?1.0f:0.0f; } // Store output out[x+w*y] = sumA/sum1; } In this example we are using all the work items in the workgroup to copy a segment of the input row to the local memory buffer aux. Note that a barrier call is required to ensure all items in the group have actually finished updating aux before we use the buffer. This kernel runs slightly faster, at 1043 Mpix/s. It can be modified to process several consecutive rows inside each work item, or several consecutive columns. The corresponding benchmarks are: Table 11-1 Benchmarks of boxAvgH5 variants: pix/item Mpix/s 1x1 1044 1x2 1630 1x4 1577 2x1 1300 4x1 1356 8x1 1123 Performance here is significantly improved, but is still far from the copy kernel reference speed of 4500 Mpix/s. Let’s direct our attention to the vertical pass. If it proves to be much faster, we may be able to use it twice with additional transpositions, assuming we can transpose an image efficiently. The boxAvgV1 kernel presented in the CPU section runs at 884 Mpix/s. Let’s modify this kernel to compute several rows in each work item: Listing 11-14 Modify the kernel to compute several rows in each work item // Vertical pass v4. Global work size: W x any Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 103kernel void boxAvgV4(int w, int h, global const float * in, global float * out) { // Number of rows to compute int rowsPerItem = (h+get_global_size(1)-1) / get_global_size(1); int x = get_global_id(0); // column to process int y0 = rowsPerItem * get_global_id(1); // rows to process are y0..y1-1 int y1 = min(h,y0+rowsPerItem); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels // Load values y0-RANGE-1..y0+RANGE-1 for (int y=max(0, y0-RANGE-1); y < min(h, y0+RANGE); y++) { sumA += in[x+w*y]; sum1 += 1.0f; } // Process our rows for (int y=y0; y= 0) { sumA -= in[x + w*yy]; sum1 -= 1.0f; } yy = y+RANGE; if (yy < h) { sumA += in[x + w*yy]; sum1 += 1.0f; } // Store value out[x+w*y] = sumA/sum1; } } This one runs at 2296 Mpix/s, and we read+write 2+1 float per pixel instead of 5+1. If we can provide a dedicated kernel for each value of RANGE, we can reduce this to 1+1 float per pixel, by keeping a “ring” of previous 2*RANGE+1 values in registers. Doing so, we won’t need to reload the value for yy = y-RANGE-1 to remove it from the sum. Here is the modified code: Listing 11-15 Provide a dedicated kernel for each value of RANGE // Register ring, RANGE=2 kernel void boxAvgV4_ring(int w,int h,global const float * in,global float * out) Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 104{ // Compute number of rows to compute int rowsPerItem = (h+get_global_size(1)-1)/get_global_size(1); int x = get_global_id(0); // column to process int y0 = rowsPerItem * get_global_id(1); // rows to process are y0..y1-1 int y1 = min(h, y0+rowsPerItem); float2 r0, r1, r2, r3, r4; // ring has 5 values // Load values y0-RANGE-1..y0+RANGE-1 in the ring int yy; r0 = r1 = r2 = r3 = r4 = (float2)(0.0f); yy = y0-2; if (yy>=0) r1 = (float2)(in[x + w*yy],1.0f); yy = y0-1; if (yy>=0) r2 = (float2)(in[x + w*yy],1.0f); yy = y0; r3 = (float2)(in[x + w*yy],1.0f); yy = y0+1; if (yy=0) { r1 = in[x + w*yy]; s1 = 1.0f; } yy = y0-1; if (yy>=0) { r2 = in[x + w*yy]; s2 = 1.0f; } Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 106yy = y0; { r3 = in[x + w*yy]; s3 = 1.0f; } yy = y0+1; if (yy