317 lines
6.7 KiB
Groff
317 lines
6.7 KiB
Groff
.\"
|
|
.\" SMPEG - SDL MPEG Player Library
|
|
.\" Copyright (C) 1999 Loki Entertainment Software
|
|
.\"
|
|
.\" This library is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU Library General Public
|
|
.\" License as published by the Free Software Foundation; either
|
|
.\" version 2 of the License, or (at your option) any later version.
|
|
.\"
|
|
.\" This library is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
.\" Library General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU Library General Public
|
|
.\" License along with this library; if not, write to the Free
|
|
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
.\"
|
|
.Dd December 23, 2002
|
|
.Dt SMPEG 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm smpeg
|
|
.Nd MPEG-1 audio/video playback library
|
|
.Sh SYNOPSIS
|
|
.Bd -literal
|
|
#include <smpeg.h>
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library provides audio/video playback of MPEG-1 data.
|
|
.Sh INITIALIZATION
|
|
.nr nS 1
|
|
.Ft "SMPEG *"
|
|
.Fn SMPEG_new "const char *file" "SMPEG_Info *info" "int sdl_audio"
|
|
.Pp
|
|
.Ft "SMPEG *"
|
|
.Fn SMPEG_new_descr "int fd" "SMPEG_Info *info" "int sdl_audio"
|
|
.Pp
|
|
.Ft "SMPEG *"
|
|
.Fn SMPEG_new_data "void *data" "SMPEG_Info *info" "int sdl_audio"
|
|
.Pp
|
|
.Ft "void"
|
|
.Fn SMPEG_getinfo "SMPEG *mpeg" "SMPEG_Info *info"
|
|
.Pp
|
|
.Ft "void"
|
|
.Fn SMPEG_enableaudio "SMPEG *mpeg" "int enable"
|
|
.Pp
|
|
.Ft "void"
|
|
.Fn SMPEG_enablevideo "SMPEG *mpeg" "int enable"
|
|
.Pp
|
|
.Ft "void"
|
|
.Fn SMPEG_delete "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft "char *"
|
|
.Fn SMPEG_error "SMPEG *mpeg"
|
|
.nr nS 0
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_new ,
|
|
.Fn SMPEG_new_descr ,
|
|
.Fn SMPEG_new_data
|
|
and
|
|
.Fn SMPEG_new_rwops
|
|
functions read MPEG data from a file, a file descriptor, memory or a
|
|
.Ft SDL_Rwops
|
|
structure, respectively.
|
|
A newly allocated
|
|
.Ft SMPEG
|
|
object is returned.
|
|
If
|
|
.Fa sdl_audio
|
|
is non-zero, the SDL audio subsystem is used to play audio.
|
|
If
|
|
.Fa info
|
|
is not NULL, it is filled with the following information:
|
|
.Bd -literal
|
|
typedef struct _SMPEG_Info {
|
|
int has_audio, has_video; /* Available data */
|
|
int width, height; /* Video geometry */
|
|
int current_frame; /* Video frame# */
|
|
double current_fps; /* Frames/second */
|
|
char audio_string[80];
|
|
int audio_current_frame; /* Audio playback status */
|
|
Uint32 current_offset; /* Position in video */
|
|
Uint32 total_size; /* Video size */
|
|
double current_time;
|
|
double total_time;
|
|
} SMPEG_Info;
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_getinfo
|
|
function returns information about
|
|
.Fa mpeg
|
|
in
|
|
.Fa info .
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_enableaudio
|
|
and
|
|
.Fn SMPEG_enablevideo
|
|
functions toggle audio and video playback respectively.
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_delete
|
|
function frees resources allocated by
|
|
.Fa mpeg .
|
|
The
|
|
.Fn SMPEG_error
|
|
function returns an error string if a fatal error occured, NULL otherwise.
|
|
.Sh PLAYBACK
|
|
.nr nS 1
|
|
.Ft SMPEGstatus
|
|
.Fn SMPEG_status "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_setvolume "SMPEG *mpeg" "int volume"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_setdisplay "SMPEG *mpeg" "SDL_Surface *dst" "SDL_mutex *surfLock" \
|
|
"SMPEG_DisplayCallback callback"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_loop "SMPEG *mpeg" "int repeat"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_scaleXY "SMPEG *mpeg" "int width" "int height"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_scale "SMPEG *mpeg" "int scale"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_move "SMPEG *mpeg" "int x" "int y"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_setdisplayregion "SMPEG *mpeg" "int x" "int y" "int w" "int h"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_play "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_pause "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_stop "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_rewind "SMPEG *mpeg"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_seek "SMPEG *mpeg" "int nbytes"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_skip "SMPEG *mpeg" "float seconds"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_renderFrame "SMPEG *mpeg" "int framenum"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_renderFinal "SMPEG *mpeg" "SDL_Surface *dst" "int x" "int y"
|
|
.nr nS 0
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_status
|
|
function returns playback status:
|
|
.Bd -literal
|
|
typedef enum {
|
|
SMPEG_ERROR = -1,
|
|
SMPEG_STOPPED,
|
|
SMPEG_PLAYING
|
|
} SMPEGstatus;
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_setvolume
|
|
function sets the audio volume of
|
|
.Fa mpeg ,
|
|
in the in the range 0-100.
|
|
The
|
|
.Fn SMPEG_setdisplay
|
|
function sets the destination surface for MPEG video playback to
|
|
.Fa dst .
|
|
The
|
|
.Fa surfLock
|
|
mutex, if not NULL, will be used to serialize access to
|
|
.Fa dst .
|
|
The
|
|
.Fa callback
|
|
function is called when an area of
|
|
.Fa dst
|
|
needs to be updated,
|
|
its prototype matches
|
|
.Xr SDL_UpdateRect 3 .
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_loop
|
|
function causes the video to loop.
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_scaleXY
|
|
and
|
|
.Fn SMPEG_scale
|
|
functions scale the pixel display to
|
|
.Fa width
|
|
by
|
|
.Fa height
|
|
pixels or
|
|
.Fa scale
|
|
% respectively.
|
|
The
|
|
.Fn SMPEG_move
|
|
function moves the video display area within
|
|
.Fa dst .
|
|
The
|
|
.Fn SMPEG_setdisplayregion
|
|
function selects the region of the video to be shown.
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_play
|
|
function plays
|
|
.Fa mpeg .
|
|
.Fn SMPEG_pause
|
|
pauses the playback.
|
|
.Fn SMPEG_stop
|
|
stops the playback.
|
|
.Fn SMPEG_rewind
|
|
rewinds the play position to the beginning of the MPEG data.
|
|
.Fn SMPEG_seek
|
|
seeks
|
|
.Fa bytes
|
|
in the MPEG stream.
|
|
The
|
|
.Fn SMPEG_skip
|
|
function skips
|
|
.Fa seconds
|
|
in the MPEG stream.
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_renderFrame
|
|
renders the frame
|
|
.Fa framenum ,
|
|
at the current video position, which may be set using
|
|
.Fn SMPEG_setdisplay
|
|
and
|
|
.Fn SMPEG_move .
|
|
The
|
|
.Fn SMPEG_renderFinal
|
|
function renders the last frame of the MPEG video at coordinates
|
|
.Fa x
|
|
and
|
|
.Fa y
|
|
of
|
|
.Fa dst
|
|
surface.
|
|
.Sh VIDEO FILTERING
|
|
.nr nS 1
|
|
.Ft "SMPEG_Filter *"
|
|
.Fn SMPEG_Filter "SMPEG *mpeg" "SMPEG_Filter *filter"
|
|
.nr nS 0
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_Filter
|
|
function selects a video filter.
|
|
.Sh AUDIO PLAYBACK
|
|
.nr nS 1
|
|
.Ft int
|
|
.Fn SMPEG_playAudio "SMPEG *mpeg" "Uint8 *stream" "int len"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_playAudioSDL "void *mpeg" "Uint8 *stream" "int len"
|
|
.Pp
|
|
.Ft int
|
|
.Fn SMPEG_wantedSpec "SMPEG *mpeg" "SDL_AudioSpec *wanted"
|
|
.Pp
|
|
.Ft void
|
|
.Fn SMPEG_actualSpec "SMPEG *mpeg" "SDL_AudioSpec *spec"
|
|
.nr nS 0
|
|
.Pp
|
|
.Fn SMPEG_playAudio
|
|
is the exported callback function for audio playback.
|
|
.Fa stream
|
|
is the buffer, and
|
|
.Fa len
|
|
is the amount of data to fill.
|
|
The function should return the amount of bytes that were actually written,
|
|
this will be the amount requested unless the MPEG audio playback is done.
|
|
.Fn SMPEG_playAudioSDL
|
|
is a wrapper for
|
|
.Fn SMPEG_playAudio
|
|
that can be passed to SDL and SDL_mixer.
|
|
.Pp
|
|
The
|
|
.Fn SMPEG_wantedSpec
|
|
function returns the best audio spec in
|
|
.Fa wanted
|
|
for the MPEG audio stream.
|
|
.Fn SMPEG_actualSpec
|
|
informs
|
|
.Nm
|
|
of the actual SDL audio spec used for sound playback.
|
|
.Sh SEE ALSO
|
|
.Xr plaympeg 1 ,
|
|
.Xr SDL_Init 3 ,
|
|
.Xr SDL_Init_SubSystem 3
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
library was Loki Software's first Open Source project.
|
|
It is based on UC Berkeley's mpeg_play MPEG decoder, and SPLAY, a MPEG audio
|
|
decoder created by Woo-jae Jung.
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
library was written by Karl Robillard and Sam Lantinga, Loki Software Inc.
|
|
Streaming MPEG support was contributed by Vivien Chappelier.
|