| Previous | Contents | Index |
This chapter presents the general Multimedia Services for OpenVMS services for performing the following functions:
The following sections describe these services.
2.1 Allocating Memory
This section presents the memory allocation services available to
applications.
2.1.1 Memory Allocation Overview
Applications must use the memory allocation functions to allocate memory passed to the Multimedia Services for OpenVMS functions and to free memory allocated with the memory allocation functions. When passing pointers to the Multimedia Services for OpenVMS API functions, the memory pointed to must be allocated using the mmeAllocMem , the mmeAllocBuffer , or the mmeAllocBufferAndGetShminfo function. The mmeAllocMem function allocates data structures; the mmeAllocBuffer or the mmeAllocBufferAndGetShminfo function allocates data buffers. Both the mmeAllocBuffer and mmeAllocBufferAndGetShminfo functions ensure that memory is aligned on system page boundaries, a requirement for data buffers.
The only pointers that do not need to be allocated are those passed to the file I/O functions described in Chapter 6. However, if a pointer that is passed to a file I/O function will also be passed to one of the other API functions, then it must be allocated using the memory allocation functions. For example, if an application reads a buffer of data from an AVI file with the mmioRead function and then decompresses the data with the ICDecompress function, the data buffer must be allocated with the mmeAllocBuffer function.
Currently, all pointers passed between a client application and the mmeserver are passed as shared memory pointers. Most systems are configured with a relatively small set of shared memory segments. There are techniques you can use to reduce the number of shared memory segments used.
To reduce the number of shared memory segments, do one of the following:
void * buffer; BITMAPINFO *lpbiIn, *lpbiOut; buffer = mmeAllocMem(sizeof(BITMAPINFOHEADER) * 2); if ( !buffer ) return ERROR; lpbiIn = (BITMAPINFOHEADER *)buffer; lpbiOut = (BITMAPINFOHEADER *)((unsigned long)buffer + sizeof(BITMAPINFOHEADER)) |
void * buffer;
int size;
void * videoIn;
void * videoOut;
void * audioPlay;
size = PAGE_PAD(audioPlayDataSize ) +
PAGE_PAD(videoInDataSize) + PAGE_PAD(videoOutDataSize);
buffer = mmeAllocBuffer(size);
if ( !buffer ) return ERROR;
audioPlay = buffer;
videoIn = (void *)((unsigned long)buffer + PAGE_PAD(audioPlayDataSize));
videoOut = (void *)((unsigned long)videoIn + PAGE_PAD(videoInPlayDataSize));
|
#define PAGE_PAD(size) ((size + getpagesize() -1) & ~(getpagesize() -1)) |
The function prototypes, constants, flags, and data structures that
applications can use to access the memory allocation services are
defined in the
mme_api.h
header file provided with Compaq Multimedia Services for OpenVMS Alpha. Include this header file in
all application programs that use memory allocation functions.
2.1.3 Memory Allocation Function Overview
Table 2-1 provides a summary of the memory allocation functions.
| Function | Description |
|---|---|
| mmeAllocBuffer | Allocates memory to be used for buffers containing raw data being passed to or from devices through the multimedia API |
| mmeAllocBufferAndGetShminfo | Allocates memory to be used for buffers containing raw data being passed to or from devices through the multimedia API, and returns shared memory information |
| mmeAllocMem | Allocates memory for all data structures (other than buffers) that are directly or indirectly referenced by the multimedia API |
| mmeFreeBuffer | Releases a buffer that was previously allocated with the mmeAllocBuffer or the mmeAllocBufferAndGetShminfo function |
| mmeFreeMem | Releases a memory segment that was previously allocated with the mmeAllocMem function |
This section contains an alphabetical listing of the functions you can use to write applications that manage memory allocation. These functions are prefixed with mme.
#include <mme/mme_api.h> void * mmeAllocBuffer(size_t size) |
The mmeAllocBuffer function allocates memory to be used for buffers containing raw data being passed to or from devices through the multimedia API. If the connection supports shared memory, then a shared memory segment is allocated.Extensions The mmeAllocBuffer function is a Compaq extension to the Microsoft multimedia API specification.
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.
#include <mme/mme_api.h>
void * mmeAllocBufferAndGetShminfo(size_t size,
mmeShmSegmentInfo * shminforet);
|
mmeShmSegmentInfo * shminforet
Specifies a pointer to the mmeShmSegmentInfo data
structure that is filled by this function. This data structure does not
have to be allocated with the Multimedia Services for OpenVMS memory
allocation functions.
The mmeShmSegmentInfo data structure is filled in by the mmeAllocBufferAndGetShminfo function to specify the shared memory segment.
typedef struct {
ShmSeg shmseg; /* resource ID */
int shmid; /* kernel ID */
char *shmaddr; /* address in client */
Bool readOnly; /* how the server should attach it */
} mmeShmSegmentInfo;
|
The mmeShmSegmentInfo data structure has the following fields:
shmseg
Specifies the shared memory segment resource ID.
shmid
Specifies the kernel ID for the shared memory segment.
shmaddr
Specifies the address of the shared memory segment.
readOnly
Specifies the segment as read-only.
If an application wants to pass the shared memory segment address to one of the multimedia functions, such as ICCompress , then it passes shminforet->shmaddr as the pointer.
If there is a local connection to an X server and if the X server supports the MIT Shared Memory Extension, then an application can communicate the shared buffer to the X server. To do this, it needs to pass the shminforet pointer to XShmAttach . When calling the XCreateImage function, pass shminforet->shmaddr as the data pointer. For example:
if ( (image = XCreateImage(
display,
visual,
lpbiOutput->biBitCount,
ZPixmap,
0,
shminforet->shmaddr,
lpbiOutput->biWidth,
lpbiOutput->biHeight,
XBitmapPad(display),
((lpbiOut->biWidth+3)/4) * 4)) == (XImage *)NULL)
return 1;
image->obdata = (char *)(shminforet);
XShmPutImage(display, window, gc, image, 0, 0, 0, 0,
lpbiOutput->biWidth, lpbiOutput->biHeight, False);
|
Basically, the shmaddr field of the mmeShmSegmentInfo data structure is the only relevant field for the multimedia functions.
The mmeAllocBufferAndGetShminfo function allocates memory to be used for buffers containing raw data being passed to or from devices through the multimedia API, and returns shared memory information.Extensions The mmeAllocBufferAndGetShminfo function is a Compaq extension to the Microsoft multimedia API specification.The mmeAllocBufferAndGetShminfo function fills in the mmeShmSegmentInfo data structure to specify the shared memory segment.
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.
#include <mme/mme_api.h> void * mmeAllocMem(size_t size) |
The mmeAllocMem function allocates memory for all data structures (other than buffers) that are directly or indirectly referenced in the multimedia API. If the connection supports shared memory, then a shared memory segment is allocated.Extensions The mmeAllocMem function is a Compaq extension to the Microsoft multimedia API specification.
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.
#include <mme/mme_api.h> BOOL mmeFreeBuffer(void * pointer) |
The mmeFreeBuffer function releases a buffer that was previously allocated with the mmeAllocBuffer or mmeAllocBufferAndGetShminfo function.Extensions The mmeFreeBuffer function is a Compaq extension to the Microsoft multimedia API specification.Before an application attempts to free a buffer, it must check to ensure that the data in the buffer has been completely processed. For example, if an application reads data into a buffer and then writes the data out to an audio device, the data might not be completely processed before the next program statement executes. This occurs because it takes time to play an audio buffer. If the buffer is freed too soon, the audio is partially played or not played at all, depending on how far the device gets before the buffer is released.
To ensure that a buffer completes processing, an application can make calls to the mmeWaitForCallbacks and mmeProcessCallbacks functions to wait for and process callbacks before releasing the buffer. See Section 2.2 for more information about the callback services functions.
Returns TRUE if the function is successful; otherwise, it returns FALSE. A failure can occur if the memory pointed to is not a valid memory pointer.
#include <mme/mme_api.h> BOOL mmeFreeMem(void * pointer) |
The mmeFreeMem function releases a memory segment that was previously allocated with the mmeAllocMem function.Extensions The mmeFreeMem function is a Compaq extension to the Microsoft multimedia API specification.
Returns TRUE if the function is successful; otherwise, it returns FALSE. A failure can occur if the memory pointed to is not a valid memory pointer.
2.2 Managing Callbacks
This section presents the callback services available to applications.
2.2.1 Callback Services Overview
Applications use the callback services to determine whether callback events are pending and to invoke callback functions that correspond to pending callback events.
Callback functions process messages sent by a device driver during audio and video recording or playback operations to notify an application of events such as the opening and closing of devices, completion of data processing, data availability, and errors.
The following Multimedia Services for OpenVMS API functions use callback functions:
See Section 4.7 for a description of the
videoStreamInit
function. See Section 3.8 for descriptions of the
waveInOpen
and
waveOutOpen
functions and for detailed information about the specific callback
function that can be associated with each API function.
2.2.2 Callback Services Header Files
The function prototypes, constants, flags, and data structures that applications can use to access the callback services are defined in the mme_api.h header file provided with Multimedia Services for OpenVMS. Include this header file in all application programs that use callback functions.
2.2.3 Callback Function Overview
Table 2-2 provides a summary of the callback functions.
| Function | Description |
|---|---|
| mmeCheckForCallbacks | Allows an application to check for pending callbacks |
| mmeProcessCallbacks | Allows an application to process pending callbacks |
| mmeServerFileDescriptor | Returns the file descriptor used to communicate with the mmeserver |
| mmeWaitForCallbacks | Allows an application to wait for callbacks |
This section contains an alphabetical listing of the functions you can use to write applications that manage callbacks. These functions are prefixed with mme.
#include <mme/mme_api.h> BOOL mmeCheckForCallbacks() |
The mmeCheckForCallbacks function allows an application to check for pending callbacks, and immediately returns. Call the mmeProcessCallbacks function next to process pending callbacks.Extensions The mmeCheckForCallbacks function is a Compaq extension to the Microsoft multimedia API specification.
Returns TRUE if callbacks are pending; otherwise, it returns FALSE.
#include <mme/mme_api.h> void mmeProcessCallbacks() |
The mmeProcessCallbacks function allows an application to process all pending callbacks. Call the mmeProcessCallbacks function after a callback is detected by either the mmeCheckForCallbacks or the mmeWaitForCallbacks function.Extensions The mmeProcessCallbacks function is a Compaq extension to the Microsoft multimedia API specification. See Also mmeCheckForCallbacks , mmeWaitForCallbacks
#include <mme/mme_api.h> int mmeServerFileDescriptor() |
The mmeServerFileDescriptor function returns the file descriptor being used to communicate with the mmeserver. Applications can add the file descriptor to a select() function call to detect incoming callbacks.Extensions The mmeServerFileDescriptor function is a Compaq extension to the Microsoft multimedia API specification.Connections to the mmeserver are made when an interface has returned an open device handle, such as a device handle returned by the waveOutOpen , ICLocate , or videoOpen functions.
Returns a file descriptor if the function is successful; otherwise, it returns --1 if no connection to the mmeserver has been established yet.
#include <mme/mme_api.h> void mmeWaitForCallbacks() |
The mmeWaitForCallbacks function allows an application to wait for callbacks. It waits until at least one callback has arrived, though multiple callbacks may be waiting when the call returns. Call the mmeProcessCallbacks function after the mmeWaitForCallbacks function to process a callback.Extensions The mmeWaitForCallbacks function is a Compaq extension to the Microsoft multimedia API specification. See Also mmeProcessCallbacksNote that the mmeWaitForCallbacks function blocks the entire process. To avoid blocking the process, use the mmeCheckForCallbacks function to check for callbacks. When a pending callback is detected, use the mmeProcessCallbacks function to process the callback.
2.3 Representing Time
The MMTIME data structure represents time in one or
more formats including milliseconds, samples, bytes, and SMPTE and song
pointer formats. SMPTE format is an encoding format
developed by the Society of Motion Picture and Television Engineers.
The following
multimedia functions use the MMTIME data structure:
Example 2-1 shows the MMTIME data structure definition.
| Example 2-1 MMTIME Data Structure Definition |
|---|
typedef struct mmtime_tag {
UINT wType; /* Contents of the union */
union {
DWORD ms; /* Milliseconds (wType = TIME_MS) */
DWORD sample; /* Samples (wType = TIME_SAMPLES) */
DWORD cb; /* Byte count (wType = TIME_BYTES)*/
struct { /* SMPTE (wType = TIME_SMPTE) */
BYTE hour; /* Hours */
BYTE min; /* Minutes */
BYTE sec; /* Seconds */
BYTE frame; /* Frames */
BYTE fps; /* Frames per second */
BYTE dummy; /* Pad byte */
} smpte;
struct { /* MIDI (wtype = TIME_MIDI) */
DWORD songptrpos; /* Song pointer position */
} midi;
} u;
} MMTIME;
|
The MMTIME data structure has the following fields:
wType
Specifies the format used to represent time. The following flags are
defined:
TIME_MS
Specifies time in milliseconds.
TIME_SAMPLES
Specifies time in number of samples.
TIME_BYTES
Specifies time in number of bytes.
TIME_SMPTE
Specifies time in SMPTE video format.
TIME_MIDI
Specifies time in song pointer format. (This time format is not supported.)
Before calling a function that uses the MMTIME data structure, set the wType field to indicate the requested time format. Be sure to check the wType field after the function call to see if the requested time format is supported. If the requested time format is not supported, the time is specified in an alternate time format selected by the device driver, and the wType field is changed to indicate the selected time format.
| Previous | Next | Contents | Index |