8.6 KiB
Android tutorial 1: Link against GStreamer
Goal!
This first Android tutorial is extremely simple: it just retrieves the GStreamer version and displays it on the screen. It exemplifies how to access GStreamer C code from Java and verifies that there have been no linkage problems.
Hello GStreamer [Java code]
The tutorial code is in the gst-docs subdirectory.
This directory contains the usual Android NDK structure: a src
folder for the Java code,
a jni
folder for the C code and a res
folder for UI resources.
We recommend that you open this project in Eclipse (as explained in ) so you can easily see how all the pieces fit together.
Let’s first introduce the Java code, then the C code and finally the makefile that allows GStreamer integration.
src/org/freedesktop/gstreamer/tutorials/tutorial_1/Tutorial1.java
package org.freedesktop.gstreamer.tutorials.tutorial_1;
import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;
import android.widget.Toast;
import org.freedesktop.gstreamer.GStreamer;
public class Tutorial1 extends Activity {
private native String nativeGetGStreamerInfo();
// Called when the activity is first created.
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
try {
GStreamer.init(this);
} catch (Exception e) {
Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
finish();
return;
}
setContentView(R.layout.main);
TextView tv = (TextView)findViewById(R.id.textview_info);
tv.setText("Welcome to " + nativeGetGStreamerInfo() + " !");
}
static {
System.loadLibrary("gstreamer_android");
System.loadLibrary("tutorial-1");
}
}
Calls from Java to C happen through native methods, like the one declared here:
private native String nativeGetGStreamerInfo();
This tells Java that there exists a method with this signature somewhere so it compiles happily. It is your responsibility to ensure that, at runtime, this method is accessible. This is accomplished by the C code shown later.
The first bit of code that gets actually executed is the static initializer of the class:
static {
System.loadLibrary("gstreamer_android");
System.loadLibrary("tutorial-1");
}
It loads libgstreamer_android.so
, which contains all GStreamer
methods, and libtutorial-1.so
, which contains the C part of this
tutorial, explained below.
Upon loading, each of these libraries’ JNI_OnLoad()
method is
executed. It basically registers the native methods that these libraries
expose. The GStreamer library only exposes a init()
method, which
initializes GStreamer and registers all plugins (The tutorial library is
explained later below).
try {
GStreamer.init(this);
} catch (Exception e) {
Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
finish();
return;
}
Next, in the OnCreate()
method of the
Activity
we actually initialize GStreamer by calling GStreamer.init()
. This
method requires a
Context
so it cannot be called from the static initializer, but there is no
danger in calling it multiple times, as all but the first time the calls
will be ignored.
Should initialization fail, the init()
method would throw an
Exception
with the details provided by the GStreamer library.
TextView tv = (TextView)findViewById(R.id.textview_info);
tv.setText("Welcome to " + nativeGetGStreamerInfo() + " !");
Then, the native method nativeGetGStreamerInfo()
is called and a
string is retrieved, which is used to format the content of the
TextView
in the UI.
This finishes the UI part of this tutorial. Let’s take a look at the C code:
Hello GStreamer [C code]
jni/tutorial-1.c
#include <string.h>
#include <jni.h>
#include <android/log.h>
#include <gst/gst.h>
/*
* Java Bindings
*/
static jstring gst_native_get_gstreamer_info (JNIEnv* env, jobject thiz) {
char *version_utf8 = gst_version_string();
jstring *version_jstring = (*env)->NewStringUTF(env, version_utf8);
g_free (version_utf8);
return version_jstring;
}
static JNINativeMethod native_methods[] = {
{ "nativeGetGStreamerInfo", "()Ljava/lang/String;", (void *) gst_native_get_gstreamer_info}
};
jint JNI_OnLoad(JavaVM *vm, void *reserved) {
JNIEnv *env = NULL;
if ((*vm)->GetEnv(vm, (void**) &env, JNI_VERSION_1_4) != JNI_OK) {
__android_log_print (ANDROID_LOG_ERROR, "tutorial-1", "Could not retrieve JNIEnv");
return 0;
}
jclass klass = (*env)->FindClass (env, "org/freedesktop/gstreamer/tutorials/tutorial_1/Tutorial1");
(*env)->RegisterNatives (env, klass, native_methods, G_N_ELEMENTS(native_methods));
return JNI_VERSION_1_4;
}
The JNI_OnLoad()
method is executed every time the Java Virtual
Machine (VM) loads a library.
Here, we retrieve the JNI environment needed to make calls that interact with Java:
JNIEnv *env = NULL;
if ((*vm)->GetEnv(vm, (void**) &env, JNI_VERSION_1_4) != JNI_OK) {
__android_log_print (ANDROID_LOG_ERROR, "tutorial-1", "Could not retrieve JNIEnv");
return 0;
}
And then locate the class containing the UI part of this tutorial using
FindClass()
:
jclass klass = (*env)->FindClass (env, "org/freedesktop/gstreamer/tutorials/tutorial_1/Tutorial1");
Finally, we register our native methods with RegisterNatives()
, this
is, we provide the code for the methods we advertised in Java using the
native
keyword:
(*env)->RegisterNatives (env, klass, native_methods, G_N_ELEMENTS(native_methods));
The native_methods
array describes each one of the methods to register
(only one in this tutorial). For each method, it provides its Java
name, its type
signature
and a pointer to the C function implementing it:
static JNINativeMethod native_methods[] = {
{ "nativeGetGStreamerInfo", "()Ljava/lang/String;", (void *) gst_native_get_gstreamer_info}
};
The only native method used in this tutorial
is nativeGetGStreamerInfo()
:
jstring gst_native_get_gstreamer_info (JNIEnv* env, jobject thiz) {
char *version_utf8 = gst_version_string();
jstring *version_jstring = (*env)->NewStringUTF(env, version_utf8);
g_free (version_utf8);
return version_jstring;
}
It simply calls gst_version_string()
to obtain a string describing
this version of GStreamer. This Modified
UTF8 string is then
converted to UTF16 by NewStringUTF()
as required by Java and returned. Java will be
responsible for freeing the memory used by the new UTF16 String, but we
must free the char *
returned by gst_version_string()
.
Hello GStreamer [Android.mk]
jni/Android.mk
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := tutorial-1
LOCAL_SRC_FILES := tutorial-1.c
LOCAL_SHARED_LIBRARIES := gstreamer_android
LOCAL_LDLIBS := -llog
include $(BUILD_SHARED_LIBRARY)
ifndef GSTREAMER_ROOT
ifndef GSTREAMER_ROOT_ANDROID
$(error GSTREAMER_ROOT_ANDROID is not defined!)
endif
GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
endif
GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
GSTREAMER_PLUGINS := coreelements
include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer-1.0.mk
This is a barebones makefile for a project with GStreamer support. It
simply states that it depends on the libgstreamer_android.so
library
(line 7), and requires the coreelements
plugin (line 18). More complex
applications will probably add more libraries and plugins
to Android.mk
Conclusion
This ends the first Android tutorial. It has shown that, besides the interconnection between Java and C (which abides to the standard JNI procedure), adding GStreamer support to an Android application is not any more complicated than adding it to a desktop application.
The following tutorials detail the few places in which care has to be taken when developing specifically for the Android platform.
As usual, it has been a pleasure having you here, and see you soon!