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

136 lines
3.7 KiB
Markdown
Raw Normal View History

# iOS tutorial 1: Link against GStreamer
2016-05-16 14:30:34 +00:00
2016-06-17 19:32:33 +00:00
## Goal
![screenshot]
2016-05-16 14:30:34 +00:00
The first iOS tutorial is simple. The objective is to get the GStreamer
version and display it on screen. It exemplifies how to link against the
GStreamer library from Xcode using objective-C.
2016-06-17 19:32:33 +00:00
## Hello GStreamer!
2016-05-16 14:30:34 +00:00
The tutorials code are in the
[gst-docs](https://cgit.freedesktop.org/gstreamer/gst-docs/) in the
`tutorials/xcode iOS` folder.
It was created using the GStreamer Single View
2016-06-17 19:32:33 +00:00
Application template. The view contains only a `UILabel` that will be
used to display the GStreamer's version to the user.
2016-05-16 14:30:34 +00:00
2016-06-17 19:32:33 +00:00
## The User Interface
2016-05-16 14:30:34 +00:00
2016-06-17 19:32:33 +00:00
The UI uses storyboards and contains a single `View` with a centered
`UILabel`. The `ViewController` for the `View` links its
`label` variable to this `UILabel` as an `IBOutlet`.
2016-05-16 14:30:34 +00:00
**ViewController.h**
2016-05-27 02:48:36 +00:00
```
2016-05-16 14:30:34 +00:00
#import <UIKit/UIKit.h>
2016-05-16 14:30:34 +00:00
@interface ViewController : UIViewController {
IBOutlet UILabel *label;
}
@property (retain,nonatomic) UILabel *label;
@end
```
2016-06-17 19:32:33 +00:00
## The GStreamer backend
2016-05-16 14:30:34 +00:00
All GStreamer-handling code is kept in a single Objective-C class called
`GStreamerBackend`. In successive tutorials it will get expanded, but,
for now, it only contains a method to retrieve the GStreamer version.
2016-06-17 19:32:33 +00:00
The `GStreamerBackend` is made in Objective-C so it can take care of the
2016-05-16 14:30:34 +00:00
few C-to-Objective-C conversions that might be necessary (like `char
2016-06-17 19:32:33 +00:00
*` to `NSString *`, for example). This eases the usage of this class by
2016-05-16 14:30:34 +00:00
the UI code, which is typically made in pure Objective-C.
2016-06-17 19:32:33 +00:00
`GStreamerBackend` serves exactly the same purpose as the JNI code in
the [](tutorials/android/index.md).
2016-05-16 14:30:34 +00:00
**GStreamerBackend.m**
2016-05-27 02:48:36 +00:00
```
2016-05-16 14:30:34 +00:00
#import "GStreamerBackend.h"
#include <gst/gst.h>
@implementation GStreamerBackend
-(NSString*) getGStreamerVersion
{
char *version_utf8 = gst_version_string();
NSString *version_string = [NSString stringWithUTF8String:version_utf8];
g_free(version_utf8);
return version_string;
}
@end
```
2016-06-17 19:32:33 +00:00
The `getGStreamerVersion()` method simply calls
`gst_version_string()` to obtain a string describing this version of
GStreamer. This [Modified
UTF8](http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8) string is then
converted to a `NSString *` by ` NSString:stringWithUTF8String `and
2016-05-16 14:30:34 +00:00
returned. Objective-C will take care of freeing the memory used by the
2016-06-17 19:32:33 +00:00
new `NSString *`, but we need to free the `char *` returned
by `gst_version_string()`.
2016-05-16 14:30:34 +00:00
2016-06-17 19:32:33 +00:00
## The View Controller
2016-05-16 14:30:34 +00:00
The view controller instantiates the GStremerBackend and asks it for the
2016-06-17 19:32:33 +00:00
GStreamer version to display at the label. That's it!
2016-05-16 14:30:34 +00:00
**ViewController.m**
2016-05-27 02:48:36 +00:00
```
2016-05-16 14:30:34 +00:00
#import "ViewController.h"
#import "GStreamerBackend.h"
@interface ViewController () {
GStreamerBackend *gst_backend;
}
@end
@implementation ViewController
@synthesize label;
- (void)viewDidLoad
{
[super viewDidLoad];
// Do any additional setup after loading the view, typically from a nib.
gst_backend = [[GStreamerBackend alloc] init];
2016-05-16 14:30:34 +00:00
label.text = [NSString stringWithFormat:@"Welcome to %@!", [gst_backend getGStreamerVersion]];
}
- (void)didReceiveMemoryWarning
{
[super didReceiveMemoryWarning];
// Dispose of any resources that can be recreated.
}
@end
```
2016-06-17 19:32:33 +00:00
## Conclusion
2016-05-16 14:30:34 +00:00
This ends the first iOS tutorial. It has shown that, due to the
2016-06-17 19:32:33 +00:00
compatibility of C and Objective-C, adding GStreamer support to an iOS
2016-05-16 14:30:34 +00:00
app is as easy as it is on a Desktop application. An extra Objective-C
2016-06-17 19:32:33 +00:00
wrapper has been added (the `GStreamerBackend` class) for clarity, but
2016-05-16 14:30:34 +00:00
calls to the GStreamer framework are valid from any part of the
application code.
The following tutorials detail the few places in which care has to be
taken when developing specifically for the iOS platform.
2016-06-17 19:32:33 +00:00
It has been a pleasure having you here, and see you soon!
2016-05-16 14:30:34 +00:00
[screenshot]: images/tutorials/ios-link-against-gstreamer-screenshot.png