Difference between revisions of "LIBRARIES PUBLIC DOCUMENT KINROU5GOU"

Revision as of 20:19, 5 August 2017

Kinrou 5 Gou Interface Library for HI-TECH C By Tatsuhiko Syoji 1998

What is it for?

This is library for controlling FM/PSG/SCC sound driver "Kinrou 5 Gou" by Keiichi Kuroda from HI-TECH C. HI-TECH C and Kinrou 5 Gou are required separately.

FIles

KINROU .H  

Header file of this library.

LIBK .LIB 

Library file of this library.

INST .BAT 

Bat file to append files of this library to other appropriate library.

KINLIB .TXT 

This file.

HIKIN .COM :Sample program of this library.

HIKIN .C  

C language part of sample program for this library.

HIKINA .AS  

Assembler part of sample program for this library.

MKHIKIN .BAT 

Bat file to build sample program.

All of files which has .AS extension other than HIKINA.AS are source file of each functions of this library.

* .O

Object of functions of this library.

REMAKE .BAT :Bat file to re-compile this library. LICENCE .BAT :License text of this library.

Setting up

Copy KINROU.H to the directory of the drive which exist other include files. Next, copy LIBK.LIB to the directory and drive which exist library files or attach function objects to existed library by INST.BAT file.

How to use INST.BAT

INST.BAT is a bat file to attach functional object files of this library to appropriate library.

Object files of functions are appended to library file by typing >INST LibraryFileName from directory and drive which has functional objects and is

executable environment of LIBR.COM of HI-TECH 

Objects of functions in this package does not depend on other libraries, thus it is locatable everywhere in library file inside.

How to use this library

This is the sequence to use Kunrou 5 gou with this library.

Include KINROU.H in program which use this library first.

Next, load KINROU5.DRV, main routines of Kinrou 5 Gou into 2000H bytes memory block after address 6000H and hook timer interruption.

After that, load song data where time interruption routine can see it, initialize the driver, initialize play setting(with kinrou_init() function), call function to start playing(kinrou_play1(), kinrou_play2()) and set 6029H(playing routine of Kinrou 5 gou) into timer interrupt routine. HI-TECH C can play MuSICA/Kinrou format data.

Link library file which contains object of functions in this library when you compile. Thus we can play MuSICA/Kinrou format data from HI-TECH C. Refer sample programs for details.

About sample program

I suppose sample program can be compiled by executing MKHIKIN.BAT with LIBK.LIB at HI-TECH C ready drive and directory.

Functions for memory management in HI-TECH C Resource kit #2 is required for compiling sample file.

Sample file reads data file and plays as follows: "HIKIN.COM DATAFILE".

KINROU5.DRV should be located at current directory.

We can control music with keyboard after starting music.

Functions

These are functions of this library.

unsigned int kinrou_init(void);

Initializes Kinrou 5 Gou. This function should be called before execution of other functions.

char kinrou_play1(void *data,unsigned char count);

Starts playing music with this function. Function kinrou_init should be executed before this function. Valuable "data" is the first address of BGM data (excluded BSAVE header). BGM data should be located at same address as address specified when data was compiled. Valuable "count" is repeat times. "0" is eternal loop.

Returns "0" when succeed and "1" when failed playing music.

char kinrou_play2(void *data,unsigned char count);

After kunrou_init function is executed, execute this function to start playing music.

Store BSAVE formatted header address of BGM data.

This function uses BSAVE header of BGM data and get both of two addresses which Kinrou 5 Gou needed - a top address of BGM data and address specified when data was compiled. Then Kinrou 5 Gou process internally and plays BGM data. Valuable "data" is the first address of BGM data (excluded BSAVE header).

BGM data does not have to be located at same address as address specified when data was compiled.

Valuable "count" is repeat times. "0" is eternal loop. Returns "0" when succeed and "1" when failed playing music.

void kinrou_stop(void);

Stops music. Revert interruption setting for Kinrou 5 Gou after execution of this function.

void kinrou_fadeout(unsigned char speed);

Fades outs music soon after this function executed with valuable "speed". Bigger valuable "speed", slower fade outs.

unsigned int kinrou_getloops(void);

Returns loop times since music has started.

char kinrou_checkplay(void);

Checks status of playing music.

When music is playing, bit 0 is "1" and when music is paused bit 1 is "1".

void kinrou_pause(void);

Switches pause/replay when executed this function.

void kinrou_vol(unsigned char v);

Sets master volume of all channels with valuable "v". Valuable "v" takes 0-15 and 0 is maximum volume.

void kinrou_volpart(unsigned char v,unsigned char c);

Sets master volume of channel "c" with valuable "v". Valuable "v" takes 0-15 and 0 is maximum volume.

Valuable "c" means sound source: 0-8 are FM, 9-11 are PSG and 12-16 are SCC.

void kinrou_psgswitch(unsigned char f);

Sets PSG output status with valuable "f". Bit 0 of "f" change PSG output: "0" means on and "1" means off.

unsigned char *kinrou_credit(void);

Returns strings of credit authority as a format of BDOS function call 09H of MSX-DOS.

unsigned char *kinrou_getparam(void *data,unsigned char kind);

Obtains parameters by calling GETPAR function call in Kinrou 5 Gou version 1.00 or higher. Gets first address of data as "data" and parameter number as "kind".

Refer Official specification document of Kinrou 5 Gou for "parameter number" and "parameters".

References

• Official specification document of Kinrou 5 Gou (by Keiichi Kuroda)
• MSX2/2+ Hayawakari Shoujiten(by Nihon Bungeisha)

(En: Pocket encyclopedia of MSX2/2+ quick learning)

Post scriptum

This library was made to implement music to homebrew game. I planned to use MPK first, but program code became bigger and bigger. Thus MPK could be loaded and I started to find music driver which uses lower addresses. Then I decided to use Kinrou 5 Gou and made this driver. I could select MGSDRV but it is execution file and driver at the same time. This makes difficult to make programming and supporting. In addition to that, integrated music composer MuSICA is very easy to compose, I choose Kinrou 5 Gou. Library itself is not so difficult to make because I experienced MPK library before. Only difference to interrupt makes more codes besides these functions. I had no choice. "Susume! Osouji Musume!" which I made is implemented BGM by this library. The biggest disk magazine in Japanese MSX scene, "NV magazine" records this game. Enjoy your programming with BGM by this library.

[NOTE] These programs and source codes are unders BSD copyright. Refer LICENSE.TXT about BSD copyright in this package. Japanese translation of BSD copyright is published at this URL. http://openlab.etl.go.jp/freesoft/BSD-j.htm

/* * Copyright (c) 1998-2000 Tatsuhiko Syoji, Japan . All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * 1 Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer as the first lines * of this file unmodified. * * 2 Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY Tatsuhiko Syoji ``AS IS'' AND ANY EXPRESS * ORIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL Tatsuhiko Syoji BE LIABLE FOR ANY DIRECT, * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING * IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */