markdown/tutorials/ios/link-against-gstreamer.md

   1 # iOS tutorial 1: Link against GStreamer
   2
   3 ## Goal
   4
   5 ![screenshot]
   6
   7 The first iOS tutorial is simple. The objective is to get the GStreamer
   8 version and display it on screen. It exemplifies how to link against the
   9 GStreamer library from Xcode using objective-C.
  10
  11 ## Hello GStreamer!
  12
  13 The tutorials code are in the
  14 [gst-docs](https://cgit.freedesktop.org/gstreamer/gst-docs/) in the
  15 `tutorials/xcode iOS` folder.
  16
  17 It was created using the GStreamer Single View
  18 Application template. The view contains only a `UILabel` that will be
  19 used to display the GStreamer's version to the user.
  20
  21 ## The User Interface
  22
  23 The UI uses storyboards and contains a single `View` with a centered
  24 `UILabel`. The `ViewController` for the `View` links its
  25 `label` variable to this `UILabel` as an `IBOutlet`.
  26
  27 **ViewController.h**
  28
  29 ```
  30 #import <UIKit/UIKit.h>
  31
  32 @interface ViewController : UIViewController {
  33     IBOutlet UILabel *label;
  34 }
  35
  36 @property (retain,nonatomic) UILabel *label;
  37
  38 @end
  39 ```
  40
  41 ## The GStreamer backend
  42
  43 All GStreamer-handling code is kept in a single Objective-C class called
  44 `GStreamerBackend`. In successive tutorials it will get expanded, but,
  45 for now, it only contains a method to retrieve the GStreamer version.
  46
  47 The `GStreamerBackend` is made in Objective-C so it can take care of the
  48 few C-to-Objective-C conversions that might be necessary (like `char
  49 *` to `NSString *`, for example). This eases the usage of this class by
  50 the UI code, which is typically made in pure Objective-C.
  51 `GStreamerBackend` serves exactly the same purpose as the JNI code in
  52 the [](tutorials/android/index.md).
  53
  54 **GStreamerBackend.m**
  55
  56 ```
  57 #import "GStreamerBackend.h"
  58
  59 #include <gst/gst.h>
  60
  61 @implementation GStreamerBackend
  62
  63 -(NSString*) getGStreamerVersion
  64 {
  65     char *version_utf8 = gst_version_string();
  66     NSString *version_string = [NSString stringWithUTF8String:version_utf8];
  67     g_free(version_utf8);
  68     return version_string;
  69 }
  70
  71 @end
  72 ```
  73
  74 The `getGStreamerVersion()` method simply calls
  75 `gst_version_string()` to obtain a string describing this version of
  76 GStreamer. This [Modified
  77 UTF8](http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8) string is then
  78 converted to a `NSString *` by ` NSString:stringWithUTF8String `and
  79 returned. Objective-C will take care of freeing the memory used by the
  80 new `NSString *`, but we need to free the `char *` returned
  81 by `gst_version_string()`.
  82
  83 ## The View Controller
  84
  85 The view controller instantiates the GStremerBackend and asks it for the
  86 GStreamer version to display at the label. That's it!
  87
  88 **ViewController.m**
  89
  90 ```
  91 #import "ViewController.h"
  92 #import "GStreamerBackend.h"
  93
  94 @interface ViewController () {
  95     GStreamerBackend *gst_backend;
  96 }
  97
  98 @end
  99
 100 @implementation ViewController
 101
 102 @synthesize label;
 103
 104 - (void)viewDidLoad
 105 {
 106     [super viewDidLoad];
 107     // Do any additional setup after loading the view, typically from a nib.
 108     gst_backend = [[GStreamerBackend alloc] init];
 109
 110     label.text = [NSString stringWithFormat:@"Welcome to %@!", [gst_backend getGStreamerVersion]];
 111 }
 112
 113 - (void)didReceiveMemoryWarning
 114 {
 115     [super didReceiveMemoryWarning];
 116     // Dispose of any resources that can be recreated.
 117 }
 118
 119 @end
 120 ```
 121
 122 ## Conclusion
 123
 124 This ends the first iOS tutorial. It has shown that, due to the
 125 compatibility of C and Objective-C, adding GStreamer support to an iOS
 126 app is as easy as it is on a Desktop application. An extra Objective-C
 127 wrapper has been added (the `GStreamerBackend` class) for clarity, but
 128 calls to the GStreamer framework are valid from any part of the
 129 application code.
 130
 131 The following tutorials detail the few places in which care has to be
 132 taken when developing specifically for the iOS platform.
 133
 134 It has been a pleasure having you here, and see you soon!
 135
 136   [screenshot]: images/tutorials/ios-link-against-gstreamer-screenshot.png