Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide


Previous Contents Index


Chapter 2
General Services

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:

2.1.2 Memory Allocation Header Files

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.

Table 2-1 Memory Allocation Function Summary
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

2.1.4 Memory Allocation Function Descriptions

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.


mmeAllocBuffer

Name mmeAllocBuffer --- Allocate memory for data buffers Syntax


#include <mme/mme_api.h> 
 
void * mmeAllocBuffer(size_t size) 
Arguments size_t size
Specifies the amount of memory (in bytes) to allocate.


Description

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.

Return Values

1
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.

See Also mmeFreeBuffer

mmeAllocBufferAndGetShminfo

Name mmeAllocBufferAndGetShminfo --- Allocate memory for data buffers and return shared memory information Syntax


#include <mme/mme_api.h> 
 
void * mmeAllocBufferAndGetShminfo(size_t size, 
                                   mmeShmSegmentInfo * shminforet); 
Arguments size_t size
Specifies the amount of memory (in bytes) to allocate.

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.


Description

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.

The mmeAllocBufferAndGetShminfo function fills in the mmeShmSegmentInfo data structure to specify the shared memory segment.

Extensions The mmeAllocBufferAndGetShminfo function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.

See Also mmeFreeBuffer

mmeAllocMem

Name mmeAllocMem --- Allocate memory for data structures Syntax


#include <mme/mme_api.h> 
 
void * mmeAllocMem(size_t size) 
Arguments size_t size
Specifies the amount of memory (in bytes) to allocate.


Description

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.

Return Values

1
Returns a pointer to the memory that was allocated if the function is successful; otherwise, it returns a null pointer.

See Also mmeFreeMem

mmeFreeBuffer

Name mmeFreeBuffer --- Release a previously allocated data buffer Syntax


#include <mme/mme_api.h> 
 
BOOL mmeFreeBuffer(void * pointer) 
Arguments void * pointer
Specifies a pointer to the buffer to release.


Description

The mmeFreeBuffer function releases a buffer that was previously allocated with the mmeAllocBuffer or mmeAllocBufferAndGetShminfo function.

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.

Extensions The mmeFreeBuffer function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
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.

See Also mmeAllocBuffer , mmeAllocBufferAndGetShminfo

mmeFreeMem

Name mmeFreeMem --- Release a previously allocated memory segment Syntax


#include <mme/mme_api.h> 
 
BOOL mmeFreeMem(void * pointer) 
Arguments void * pointer
Specifies a pointer to the memory segment to release.


Description

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.

Return Values

1
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.

See Also mmeAllocMem

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.

Table 2-2 Callback Function Summary
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

2.2.4 Callback Function Descriptions

This section contains an alphabetical listing of the functions you can use to write applications that manage callbacks. These functions are prefixed with mme.


mmeCheckForCallbacks

Name mmeCheckForCallbacks --- Check for pending callbacks Syntax


#include <mme/mme_api.h> 
 
BOOL mmeCheckForCallbacks() 
Arguments None.


Description

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.

Return Values

1
Returns TRUE if callbacks are pending; otherwise, it returns FALSE.

See Also mmeProcessCallbacks

mmeProcessCallbacks

Name mmeProcessCallbacks --- Process all pending callbacks Syntax


#include <mme/mme_api.h> 
 
void mmeProcessCallbacks() 
Arguments None.


Description

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

mmeServerFileDescriptor

Name mmeServerFileDescriptor --- Return the file descriptor used to communicate with the mmeserver Syntax


#include <mme/mme_api.h> 
 
int mmeServerFileDescriptor() 
Arguments None.


Description

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.

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.

Extensions The mmeServerFileDescriptor function is a Compaq extension to the Microsoft multimedia API specification.


Return Values

1
Returns a file descriptor if the function is successful; otherwise, it returns --1 if no connection to the mmeserver has been established yet.

See Also None.

mmeWaitForCallbacks

Name mmeWaitForCallbacks --- Wait for callbacks Syntax


#include <mme/mme_api.h> 
 
void mmeWaitForCallbacks() 
Arguments None.


Description

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.

Note 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.

Extensions The mmeWaitForCallbacks function is a Compaq extension to the Microsoft multimedia API specification. See Also mmeProcessCallbacks

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