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