OSC - Documentation

 

Overview

The OSC Library currently consists of the following

The C++ source code has three major classes:

The source code is not tied to any particular C++ compiler, allthough it has been developed using Microsoft Visual C++ 6.0.

The ActiveX control wraps the OSC_SFManager class. The control is released for beta-testing to get feedback.

The current version of the OSC Library (as of June 27. 1999) is 1.1.

 

Installation instructions

Download the zip'ed archive and decompress it (using WinZip, or a similar tool) to a new folder on your hard-drive. The folder should be named 'OSC'.

For SoundFont support, you'll also need the SoundFont Management System from Creative Labs, which can be downloaded from here [12.8MB]. All you need is one file (sfman.h), but Creative's license doesn't permit me to copy the file, so ...

To install the ActiveX control (not neccessary for C++ programmers), just run the file activex/RegisterActiveXControls.bat.

 

User's Guide for C++ programmers

To use the OSC Library in your project, there are a couple of things you have to do:

1. Adding include directories

Add the path of the OSC include files to the projects. In MS Visual C++ you do this by selecting 'Project | Settings | C++ | Preprocessor' and typing the path in the field named 'Additional include directories'.

If you're using the OSC_SFManager class (for SoundFont support), add the path to the sfman.h file (included in the SoundFont Management System) to the projects include files (In MS Visual C++, 'Project | Settings | C++ | Preprocessor'   - 'Additional include directories'), or just copy it (sfman.h) to the OSC\include folder.

2. Adding the library-file to the project

Add the OSC library (.lib) file to the project by selecting 'Project | Settings | Link | General' and adding the full path to the .lib file to the end of the field named 'Object/library modules'.

There are 6 differend .lib files to choose from, and it is important that you choose the library that matches the run-time library you use. If you choose the wrong type of library, you'll get lots of linker errors. (In Visual C++, select Project | Settings | C++ | Code Generation and look at the the field 'Use run-time library').

Here's the match between OSC libraries and run-time libraries:

OSC Library Run-time library
osc_s.lib SingleThreaded
osc_m.lib MultiThreaded
osd_md.lib MultiThreaded DLL
osc_ds.lib Debug SingleThreaded
osc_dm.lib Debug MultiThreaded
osc_dmd.lib Debug MultiThreaded DLL

 

And that's it. To use the OSC classes, just #include the appropriate header file.

If you need more guidance, take a look at the source code documentation for documentation of each OSC class. Then dive right into the tutorial and the samples to get started.

Tutorial

The tutorial gives a good example of what the OSC Library can be used for, as well as a goot introduction to actually using it.

Samples

Another good example is the source code for sf2load, which is a part of the OSC distribution. This is a real world program which has been downloaded by thousands of users.

 

Source Code documentation

The complete documentation for the OSC source code is available on-line.

 

User's Guide for the ActiveX control

The ActiveX control is currently in beta. This means that the interface might change later on, and you will need to recompile your programs using this ActiveX control when the complete version is released. It will probably be a bad idea to release programs using this beta version to the general public.

I'm very interested in feedback from users of this control. Please share your experiences at the OSC newsgroup.

Please remember to register the ActiveX control, as described under the section about installation above, before trying to use it.

You should read the documentation of the OSC_SFManager class for a description of the different functions. The functions and properties of the ActiveX control closely matches the functions in this class. You should also take a look at the example webpage below as well as the tutorial.

The control's properties and functiona are as follows.

Properties:

Functions:

All functions and properties except Open, NumDevs, DevName and IsDeviceFree require that a device has been opened before use.

I have created a sample that illustrates the use of the ActiveX control. The sample is a webpage which hosts the control and uses JavaScript to control it. The webpage shows the number of installed SoundFont devices and shows a list of all soundfonts currently loaded by the first device (index 0). The webpage also lets the user select a soundfont on disk and load it into a bank. The webpage has only been tested with InternetExplorer v. 4.0 and above and might not work with older versions of InternetExplorer or with other browsers. Anyway, it's the source code that matters, and it shouldn't be too difficult to translate this example into other programming languages.

Tutorial for VisualBasic 6.0

I am not a VB programmer, so please bear with me.

Step 1 - Creating the project and adding the OSC ActiveX control

Select 'File | New Project' and choose the kind of project you want to create. This example uses the 'Standard EXE' project type.

Select 'Project | Components' and check the box next to the OSCX_SFMan Type Library. A new icon should appear on the toolbar on the left (the dockable window with the arrow, the different types of controls, etc). This is the icon of the OSCX_SFMan ActiveX control. If the OSCX_SFMan TypeLibrary entry is missing from the list, you probably have forgotten to install the control. Read the installation instructions again.

Doubleclick this new icon and the control is inserted into your form. A frame with some text in it should appear in the form.

Step 2 - Using the OSC ActiveX control

Add a text box, a list and a button.

Double-click on the button and add the following line of code:

Text1 = OSCX_SFManControl1.NumDevs
List1.Clear
OSCX_SFManControl1.Open (0)
For i = 0 To 127
	If OSCX_SFManControl1.BoolIsMIDIBankUsed(i) Then
		List1.AddItem (OSCX_SFManControl1.LoadedBankDescriptor(i))
	End If
Next i
OSCX_SFManControl1.Close

Run the program and click the button. A number should appear in the textbox indicating the total number of SoundFont devices in your systems. If you have one SBLive! soundcard, this number will be 2 (the A and B synth), if you have one AWE32 soundcard, the number will be 1. The list should be filled with the names of the soundfonts currently loaded. You could verify that this list is correct by comparing it with the output from the SoundFont application in the AudioHQ (SBLive users), or the AWE Control Panel (AWE32/64 users).

Well, that's as far as I got today. As this is the largest VB program I have ever written, I'm pretty proud of myself now ;-). I'd be very interested in featuring the source code of a more experienced VB programmer.

More Tutorials

I'd like to have tutorials for Delphi, J++ and any other development language/environment capable of using ActiveX controls. Please contact me if you'd like to write such a tutorial.

 

Known problems

The C++ library

On some occasions, my SFExplorer has crashed when I sent MIDI CC and PitchBend messages to a SoundFont device. I haven't researched the problem thoroughly yet, and it doesn't appear in the tutorial, so it is very possible that there is something I do wrong in SFExplorer. I just thought I'd warn you.

The MIDI input and output is not real-time! On most system it should be very close to real-time. But especially on Win95 & Win98 systems where some drivers and parts of the OS kernel runs in 16-bit mode, response time cannot be quarranteed. If you want to write a program using true real-time MIDI input and output, I recommend reading Paul Messick's book 'Maximum MIDI'. He explains how to write & use a 16-bit dll to create a sequencer.

The ActiveX Control

The only kind of error reporting is throug the HRESULTs (S_OK, E_FAIL) that all functions and properties return. I don't know how the different development environments deal with ActiveX errors yet, and the system for error reporting will very probably have to be modified.

 

History

[May 25. 1999] Version 1.0
  • First  public release
[June 27. 1999] Version 1.1
  • ActiveX control added
  • Changed some of the function names so that the first letter is uppercase (all functions now starts with uppercase)
  • Added 2 functions to the OSC_SFManager class to make it easier to access information about Synthesizer Emulation

 

Recommended reading

Here are some of the books which I recommend:

 


The complete HammerSound website, including all text, images and databases,  is copyright (c) 1997-2000 Thomas Hammer
[HammerSound Home]