Графическая Библиотека MSX для BDS C версия 3.05 (c) А.Родионов 2022 г. ================================================================ MSX Graphic Library for BDS C v3.05 АННОТАЦИЯ В данном документе содержится описание применения библиотеки функциЙ "MSX Graphic Library for BDS C" версии 3.02. Документ предназначен для разработчиков программного обеспечения на компьютерах MSX2 и MSX и содержит следующие разделы: "Назначение", "Условия применения", "Описание функций", "Рекомендации по использованию и форматы данных". "MSX Graphic Library for BDS C" является авторской разработкой А.Б.Родионова (Москва, 1986~1988). Оригинальная документация ведется на английском языке для совместимости с оборудованием, не имеющим кириллических знакогенераторов и может быть поставлена по специальному заказу. По этой же причине англоязычными являются все комментарии в текстах программ и диалог, ведущийся утилитами ПС "МАЭСТРО". Данный документ не следует рассматривать как учебное пособие по компьютерам MSX2 и MSX - напротив он расчитан на подготовленых программистов, знающих архитектуру этих компьютеров, но испытывающих затруднения в выборе инструментальных средств для разработки своих программ. -------------------------------------------------------------------- ПС "МАЭСТРО" является первым в СССР программным продуктом, обладающим имеющим законную силу Copyright (C) - правом на тиражирование и копирование. -------------------------------------------------------------------- 1. НАЗНАЧЕНИЕ "MSX Graphic Library for BDS C" (в дальнейшем именуемая просто "Библиотека") предназначена для программистов, использующих компилятор BDS C. Библиотека разработана специально для MSX-машин. Она обеспечивает полный доступ ко всей аппаратуре MSX2 и MSX (в дальнейшем именуемой MSX1) из программ, написанных на языке С. Кроме обращений к стандартным функциям BIOS/SUBROM MSX, библиотека включает в себя ряд новых специальных функций и методов доступа, облегчающих программирование сложных и ресурсоемких задач. Библиотека может быть использована для разработки учебных программ, компьютерных игр, системных и прикладных программ и для других применений. Библиотека включает в себя следующие подразделы: - параллельные процессы с циркулярной и линейной очередями, почтоЙ и др.; - базовые методы работы с манипулятором "мышь"; - спрайтовое зеркало; - специальные методы доступа; - работа с прерываниями; - работа с мэппером; - отладочные функции; - вспомогательные функции. - дисковый ввод/вывод для VRAM MSX2; - блочные пересылки RAM-VRAM, VRAM-RAM, VRAM-VRAM. - функции для рисования точек, линий, блоков и пр.; - вывод символов на графический экран; - текстовые меню в графическом режиме; - прямой доступ к текстовому экрану; - опрос специальных клавиш клавиатуры; - работа с мышью; - спрайты (логический уровень); - доступ к оглавлению диска и его сортировка; - методы организации и выделения оперативной памяти; - копирование текстового и графического экранов на принтер; - ввод/вывод для магнитной ленты; - работа со звуковым генераторм MSX; - сжатие/расширение информации в памяти; - доступ к диску по секторам. - загрузка знакоместного полиэкрана; - управление знакоместным полиэкраном; - графические и текстовые окна для полиэкрана; - спрайты MSX1; - прямой ввод/вывод для полиэкрана. 2. УСЛОВИЯ ПРИМЕНЕНИЯ Для пользования Библиотекой необходим MSX компьютер с оперативной памятью минимум 64 Кбайт и минимум одним диск-драйвом. Программы, написанные с использованием Библиотеки и компилятора BDS C, могут быть рассчитаны и на "бездисковую" или "сетевую" конфигурацию объектной машины (при соответсвующем их программировании) или на компьютер с дисками и другим объемом как оперативной, так и видео-памяти. Большая часть функций Библиотеки может быть использована как для компьютеров MSX1, так и MSX2, но некоторые функции (указаны особо в описании) применимы ТОЛЬКО к MSX1 или ТОЛЬКО к MSX2. В частности, раздел библиотеки GRPLIB2 содержит функции ТОЛЬКО для MSX2 и НЕ ДОЛЖЕН использоваться при написании программ для MSX1, а раздел GRPLIB5 и заголовок GRPMSX1.H ДОЛЖНЫ быть подключены к программе, если она рассчитана на компьютер MSX с 16 К видео-памяти и без SUBROM (дополнительного 16 К расширения ПЗУ, обеспечивающего большинство функциЙ MSX2 со 128 Кбайт видео-памяти и энерго-независимой памятью для календаря, часов, пароля и т.п.). Абсолютно необходимым условием успешного применения функций библиотеки является знание программистом архитектуры и особенностей компьютеров MSX и MSX2, операционной системы MSXDOS и основных принципов работы со знакоместной и бит-мэп графикой. Кроме этого, совершенно необходимо знание языка Си и особенностей его конкретной реализации в системе BDS C (смотри C Compiler v1.5 Users Guide, Copyright (c) 1982 by Leor Zolman BD Software). Для нормальной работы большинства функций Библиотеки требуется выделение и инициализация специальной системной рабочей области памяти. Эта рабочая область выделяется автоматически при ОБЯЗАТЕЛЬНОМ включении в создаваемую программу одного из двух системных заголовков: #include GRPLIB0.H - для MSX2 или #include GRPMSX1.H - для MSX1 ВНИМАНИЕ! Любой из этих заголовков резервирует рабочую область в External и для правильной работы библиотеки должен быть записан в качестве САМОГО ПЕРВОГО оператора Вашего файла с исходным текстом программы на Си. Иными словами, Ваши собственные глобальные переменные должны располагаться только ПОСЛЕ системной рабочей области (иметь бОльшие адреса памяти). Внутрь этих заголовков всегда автоматически включается заголовок BDSCIO.H GRPMSX1.H включает в себя автоматический вызов GRPLIB0.H и его собственные функции могут замещать некоторые другие функции разделов библиотеки GRPLIB1~GRPLIB5. Переменные условной компиляции для заголовков Есть несколько специальных операторов для условной компиляции заголовков .Н, которые можно указывать перед их вызовом: #define NO_FUNC /* используется в GRPMSX1.H */ Используйте этот оператор, если вы компилируете и линкуете более, чем 1 исходный файл на Си. Этот оператор условной компиляции должен присутствовать во всех ваших файлах с исходными текстами кроме ОДНОГО во избежание повторных генераций функций с одинаковыми именами т.к. заголовок GRPMSX1.H содержит в себе определения и переопределения функций GRPLIB0.H, специфических для MSX1 и не использующих SUBROM и VDP9938. #define NO_TICKS /* используется в GRPMSX1.H */ Создаётся пустая функция totick() { } если не предполагается использование параллельных процессов. Это экономит память. #define NO_PUTSXY /* используется в GRPMSX1.H */ Не создаётся переопределение функции putsxy() для вывода символов на текстовой экран MSX1 с использованием BIOS вместо обращенния к VDP9938 #define NO_RTOVLW /* используется в GRPMSX1.H */ Не создаются переопределения функций _rtovlw() и _vtorlw() для работы через BIOIS вместо прямого обращенния к VDP9938 #define NO_MOUSE /* используется в GRPMSX1.H */ Не используется вызов SUBROM в totick() для работы с мышью даже если используется MSX2 #define NO_PBUF /* используется в GRPMSX1.H и GRPLIB0.H */ Не создаётся массив _pbuf[32] в GRPLIB0.H для работы с функцией fmt(). Сама функция fmt() также будет недоступна. Это экономит память. #define JOY2ONLY /* используется в GRPSTICK.H и GRPLIB0.H */ Используется опрос джойстика только в порте 2. Функция chkmouse() недоступна. Это экономит память. Предупреждения ВНИМАНИЕ! Для правильной работы библиотечных функций системная рабочая область ДОЛЖНА находиться в диапазоне адресов 4000~C000 (страницы 1 и 2) - поэтому, если Ваша программа меньше, чем 0х4000, компилируйте и линкуйте её с параметрами '-е4000' как минимум. Таким образом, компилятору cc.com и ликовщику clink.com задается явный адрес начала области External, где находятся служебные вызовы некоторых встроенных бибилиотечных функций, в частности, обращения к функциям BIOS, SUBROM и MEMORY MAPPER. Использование для External областей памяти выше 0xBFFF также является недопустимым. ВНИМАНИЕ! Кроме выделения рабочей области при помощи включения в Вашу программу стандартных заголовков GRPLIB0.H или GRPMSX1.H, для нормальной работы библиотечных функций требуется последующая ИНИЦИАЛИЗАЦИЯ этой рабочей области с помощью функции grpini() или gameini()/gameini2(). Если вы забудете вызвать одну из этих функций в начале Вашей программы - вы можете получить НЕПРЕДСКАЗУЕМЫЕ РЕЗУЛЬТАТЫ! ПРИМЕР 1. ======== /* +-----------------------------------------------------------+*/ /* | -- Образец правильного выполнения требований для MSX2: -- |*/ /* +-----------------------------------------------------------+*/ #include grplib0.h /* выделение системной рабочей области */ char foo,foo2; /* глобальные переменные пользователя */ unsigned bar,bar2; /* глобальные переменные пользователя */ main() /* главная программа */ { int zot,zot2; /* локальные переменные пользователя */ grpini(); /* инициализация системной рабочей области */ /* ниже используются библиотечные функции - см. описание */ screen(5); palette(0,0,0,0); color(15,0,0); cls(); . . . zot=frotz(0); . . . EXIT /* выход в MSXDOS */ } int frotz(zap) int zap; { ... } /* ------------------- Конец образца -------------------- */ ПРИМЕР 2. ======== .+---------------------------------------------------------+ .| ----- Образец задания на компиляцию и компоновку ------ | .+---------------------------------------------------------+ cc gro clink gro -f grplib4 grplib3 grplib2 grplib1 grpliba -e6000 . -------------------- Конец образца ---------------------- Примечания: 1. Точка '.' может быть использована в MSXDOS вместо REM 2. Если в файле GRO.CRL (результат работы компилятора BDS C) появляются функции с именами, такими же как и в файлах Библиотеки GRPLIB4.CRL ~ GRPLIB1.CRL - они заменяют соответствующие функции Библиотеки, так как находятся в командной строке clink ДО переключателя '-f' (см. BDS C clink). Этот прием используется для подключения функций пользователя вместо стандартных системных заглушек, находящихся в библиотеке (process0() ~ process9(), tickexit() - см.ниже), а также для исключения нежелательных библиотечных функций, которые подключаются автоматически (путем написания заглушек пользователем - см.ниже). 2. Порядок следования библиотечных файлов по убыванию их номеров ... -f grplib5 grplib4 grplib3 grplib2 grplib1 grpliba ... является существенным для clink, так как в противном случае clink не найдет функции, на которые появятся отсылки "назад" (см. BDS C clink). 3. ОПИСАНИЕ ФУНКЦИЙ Раздел Библиотеки GRPLIB1 ========================= ----- СПЕЦИАЛЬНЫЕ ФУНКЦИИ ----------------------------------------------- beep(n) char n; Подача звукового сигнала 'n' раз. char *errmsg(errnum) char errnum; Расширенная версия стандартной функции errmsg() из библиотеки Л.Зольмана - !ПЕРЕОПРЕДЕЛЕНИЕ! _fataler(mode,msg1,msg2) char mode,*msg1,*msg2; Аварийный выход из программы в MSXDOS с установкой (без установки) Screen 0 и выдачей сообщения (сообщений). 'mode': 0 - Screen 0 и вывод только 'msg1' 1 - Screen 0 и вывод "Sorry, fatal error detected" на 1-й строке и 'msg1' на второй строке. 2 - Screen 0 и вывод "Sorry, fatal error detected" на 1-й строке, а на второй 'msg1' и 'msg2'. 10 - выводить 'msg1' не устанавливая Screen 0. 11 - выводить "Sorry, fatal error detected" на 1-й строке и 'msg1' на второй строке не устанавливая Screen 0. 12 - выводить "Sorry, fatal error detected" на 1-й строке, а на второй 'msg1' и 'msg2' не устанавливая Screen 0. 13 - выводить 'msg1' и 'msg2' не устанавливая Screen 0. ----- УПРАВЛЯЮЩИЕ ФУНКЦИИ ----------------------------------------------- grpini() Инициализация рабочей области Библиотеки. Бнимание! ПОЧТИ НИЧЕГО НЕ БУДЕТ РАБОТАТЬ, ЕСЛИ вы ЗАБУДЕТЕ НАПИСАТЬ grpini() или gameini()/gameini2() (см.ниже) В НАЧАЛЕ ВАШЕЙ ПРОГРАММЫ!!! screen(mode) char mode; Установить тип графического экрана: 0~8 для MSX2, 0~3 для MSX1. Палитра не инициализируется. Используйте paletini(), если предполагается в дальнейшем использовать функции paletv() или paletrst(). cls() Очистка экрана. Применима к любому типу экрана 0~8. sprctl(size,magn,disp,mode) char size,magn,disp,mode; ----- только для MSX2 ----- (см. gameini() для MSX1) Инициализация и настройка механизма работы со спрайтами. Используйте специальные имена из файла GRPLIB0.H в качестве параметров этой функции: для size : SIZE_8 или SIZE_16 - размер 8 или 16 точек для magn : MAGNIFIED или UNMAGNIFIED - увеличение в 2 раза для disp : ENABLE или DISABLE - разрешение/запрет вывода спрайтов на экран для mode : SINGLE или SIMULTANEOUS - режим вывода спрайтов (см. ниже) Если вы хотите оставить без изменения значения каких-либо параметров - пишите имя NONE. 'mode' специфицирует механизм, используемый для управления спрайтами: SINGLE - каждое выполнение функции sprite() (см. ниже) приводит к немедленной модификации участков VRAM, определяющих координаты и другие параметры, относящиеся к данному плану спрайта (Sprite Attribute Table модифицируется в специальной рабочей области библиотеки, называемой "спрайтовое зеркало" в RAM, после чего БЛОК этой области пересылается (отражается) в VRAM для одновременного изменения параметров ВСЕХ спрайтов, определенных одной функцией sprite()). SIMULTANEOUS - функция sprite() модифицирует спрайтовое зеркало, но не пересылает блок данных в VRAM - эта операция выполняется специальным скрытым от пользователя процессом каждый "тик" таймера в функции totick() - диспетчере параллельных процессов. Этот скрытый процесс активируется только в случае задания mode = SIMULTANEOUS и пересылает каждый "тик" ВСЕ спрайтовое зеркало целиком из RAM в VRAM. Такой режим является более "мягким" и часто более эффективным для работы со спрайтами одновременно из нескольких параллельно выполняющихся процессов, но он постоянно занимает время процессора и делает лишние пересылки в Screen 0. Поэтому по умолчанию mode = SINGLE. вы можете "мягко" переходить из SINGLE в SIMULTANEOUS и наоборот во время выполнения программы без потери данных в спрайтовом зеркале. Работа этого механизма не зависит от TICKON/TICKOFF (см.ниже). clrspr() ----- только для MSX2 ----- Стирание всех спрайтов в VRAM и в спрайтовом зеркале. clrspr() будет корректно работать только в том случае, если предварительно была вызвана функция screen() с параметром, отличным от нуля, а также sprctl() с определением размера спрайтов. paletini() ----- только для MSX2 ----- Инициализация палитры и VRAM для палитры. Не забудьте вызвать эту функцию, если будете использовать paletv() или paletrst(). Область сохранения для палитры может быть организована в разных областях VRAM в зависимости от того, какая страница VRAM была активна в момент использования paletini() - пожалуйста, будьте осторожны! (это одно из неудачных решений в SUBROM). paletrst() ----- только для MSX2 ----- Восстановить палитру, запомненую в VRAM. paletv(paletnum,r,g,b) int paletnum,r,g,b; ----- только для MSX2 ----- Установить цветовой код для палитры 'paletnum'. В случае отрицательного значения какого-либо параметра - старое значение остается без изменения. Это стандартная SUBROM-версия, работающая с областью сохранения палитр в VRAM. palette(paletnum,r,g,b) int paletnum,r,g,b; ----- только для MSX2 ----- То же самое, что и paletv(), но VRAM не используется для сохранения палитры. Область сохранения палитры организуется в рабочей области RAM Библиотеки. paletini() и paletrst() не работают с этой областью - поэтому Вам не надо их использовать, если вы работаете с palette(). Область сохранения палитр в рабочей области Библиотеки обнуляется во время выполнения grpini(). !!!Для работы с областью сохранения палитр в RAM!!! GETPLT(paletnum,r,g,b) /* macro */ ----- только для MSX2 ----- Запись в Ваши переменные r, g, и b текущих значений Красного, Синего и Зеленого для палитры paletnum. !!!Для работы с областью сохранения палитр в RAM!!! paletrot(<список палитр>,255) char <список палитр>; ----- только для MSX2 ----- "Вращение" влево палитр в списке палитр. Более мощный эквивалент "Colour Rotation" Yamaha Painter. '255' - признак конца списка палитр. Примеры использования: paletrot(1,5,3,255); переписывает палитры: 3 -> 5, 5 -> 1, 1 -> 3; paletrot(4,2,7,6,1,255); переписывает палитры: 1 -> 6, 6 -> 7, 7 -> 2, 2 -> 4, 4 -> 1. !!!Для работы с областью сохранения палитр в RAM!!! paletblk() ----- только для MSX2 ----- Установить палитры 0~15 в (0,0,0) - черный цвет. !!!Для работы с областью сохранения палитр в RAM!!! color(fg,bg,bd) int fg,bg,bd; Установить цвета экрана (номера палитр) для переднего плана (fg), заднего плана (bg) и бордюра (bd). page(display,active) int display,active; ----- только для MSX2 ----- Управление страницами VRAM для Screen 5~8. char swpage() ----- только для MSX2 ----- Обмен (swap) страниц 'active' и 'display'. Возвращает номер страницы 'active'. char swpaged() ----- только для MSX2 ----- Обмен (swap) страниц 'active' и 'display'. Возвращает номер страницы 'display'. showpage(mode) char mode; Отладочная функция, которая обычно стандартно подключается к каждой программе и вызывается диспетчером параллельных процессов с параметром 0 /showpage(0)/. В этом режиме функция проверяет нажатие клавиш STOP и SELECT и, если они нажаты, захватывает управление. После этого, нажатие функциональных клавиш F1~F4 дает возможность визуально проверить состояние всех страниц VRAM с плавным просмотром каждой страницы при помощи клавиш курсора, F5 возвращает управление в прерванную программу, STOP и F5 - возвращает управление MSXDOS с выдачей статистики использования процессов и состояний почтовых ящиков (см.ниже). ------------------------------------------------------------- ВНИМАНИЕ! Для сокращения объема уже отлаженной программы можно исключить эту функцию на этапе компоновки, написав в тексте Вашей программы заглушку с тем же именем: showpage() { } В этом случае она будет подключена к Вашей программе вместо библиотечной функции showpage() (см. BDS C clink). Этот же метод можно использовать для исключения других нежелательных библиотечных функций, которые подключаются автоматически. Например, если вы не планируете использовать параллельные процессы - напишите заглушку totick() { } и диспетчер параллельных процессов не будет подключен к Вашей программе. ------------------------------------------------------------- Функция showpage() может быть вызвана в Вашей программе и в явном виде: showpage(1) захватит управление без проверки STOP и SELECT, showpage(2) завершит выполнение программы с выдачей статистики по параллельным процессам. clrbuf() Очистка буфера клавиатуры. backup() Восстановление параметров экрана из энерго-независимой памяти для MSX2 или стандартных значений из файла GRPMSX1.H для MSX1. ----- ПАРАЛЛЕЛЬНЫЕ ПРОЦЕСЫ ---------------------------------------------- totick() Диспетчер параллельных процессов. Алгоритм работы: Независимо от того, был или нет "тик" таймера, вызывается функция пользователя с именем process0(). В случае, если с момента предыдущего вызова totick() таймер не изменил своего значения (анализируется jiffy) - управление возвращается к вызвавшей totick() функции. Если же значение таймера изменилось (прошел квант времени, равный как минимум одному "тику"): - вызывается функция с именем showpage() (см.выше), - механизм работы со спрайтовым зеркалом (если активирован - см.выше), - механизм отслеживания абсолютных координат манипулятора "мышь" для MSX2 (если активирован - см.ниже), - процесс пользователя с именем tickexit(), - диспетчер циркулярной очереди процессов с именем _calproc(), который вызывает один из процессов пользователя с именами process1()~process9() (по одному на каждый "тик"). После завершения выполнения всех вызванных функций, управление возвращается к вызвавшей totick() функции. Процессы пользователя process0(), tickexit() и process1()~process9() могут сами обращаться к totick() во время их выполнения, так как в это время они блокируются диспетчером от нежелательной вложенности вызовов. Обращения к totick() встроены в большинство стандартных функций Библиотеки и, поэтому, в программах, интенсивно использующих библиотечные функции, обращение к диспетчеру происходит с достаточной частотой для нормирования вызова процессов пользователя по каждому кванту таймера. Если же программа пользователя не обращается к диспетчеру достаточно часто (например, используется много арифметических вычислений) - для нормальной работы диспетчера рекомендуется вставлять обращения к нему в тексте программы в явном виде: totick(); Функции process0(), tickexit() и processN() (N=1~9) содержатся в Библиотеке в виде заглушек и автоматически заменяются на функции пользователя с такими же именами (если пользователь oписал их в своей программе). Эта замена происходит на этапе компоновки программы при помощи clink. TICKON /* macro */ Активация механизма псевдо-прерываний - разрешение вызова функций process0(), tickexit() и process1()~process9() диспетчером параллельных процессов totick(). TICKOFF /* macro */ Деактивация механизма псевдо-прерываний - запрет вызова функций process0(), tickexit() и process1()~process9() Установлен по умолчанию после выполнения grpini(). TICKSTOP /* macro */ Временная приостановка механизма псевдо-прерываний без изменения состояния TICKON/TICKOFF. Используется обычно в совокупности с TICKSTART. TICKSTART /* macro */ Отмена TICKSTOP без изменения состояния TICKON/TICKOFF. Установлен по умолчанию после выполнения grpini(). MAXPROCS(n) /* macro */ Определение максимального количества процессов в циркулярной очереди process1()~process9() (длины очереди). 0 <= n <= 9. По умолчанию - 0 (ни одного). вы можете изменять длину циркулярной очереди во время выполнения Вашей программы. Следует заметить, что частота вызова каждой отдельной функции process1()~process9() обратно пропорциональна числу процессов в циркулярной очереди, определенному при помощи MAXPROCS(). ACTIVATE(pnum) /* macro */ Активировать процесс 'pnum' (0~9). Внимание! Процесс может быть активирован, но, тем не менее, никогда не вызван, если его номер больше, чем число процессов, определенных при помощи MAXPROCS(). По умолчанию, после выполнения grpini() все процессы находятся в "активном" состоянии, но не выполняются, так как MAXPROCS(0). DEACTIVATE(pnum) /* macro */ Деактивировать процесс 'pnum' (0~9). Процесс переводится в "пассивное" состояние - следующий процесс в циркулярной очереди анализируется на "активность". PUTMAIL(boxnum,message,who) /* macro */ Имеется 16 "простых" почтовых ящиков (0~15) без очередей. вы можете положить в почтовый ящик 'boxnum' (char) сообщение 'message' (integer) и сообщить, кто его послал 'who' (integer) другому (другим) процессам, которые могут проверять этот почтовый ящик. PUTMAIL() является макросом, возвращающим значение OK (0), если сообщение успешно положено в почтовый ящик, или ERROR (-1) в случае, если там уже что-то лежит и еще никем не получено при помощи GETMAIL() (message != 0). Таким образом, if (PUTMAIL(...) == ERROR) <ждите и пробуйте снова> Конечно, в рамках Z80 и BDS C, 'message' может быть, в том числе, и указателем на какие-либо даннные или структуры. В простых случаях, вы можете использовать почтовые ящики непосредственно, так как они имеют стандартные имена MAILBOX(0)~MAILBOX(15) (номер почтового ящика может быть переменной). Примеры: MAILBOX(5)=TRUE; if (MAILBOX(i) == 61) { ... } GETMAIL(boxnum,messvar,sendvar) /* macro */ Забрать сообщение из почтового ящика 'boxnum' в переменную 'messvar', а идентификатор пославшего - в переменную 'sendvar'. 'messvar' будет равна 0, если в ящике ничего нет. GETMAIL() устанавливает в 0 значение почтового ящика после того, как заберет оттуда сообщение. АBANDONWINDOW /* macro */ Специальный тип почты, заставляющий последнее меню, открытое при помощи windsel() (см.ниже) прекратить ожидание выбора альтернативы. tickexit() Системная заглушка для процесса пользователя. Напишите функцию с таким же именем - и она будет подставлена clink на этапе компоновки вместо заглушки. Эта функция будет выполняться каждый "тик" таймера /при достаточном количестве обращений к totick()/. К tickexit() неприменимы операции ACTIVATE/DEACTIVATE - ее выполнение зависит только от TICKON/TICKOFF и TICKSTART/TICKSTOP. Выполняется только в состоянии TICKON и TICKSTART!!! process1() ... process9() Имена системных заглушек для процессов пользователя, находящихся в циркулярной очереди и получающих управление по одному на каждый "тик". К этим процессам применимы операции ACTIVATE/DEACTIVATE. Выполняются только в состоянии TICKON и TICKSTART!!! process0() Имя системной заглушки для самого приоритетного процесса пользователя не квантизируемого по "тикам" таймера - он получает управление каждый раз, когда вызывается totick() вне зависимости от того был "тик" таймера или нет. К этому процессу применимы операции ACTIVATE/DEACTIVATE. Выполняется только в состоянии TICKON и TICKSTART!!! P_COUNT0 ~ P_COUNT9 системные переменные 10 внутренних счетчиков вызовов для процессов 0~9 (unsigned). Каждый счетчик увеличивается на 1 при каждом новом вызове соответствующего процесса диспетчером. вы можете использовать их для управления частотой исполнения процесса внутри него самого, например, следующим образом: main() { ... MAXPROCS(2) TICKON ... } process1() { if (P_COUNT1 % 4) return; ... } В этом примере process1() будет фактически выполняться 1 раз за каждые 8 "тиков" таймера вместо обычного выполнения каждый второй "тик". T_COUNT системная переменная То же самое, что и P_COUNT, но для tickexit(). ----- ДРУГИЕ БАЗОВЫЕ ФУНКЦИИ -------------------------------------------- waitvdp() Ожидание обнуления битa 0 (Command Execution) статус-регистра 2 V9938 для MSX2. Количество "тиков" ожидания записывается в переменную '_waitvdp' (unsigned) в рабочей области библиотеки. drowse(t) unsigned t; "Дремать" - пропустить 't' "тиков" таймера вызывая totick(). Эту функцию удобно использовать для задания временных интервалов мигания надписей на экране, мультипликации и пр. vpoke(addr,byte) unsigned addr; char byte; Записать байт в VRAM. char vpeek(addr) unsigned addr; Прочитать байт из VRAM. writevdp(reg,byte) char reg,byte; Записать байт в регистр VDP и в соответствующий теневой регистр в RAM. char readvdp(reg) char reg; Прочитать регистр VDP (из теневого регистра RAM). char vdpstat(statreg) char statreg; Прочитать регистр статуса VDP (0~9 для V9938). char stick(stick_no) char stick_no; Получить статус (0~8) джой-стика (0~2). char trig(trig_no) char trig_no; Получить статус (TRUE/FALSE) кнопки триггера (0~4). char pad(pad_no) char pad_no; Читать Paddle, Light Pen, Mouse, Track Ball. int getjiffy() Получить значение JIFFY MSX (2-х байтовый счетчик, увеличивающийся каждый "тик" (1/60 или 1/50 секунды в зависимости от системы кодирования цвета NTSC/PAL). char *deblank(to_str,from_str) char *to_str,*from_str; Перепись строки 'from_str' в строку 'to_str' с исключением всех пробелов и знаков табуляции. Возвращается указатель на строку 'to_str'. char *upshift(str) char *str; Приведение строки 'str' к заглавным буквам ASCII. Используется функция toupper(). Возвращается указатель на строку 'str'. _rtovlw(radr,vadr,len) unsigned radr,vadr,len; Пересылка данных RAM -> VRAM для нижних 64 Кбайт VRAM. В отличие от rtovlow() (см.ниже) внутри функции не вызывается totick(). _vtorlw(vadr,radr,len) unsigned radr,vadr,len; Пересылка данных VRAM -> RAM для нижних 64 Кбайт VRAM. В отличие от vtorlow() (см.ниже) внутри функции не вызывается totick(). char movmap0(source,dest,count,mapper_page) unsigned source,dest,count; char mapper_page; Обмен данными с RAM в Memory Mapper. Во время работы функции вместо текущей страницы 0 мэппированного слота RAM временно подставляется страница 'mapper_page' из Memory Mapper. Пересылка осуществляется с адреса 'source' в адрес 'dest' длиной 'count' (1~0x4000) байтов. Во время пересылки, адреса 0~0x3FFF принадлежат подставленой странице Memory Mapper, а 0x4000~0xFFFF - текущей конфигурации RAM. После пересылки для нулевой страницы мэппированного слота восстанавливается текущая конфигурация RAM и управление возвращается в вызывающую программу. Таким образом, вы можете записывать/читать данные из любой страницы Memory Mapper блоками не более 16 Кбайт за одно выполнение movmap0(), a так же осуществлять пересылки внутри подставленой страницы, если и 'source' и 'dest' находятся в пределах 0~0x3FFF. Во время выплнения grpini() системной переменной MEMORY_MAPPER присваивается значение TRUE/FALSE в зависимости от того, оснащен ли данный компьютер аппаратурой Memory Mapper. вы можете анализировать эту переменную в своей программе и, в зависимости от этого, так или иначе строить алгоритм работы программы: if (MEMORY_MAPPER) { ... } else { ... } Кроме того, grpini() создает специальный байт _mapmask, для указания, какие страницы Memory Mapper активны в данном компьютере. Например: значение 0xF8 (1111 1000) для _mapmask означает, что в Memory Mapper активны только 3 бита (нули) и, следовательно, Вам доступны 8 страниц RAM по 16 Кбайт каждая. Дополнительно, функция movmap0() возвращает следующие коды: 0 - OK 1 - Memory Mapper не найден 2 - не найден RAM по адресу 'dest' В случае выполнения функции с кодом возврата, отличным от 0 - системная переменная MEMORY_MAPPER автоматически устанавливается в FALSE. unsigned geteda(dataname) char *dataname; Получение адреса данных, прикомпонованых к программе при помощи утилиты Extra Data Linker (EDL.COM). Любые данные (экраны, библитеки знакомест, таблицы и пр.), могут быть пркомпонованы к Вашему COM-файлу при помощи EDL с тем, чтобы быть использованными во время работы программы без дополнительных обращений к диску. Функция geteda() возвращает адрес таких данных, прикомпонованых после области External, или 0, если данные не найдены. Каждый прикомпонованый набор данных имеет 15-ти байтовый заголовок, который, в свою очередь, содержит 2-х байтовое слово с длиной набора данных + 15 (длина заголовка) и 13-ти байтовую строку с именем набора данных, оканчивающуюся двоичным нулем. Так как за одно выполнение EDL к COM-файлу может быть прикомпонован более чем один набор данных, эти 13-ти байтовые строки служат идентификаторами каждого набора данных. geteda() ищет набор данных с именем dataname (имя предварительно подвергается операциям upshift и deblank) и возвращает точный адрес данных (адрес первого байта после заголовка) или 0. Длину прикомпонованых данных можно узнать, прочитав слово (2 байта) по адресу geteda()-15. Примечание. В качестве имен данных Extra Data Linker использует имена файлов, сообщаемых ему в командной строке. При этом, префикс диск-драйва (если присутствует) не попадает в имя набора данных, а суффикс (.<расширение>) является неотъемлемой его частью. Таким образом, dataname, как параметр функции, должен включать в себя суффикс имени файла, указанного в командной строке EDL (если файл имеет суффикс). unsigned geteda2(dataname,base) unsigned dataname,base; То же самое, что и geteda(), но набор данных может быть прикомпонован начиная с адреса base. EDL версии 1.01 и выше может прикомпоновывать данные не только к концу области External (-f), но и к концу кодовой части программы (-c) или к началу области External (-e). Поэтому вы можете вызывать geteda2() следующим образом: geteda2(,codend()) для -c (конец кода), geteda2(,extrns()) для -e (начало External), geteda2(,endext()) для -f (конец External "free RAM"). Образец использования geteda2(): char *p,*c_end; if (!(p=geteda2("data",c_end=codend()))) swapin("data",p=c_end); В этом примере при помощи geteda2() проверяется наличие файла "data" (без суффикса), прикомпонованого к концу кодовой области программы (был использован переключатель '-c' EDL), и, в случае его наличия, указателю p присваивается адрес начала данных файла "data". В противном случае (если p == 0) - файл загружается в память с диска (в обоих случаях предполагается, что между концом кодовой части программы и началом области External существует достаточно места для размещения файла "data"). Этот прием удобно использовать при написании программы в том случае, когда данные, используемые программой, могут претерпевать частые изменения в процессе отладки и подготавливаются каким-либо специальным редактором (например, графика, разрабатываемая при помощи Pattern Composer). Таким образом, во время отладки данные могут просто загружаться с диска без использования EDL, а в готовой программе - составлять единое целое с COM-файлом, прикомпонованые к ней без перекомпиляции программы следующим образом (см. описание утилиты Extra Data Linker): A>edl prog progdat -c data Функции geteda() и geteda2() удобно использовать вместе с функцией expand() (см.ниже). setdi() При помощи setdi() вы можете подавить все команды EI (Еnable Interrupt) в кодовой части Библиотеки, которая выполняет обращениe к BIOS/SUBROM и, поэтому, чаще всего будете получать управление обратно в режиме DI (Disable Interrupt) - это зависит от работы конкретных точек входа BIOS/SUBROM. setei() Функция, обратная setdi() - включает все команды EI в кодовой части Библиотеки, котрые могли быть выключены setdi(). Гарантируется возврат управления в Вашу программу в EI режиме. Этот режим установлен по умолчанию, так как в противном случае многие системные механизмы MSX не будут работать в отсутствие прерываний. char *inith(addr,str) char *addr,*str; Инициализация памяти при помощи шестнадцатеричных цифр, записанных в виде литеральной строки. Все не-шестнадцатеричные символы игнорируются. Например: inith(buf,"FF A|B.01 v 2"); инициализирует buf как FFAB0120. Обратите внимание на то, что последний нуль появляется из-за нечетного количества шестнадцатеричных символов в исходной строке. Возвращает указатель на <последний записанный байт> + 1, то есть адрес следующего "свободного" байта. unsigned expand(from,to) unsigned from,to; Экспандировать (расширить, развернуть) данные, компрессированные (сжатые) при помощи утилиты FCX.COM и находящиеся по адресу from. Экспандированные данные разместить в памяти по адресу to. Возвращает длину экспандированных данных. unsigned getparm(n_arg,arg0_adr) unsigned n,*arg0_adr; Возвратить параметр n_arg (0~n) из списка параметров функции с переменным (неопределенным) числом аргументов. Пример: main() { foo(0,1,2,"text"); } foo(args) unsigned args; { printf("%d %s",getparm(2,&args),getparm(3,&args)); } В результате выполнения этой программы будет выведено на экран: 2 text Примечание: альтернативным (и более быстрым) способом извлечения аргументов по номеру является использование макросов VARPARMS() и PARM() (см.ниже). Раздел Библиотеки GRPLIB2 (ТОЛЬКО ДЛЯ MSX2) ========================= ----- ДИСКОВЫЕ ФУНКЦИИ MSX2 (SCREEN 5~8) -------------------------------- dtov(fname,dx,dy,dir,lop) char *fname,dir,lop; unsigned dx,dy; Загрузка в VRAM файла fname. Файл загружается начиная с координат dx,dy VRAM с направлением передачи данных dir и применением логической операции lop. Размер файла (ширина и высота в точках) записывается в первых двух словах этого файла - это формат оператора "COPY" Бейсика MSX2 и "Data" Yamaha Painter. Используйте специальные ключевые слова из стандартного заголовка GRPLIB0.H: для dir - R_D вправо вниз - L_D влево вниз - R_U вправо вверх - L_U влево вверх для lop без прозрачного цвета: PSET или IMP, AND, OR, XOR или EOR, NOT или PRESET для lop с прозрачным цветом: TPSET или TIMP, TAND, TOR, TXOR или TEOR, TNOT или TPRESET ВНИМАНИЕ! Эта функция использует точку входа в SUBROM, которая работает некоррекно - а именно, затирает вторую страницу RAM (0x8000~0xBFFF). Будьте осторожны! vtod(fname,sx,sy,width,height,dir,lop) char *fname,dir,lop; unsigned dx,dy,width,height; Запись на диск в файл fname информации из VRAM. Файл записывается начиная с sx,sy VRAM с направлением передачи данных dir и применением логической операции lop. Ширина прямоугольного блока даннах из VRAM задается width, высота - height (в точках). Используйте специальные ключевые слова из стандартного заголовка GRPLIB0.H для dir и lop (см. dtov()). ВНИМАНИЕ! Эта функция использует точку входа в SUBROM, которая работает некоррекно - а именно, затирает вторую страницу RAM (0x8000~0xBFFF). Будьте осторожны! dtor(fname,start_adr,end_adr) char *fname; unsigned start_adr,end_adr; Загрузка файла fname в RAM. rtod(fname,start_adr,end_adr) char *fname; unsigned start_adr,end_adr; Сохранение блока данных из RAM в файле fname. ----- Специальный набор дисковых функций -------------------------------- char dtova2(fname,dx,dy) char *fname; unsigned dx,dy; Загрузка файла в активную страницу VRAM с диска. Эта функция "понимает" компрессированный формат данных (ширина < 0, то есть -width). вы можете дополнительно специфицировать тип данных, которые вы загружаете установкой системной переменной _picture в состояние TRUE (по умолчанию) или FALSE. Для этой функции dir=R_D, lop=PSET в любом случае ее использования. Если вы установили _picture=FALSE, данные не анализируются на наличие заголовка width/heght и загружаются в VRAM последовательно до обнаружения ситуации EOF. dtova2() возвращает ОК (0) или номер ошибки для errmsg(), если ошибка имела место при чтении информации с диска. SUBROM не используется, поэтому эта функция работает корректно. Внимание! Иногда вы можете получать неожиданные результаты, если адреса загрузки VRAM пересекают границу FFFF~10000. Это связано с некоторыми особенностями V9938 - рекомендуем в этих случаях использовать раздельную загрузку нижних и верхних 64 Кбайт VRAM. rtova2(radr,dx,dy) unsigned radr,dx,dy; Пересылка данных из RAM в активную страницу VRAM с координатами dx,dy. Эта функция так же "понимает" компрессированный формат данных (ширина < 0, то есть -width). вы так же можете дополнительно специфицировать тип данных, которые вы пересылаете установкой системной переменной _picture в состояние TRUE (по умолчанию) или FALSE. Для этой функции dir=R_D, lop=PSET в любом случае ее использования. SUBROM не используется. char vtoda2(fname,sx,sy,width,height) char *fname; unsigned sx,sy,width,height; Сохранение данных из активной страницы VRAM (координаты sx,sy, размеры width и height) в файле fname. Функция является обратной по отношению к dtova2(). Компрессор данных не имплементирован из-за сравнительно большого объема занимаемой им оперативной памяти. vtoda2() возвращает ОК (0) или номер ошибки для errmsg(), если ошибка имела место при записи информации на диск. SUBROM не используется. Примечание. Для компрессии файлов в подобных форматах автором разработана программа Picture Compressor, которая не входит в состав ПС "МАЭСТРО" и может быть в дальнейшем поставлена по специальному заказу. Эта утилита разработана специально для визуальной компрессии/экспандирования графических данных в формате COPY (Data) Screen 5. vtodpage(fname,page_no,len) char *fname,page_no; unsigned len; Прямой dump страницы page_no VRAM в файл fname объемом len байт. Dump всегда начинается с начала страницы (0~3 для Screen 5 или 6 и 0~1 для Screen 7 или 8) с координатами (0,0) и включает данные в VRAM длиной len байт. vtodpage() возвращает ОК (0) или номер ошибки для errmsg(), если ошибка имела место при записи информации на диск. SUBROM не используется. char xtova2(fname,dx,dy) char *fname; unsigned dx,dy; Эта функция сначала проверяет Extra Data для конца области External (переключатель '-f', см. geteda() и Extra Data Linker) и, в случае, если данные с именем fname (upshifted & deblanked) найдены, пересылает их в dx,dy VRAM. В противном случае xtova2() пытается загрузить файл с именем fname с диска. Эта функция "понимает" компрессированый формат данных. xtova2() возвращает ОК (0) или номер ошибки для errmsg(), если ошибка имела место при чтении информации с диска. SUBROM не используется. ----- COPY с абсолютной адресацией dy/sy (0~1024 или 0~512) ------------- vtov(sx,sy,dx,dy,width,height,dir,lop) unsigned sx,sy,dx,dy,width,height; char dir,lop; Пересылка из sx,sy VRAM в dx,dy VRAM прямоугольного блока размером width,height. Направление пересылки - dir, логическая операция - lop (см. dtov()). Используется SUBROM. vtovb(sx,sy,dx,dy,width,height,dir) unsigned sx,sy,dx,dy,width,height; char dir; Высокоскоростная пересылка без логических операций из sx,sy VRAM в dx,dy VRAM прямоугольного блока размером width,height. Направление пересылки - dir (см. dtov()). Горизонтальный размер и начало блока автоматически выравниваются на границу БАЙТА (не точки!). SUBROM не используется. rtov(sadr,dx,dy,dir,lop) unsigned sadr,dx,dy; char dir,lop; Пересылка блока, имеющего заголовок ширины и высоты из RAM в dx,dy VRAM. Направление пересылки - dir, логическая операция - lop (см. dtov()). Используется SUBROM. vtor(sx,sy,width,height,radr,dir) unsigned sx,sy,dx,dy,width,heigth,radr; char dir; Пересылка блока из sx,sy VRAM в RAM по адресу radr размерами width,height. Направление пересылки - dir. Используется SUBROM. ----- COPY с адресацией dy/sy внутри активной страницы (0~256) ---------- vtova(sx,sy,dx,dy,width,height,dir,lop) unsigned sx,sy,dx,dy,width,height; char dir,lop; Пересылка из sx,sy VRAM в dx,dy VRAM прямоугольного блока размером width,height. Направление пересылки - dir, логическая операция - lop (см. dtov()). Используется SUBROM. rtova(sadr,dx,dy,dir,lop) unsigned sadr,dx,dy; char dir,lop; Пересылка блока, имеющего заголовок ширины и высоты из RAM в dx,dy VRAM. Направление пересылки - dir, логическая операция - lop (см. dtov()). Используется SUBROM. ----- COPY с прямой адресацией RAM и VRAM ------------------------------- rtovlow(radr,vadr,len) unsigned radr,vadr,len; Пересылка len байт из RAM в нижние 64 Кбайт VRAM. SUBROM не используется. rtovhi(radr,vadr,len) unsigned radr,vadr,len; Пересылка len байт из RAM в верхние 64 Кбайт VRAM. SUBROM не используется. vtorlow(vadr,radr,len) unsigned vadr,radr,len; Пересылка len байт из нижних 64 Кбайт VRAM в RAM. SUBROM не используется. vtorhi(vadr,radr,len) unsigned vadr,radr,len; Пересылка len байт из верхних 64 Кбайт VRAM в RAM. SUBROM не используется. Раздел Библиотеки GRPLIB3 ========================= ----- ФУНКЦИИ РИСОВАНИЯ ДЛЯ MSX2 (Screen 5~8) --------------------------- pset(x,y,cl) int x,y; char cl; Рисовать точку с координатами x,y на активной странице цветом cl. char point(x,y) int x,y; Получить цвет точки с координатами x,y на активной странице. line(x1,y1,x2,y2,cl,lop) int x1,y1,x2,y2; char cl,lop; Рисовать линию с координатами x1,y1 - x2,y2 на активной странице цветом cl с логической операцией lop. box(x1,y1,x2,y2,cl,lop) int x1,y1,x2,y2; char cl,lop; Рисовать прямоугольник с координатами x1,y1 - x2,y2 на активной странице цветом cl с логической операцией lop. boxf(x1,y1,x2,y2,cl,lop) int x1,y1,x2,y2; char cl,lop; Рисовать закрашеный прямоугольник с координатами x1,y1 - x2,y2 на активной странице цветом cl с логической операцией lop. ----- ВЫВОД СИМВОЛОВ НА ГРАФИЧЕСКИЙ ЭКРАН MSX2 (Screen 5~8) ------------- pstep(px,py) int px,py; Задать горизонтальный/вертикальный шаг (расстояние в точках) для вывода символов на графический экран (по умолчанию 8,8). gputch(x,y,fcl,bcl,c) int x,y,fcl,bcl; char c; Вывести символ 'c' цветом fcl на графический экран с координатами x,y, предварительно нарисовав под ним закрашеный прямоугольник цветом bcl. Прямоугольник может быть невидимым, если для него используется цвет (палитра) 0 - это применимо также для всех остальных функций вывода строк на графический экран. Функция gputch() не распознает символ перевода строки '\n'. gputs(x,y,fcl,bcl,str) int x,y,fcl,bcl; char *str; Вывести строку str цветом fcl на графический экран с координатами x,y предварительно рисуя под каждым символом закрашеный прямоугольник цветом bcl. Прямоугольник может быть невидимым, если для него используется цвет (палитра) 0. Функция gputs() не распознает символ перевода строки '\n'. gputs6(x,y,fcl,bcl,str) int x,y,fcl,bcl; char *str; Вывести строку str цветом fcl на графический экран с координатами x,y предварительно рисуя под каждым символом закрашеный прямоугольник цветом bcl. Прямоугольник может быть невидимым, если для него используется цвет (палитра) 0. Все символы выводятся с шагом 6 точек по горизонтали независимо от того, какие значения были заданы при помощи pstep() и не изменяя этих значений. Это удобно при многозадачном использовании, так как ресурсы px,py pstep() являются общими для всех задач. Функция gputs6() не распознает символ перевода строки '\n'. gprintf(x,y,fcl,bcl,format,arg1,...,argN) int x,y,fcl,bcl; char *format; Форматированный вывод на графический экран (см. printf() Л.Зольмана для детального описания всех форматов вывода данных). По символу перевода строки '\n' выполняется стандартная операция CR LF при которой 'x' устанавливается в 0, а y+=py (см. pstep()). gdump(x,y,fcl,bcl,start_adr,end_adr) int x,y,fcl,bcl; unsigned start_adr,end_adr; Шестнадцатеричный dump памяти на графический экран начиная со start_adr и кончая end_adr. char *sprintf(buf,format,arg1,...,argN) char *buf,*format; То же самое, что и обычный sprintf() Л.Зольмана, но возвращает указатель на buf для вложенного использования в других функциях. !!!ПЕРЕОПРЕДЕЛЕНИЕ!!! char *fmt(format,arg1,...,argN) char *format; Функция аналогичная sprintf(), но использующая системный буфер _pbuf[32] для форматирования строк. Удобна для компактной записи таких операторов как putstrt(y,x,fmt("%d",n)); Если вы ограничены по объёму памяти External и не планируете использовать эту функцию, то можете написать #define NO_PBUF перед #include grpmsx1.h или #include grplib0.h char *trt(str) char *str; Перекодировка строки с использованием таблицы _trtab1 длиной 256 байт. /эта же таблица используется в функции putstrt()/ Функция возвращает указатель на переданную ей строку str. Пример использования: trt(fmt("",vars)); ----- ТЕКСТОВЫЕ ФУНКЦИИ ДЛЯ SCREEN 0 (X: 1~80, Y: 1~24) ----------------- char posx() Возвратить текущую X-координату текстового курсора. char posy() Возвратить текущую Y-координату текстового курсора. locate(tx,ty) char tx,ty; Поместить текстовой курсор в позицию tx (1~80), ty (1~24). putsxy(tx,ty,str) char tx,ty,*str; Вывести строку str непосредственно в VRAM с координатами tx (1~80), ty (1~24). Внимание! Позиция текстового курсора не изменяется! char getchrv(tx,ty) char tx,ty; Возвратить код символа, находящегося на экране в позиции tx (1~80), ty (1~24). Внимание! Позиция текстового курсора не изменяется! putchrv(tx,ty,c) char tx,ty,c; Поместить символ непосредственно в VRAM в позицию экрана tx (1~80), ty (1~24). Внимание! Позиция текстового курсора не изменяется! char inline(tx,ty,len,buf) char tx,ty,len,*buf; Вводить не более len символов с клавиатуры компьютера с отображением их на экране начиная с позиции tx (1~80), ty (1~24) и записью в buf. Завершающие ввод пробелы (если присутствуют) усекаются в buf, размер которого должен быть как минимум len+1 для записи завершающего строку двоичного нуля. Нажатие CR - признак конца ввода. Возвращает длину строки в buf. Нажатие клавиш ESC или STOP приводит к прекращению ожидания ввода с клавиатуры с возвратом длины 0. Внимание! Позиция текстового курсора не изменяется! clrtxt() Очистить текстовой экран. dline(lnum) char lnum; Удалить на экране строку lnum (1~24). iline(lnum) char lnum; Вставить на экране строку lnum (1~24). ----- ФУНКЦИИ ДЛЯ РАБОТЫ С ОКОННЫМИ МЕНЮ В SCREEN 5~8 ------------------- paletwin(fg,bg) char fg,bg; Установить цвета (палитры) переднего и заднего плана для оконных меню. По умолчанию 7,8. char swpaletw() Обменять (swap) текущие палитры переднего и заднего плана для оконных меню. Вернуть палитру переднего плана. char windsel(x,y,head,alt1,...,alt23) unsigned x,y; char *head,*alt1,...,*alt23; Открыть оконное меню на активной странице VRAM (временно назначив активную страницу на страницу, показываемую на экране) и возвратить номер выбранной оператором альтернативы alt1,...,alt23. Возвратить RESUME (1) без ожидания выбора альтернативы в случае, если присутствует только один заголовок меню (header) или заголовок и только одна альтернатива (alt1). Меню управляется мышью из порта 1 или 2 или клавишами курсора, если мышь не подключена к компьютеру (распознается автоматически). В случае использования клавиш курсора, клавиша ПРОБЕЛ выполняет функцию левой кнопки мыши (DO), а ESC - правой (UNDO). Если нажата клавиша UNDO, windsel() возвращает значение UNDO (255). Во время ожидания ответа оператора эта функция вызывает totick() для нормального выполнения параллельных процессов и может быть абортирована при помощи ABANDONWINDOW (см.выше) - в этом случае windsel() возвращает значение ABORT (0). Внимание! Для нормального выполнения параллельных процессов рекомендуется вызывать windsel() из главной программы или из process0(). rewindow(mother_page) char mother_page; Восстановить область на активной странице, затертую группой последовательно выведенных оконных меню, используя материнскую страницу mother_page (0~3) с эталоном изображения. Это возможно, так как все последовательно выводимые оконные меню накапливают граничные координаты используемых ими областей экрана до тех пор, пока rewindow() не сбросит их в ноль. ----- ОПРОС СПЕЦИАЛЬНЫХ КЛАВИШ КЛАВИАТУРЫ ------------------------------- char isesc() - Возвращает TRUE, если нажатa клавиша ESC char istab() - Возвращает TRUE, если нажатa клавиша TAB char isctrl() - Возвращает TRUE, если нажатa клавиша CTRL char isshift() - Возвращает TRUE, если нажатa клавиша SHIFT char iscaps() - Возвращает TRUE, если нажатa клавиша CAPS char isgraph() - Возвращает TRUE, если нажатa клавиша GRAPH char isspbar() - Возвращает TRUE, если нажатa клавиша SPACE (ПРОБЕЛ) char iscode() - Возвращает TRUE, если нажатa клавиша CODE (РУС) char isselect() - Возвращает TRUE, если нажатa клавиша SELECT char isstop() - Возвращает TRUE, если нажатa клавиша STOP char ishome() - Возвращает TRUE, если нажатa клавиша HOME (CLS) char isins() - Возвращает TRUE, если нажатa клавиша INS char isdel() - Возвращает TRUE, если нажатa клавиша DEL char isf1() - Возвращает TRUE, если нажатa клавиша F1 (F6) char isf2() - Возвращает TRUE, если нажатa клавиша F2 (F7) char isf3() - Возвращает TRUE, если нажатa клавиша F3 (F8) char isf4() - Возвращает TRUE, если нажатa клавиша F4 (F9) char isf5() - Возвращает TRUE, если нажатa клавиша F5 (F10) char isfunkey() - Возвращает TRUE, если нажатa любая из клавиш F1~F5 char isleft() - Возвращает TRUE, если нажатa клавиша курсора "влево" char isright() - Возвращает TRUE, если нажатa клавиша курсора "вправо" char isup() - Возвращает TRUE, если нажатa клавиша курсора "вверх" char isdown() - Возвращает TRUE, если нажатa клавиша курсора "вниз" char iscursor() - Возвращает TRUE, если нажатa любая клавиша курсора char ismouse1() - Возвращает TRUE, если мышь подключена к порту 1 char ismouse2() - Возвращает TRUE, если мышь подключена к порту 2 char ismouse(mp) - Возвращает TRUE, если мышь подключена к порту mp char istrig(tn) - Возвращает TRUE, если нажат триггер tn char isdclick(tn) - Возвращает TRUE, если триггер tn нажат дважды fretrig(tn) Ждать отпускания триггра tn char iscr() - Возвращает TRUE, если нажатa клавиша CR (возврат каретки) char isbs() - Возвращает TRUE, если нажатa клавиша BS Раздел Библиотеки GRPLIB4 ========================= ----- СПРАЙТЫ ----------------------------------------------------------- lsphex(patnum,hexstr) char patnum,*hexstr; Записать в VRAM Sprite Generator Table начиная со спрайта patnum конфигурацию спрайта (спрайтов), заданую литеральной строкой с шестнадцатеричными цифрами (аналогично inith()). Несколько подряд идущих спрайтов могут быть инициализированы за одно выполнение lsphex(). lsphex8(patnum,hexstr1,...,hexstr8) char patnum,*hexstr1,...,*hexstr8; То же самое, что lsphex(), но, для удобства, слишком длинная литеральная строка может быть разбита на максимум 8 более коротких строк. Если общее количество таких строк меньше 8 - последняя строка должна быть пустой: "". lspmem(patnum,sadr,eadr) char patnum; unsigned sadr,eadr; Записать в VRAM Sprite Generator Table начиная со спрайта patnum конфигурацию спрайта (спрайтов), заданную в RAM начиная с адреса sadr и кончая адресом eadr. Ограничения на длину записываемых данных отсутствуют. char getpat(patnum,buf) char patnum,*buf; Переписать конфигурацию спрайта patnum из VRAM Sprite Generator Table в buf (8 или 32 байта в зависимости от размеров спрайтов). lschex(planenum,hexstr) char planenum,*hexstr; ----- ТОЛЬКО ДЛЯ SCREEN 4~8 MSX2 ----- Загрузить цвет спрайта (построчную окраску, 16 байт), ассоциированный с планом спрайта planenum из литеральной строки с шестнадцатеричными цифрами (аналогично inith()). Несколько подряд идущих планов спрайтов могут быть инициализированы за одно выполнение lschex(). Каждый из 16 байт имеет следующую структуру: { EC CC IC 0 } lschex8(planenum,hexstr1,...,hexstr8) char planenum,*hexstr1,...,*hexstr8; ----- ТОЛЬКО ДЛЯ SCREEN 4~8 MSX2 ----- Используется аналогично lsphex8(). lscmem(planenum,sadr,eadr) char planenum; unsigned sadr,eadr; ----- ТОЛЬКО ДЛЯ SCREEN 4~8 MSX2 ----- Загрузить цвета планов спрайтoв начиная с planenum из RAM с адресов sadr по eadr. Ограничения на длину записываемых данных отсутствуют. char getcol(planenum,buf) char planenum,*buf; ----- ТОЛЬКО ДЛЯ SCREEN 4~8 MSX2 ----- Переписать цвет плана спрайта planenum в buf (16 байт) и вернуть количество значащих байт (8 или 16) в зависимости от размера спрайтов. sprite(planenum,patnum1,x1,y1,patnum2,x2,y2,...,patnumN,xN,yN) char planenum,patnum1,x1,y1,patnum2,x2,y2,...,patnumN,xN,yN; Ассоциировать группу последовательно идущих планов спрайтов начиная с planenum со спрайт-паттернами patnum1~patnumN и вывести их на экран соответсвенно в позициях (x1,y1)...(xN,yN) одновременно. Если очередной patnum (исключая первый) равен нулю - считается что список параметров функции исчерпан (это функция с переменным числом параметров). При выводе спрайтов на экран автоматически производится коррекция координаты Y каждого плана спрайта на -1 (компенсация неудачного решения в VDP). Функция sprite() применима как к MSX1, так и к MSX2. Координаты спрайтов всегда находятся в диапазоне 0~255 (в том числе и для Screen 6,7 - см. V9938). ----- ДОСТУП К ОГЛАВЛЕНИЮ ДИСКА ----------------------------------------- char diskdir(dirmask,buf1700) char *dirmask,*buf1700; Поместить оглавление диска в buf1700 (длиной 1700 байт). Каждая точка входа, полученая при помощи diskdir(), имеет длину 15 байт и следующую структуру: d:ffffffff.sss\0 diskdir() возвращает количество точек входа, помещенных в buf1700, и релевантных dirmask. dirmask является символической строкой (оканчивающейся двоичным нулем) в стандартной нотации MSXDOS: [drive:]filename[.suffix]\0 которая может включать в себя символы '*' и '?', а также дополнительный символ '!' ([AND] NOT). Примеры: "*.com!ab*.com!cde.com" означает все COM-файлы кроме начинающихся с "ab" и "cde". "!*.c" означает все файлы, кроме имеющих суффикс ".c" Пустая строка dirmask ("") эквивалентна "*.*". sortdir(buf1700,n_entry) char *buf1700,n_entry; Сортировать n_entry точек входа в оглавление buf1700, полученых после выполнения diskdir(). Сортировка производится в полуинверсной форме: "d:sss.ffffffff". Результат сортировки записывается в тот же буфер в нормальной форме "d:ffffffff.sss". вы можете использовать функцию qsort() Л.Зольмана для сортировки точек входа обычным образом. ----- ДОПОЛНИТЕЛЬНЫЕ ВОЗМОЖНОСТИ ---------------------------------------- unsigned blockmem(blksize) unsigned blksize; Получить количество блоков памяти размером blksize (без выделения этой памяти), которое в текущий момент можно разместить в RAM при помощи alloc() или sbrk(). Внимание! Функция alloc() Л.Зольмана /в отличие от sbrk()/ не может выделять память блоками более 32 Kбайт - это связано с тем, что одна из переменных в alloc() описана как int вместо unsigned. Это ЕДИНСТВЕННАЯ ошибка(?), которую автор Библиотеки обнаружил в BDS C v1.50a Лео Зольмана за более чем три года интенсивной эксплуатации этой системы. Здесь же отметим, что ошибочная ситуация со стеком при автоматическом вызове cc2.com из cc.com порождена отличием MSXDOS 1.03 от CP/M, а не ошибкой Л.Зольмана. Это отличие компенсировано автором Библиотеки небольшим изменением кода cc.com (вместе с добавлением обнуления счетчиков времени для утитлиты DURATION.COM). Измененную версию cc.com можно идентифицировать по номеру версии, выводимому на экран во время выполнения cc.com (v1.50aR вместо v1.50a). hcopy0(firstlin,lastlin) char firstlin,lastlin; Копировать на принер экран начиная со строки firstlin (1~24) и кончая строкой lastlin (1~24) для Screen 0. hcopy2() Копировать на MSX-принтер весь экран для Screen 2. lprint(adr,count) unsigned adr; char count; Вывести на принтер count байт начиная с адреса adr непосредственно через MSXDOS (не используя lprintf() Л.Зольмана). Эту функцию, в том числе, удобно использовать для посылки кодов управления принтером. lprint2(adr,count) unsigned adr; char count; То же самое, что и lprint(), но все знаки табуляции заменяются на соответсвующее (вычисляемое) число пробелов не более 8. lprintf2(format,args...) То же самое, что и lprintf() Л.Зольмана, но все знаки табуляции заменяются на соответсвующее (вычисляемое) число пробелов не более 8. unsigned ltape(mode,adr,count) char mode; unsigned adr,count; Загрузить не более count байтов данных с магнитной ленты размещая их в RAM начиная с адреса adr. Загрузка может быть прервана по нажатию CTRL STOP или из-за ошибки считывания с магнитной ленты. Мотор включается и выключается автоматически. Возвращается остаточный счетчик. Работает в режиме DI. Значения для mode: 0 - читать любой тип данных - остановка по счетчику; 1 - CLOAD - остановка по семи подряд идущим нулям или по счетчику; 2 - BLOAD - вычислить значение счетчика исходя из первых 4 байт данных, считаных с ленты: start (2 байта), end (2 байта). unsigned dtape(mode,adr,count) char mode; unsigned adr,count; Записать на магнитную ленту count байтов данных начиная с адреса adr. Загрузка может быть прервана по нажатию CTRL STOP. Мотор включается и выключается автоматически. Возвращается остаточный счетчик (не 0, если запись была прервана при помощи CTRL STOP). Работает в режиме DI. Значения для mode: 0 - требуется короткий заголовок (пилот-сигнал) 1 - требуется длинный заголовок (пилот-сигнал) wpsg(reg,byte) char reg,byte; Записать byte в регистр reg Программируемого Звукового Генератора (PSG). char rpsg(reg) char reg; Читать байт из регистра reg PSG. sndreset() Сброс PSG в начальное состояние. sound(r0,...r13,ctrl,waveform,modstep,modwidth,chanconfig,duration) int r0,...r13,ctrl; char waveform,modstep,modwidth,chanconfig; unsigned duration; Генерировать звук при помощи PSG и программного Extra LFO для частотной модуляции звука. Значения r0~r13 загружаются в соответствующие регистры PSG (отрицательные значения игнорируются). Если ctrl не равен нулю, то используется Extra LFO для каналов PSG, определяемых байтом chancofig: 0000 ABCN |||| |||+-- 1: модулировать шум ||+--- 1: модулировать канал C |+---- 1: модулировать канал B +----- 1: модулировать канал А При этом: waveform: 0 или 1 (форма волны) modstep: 0~255 (шаг девиации частоты) modwidth: 0~255 (ширина девиации частоты) duration: 1~0xFFFF (длительность в "тиках" таймера) Функцией sound() автоматически вызывается totick() для обеспечения возможности параллельного выполнения других процессов во время генерации звуков, имеющих большую длительность (duration). Примечание. Для упрощения разработки и создания новых звуковых эффектов автором разработана утилита PSG Extra Editor, которая позволяет создавать звуки в режиме полноэкранного редактирования всех параметров функции sound() и сохранять/загружать банки звуков в виде ASCII-файлов, содержащих готовые к вставке в программу операторы sound(). Эта утилита не входит в состав ПС "МАЭСТРО" и может поставляться в дальнейшем по отдельному заказу. sound1(str) char *str; Альтернативная версия функции sound() для управления только каналом #1 (А) PSG. Эту функцию удобно использовать для создания отдельных звуковых эффектов в канале #1 во время исполнения какой-либо музыки, разработанной с использованием ПС "МЕДИА" для системной музыкальной очереди MSX. Кроме этого, sound1() является более компактным вариантом функции sound() (как по объему генерируемого кода, так и по данным). Строка str представляет собой последовательность байтов следующего вида: байт: r0 r1 r6 r7 r8 r11 r12 r13 ctrl wf ms mw ch dur смещение: +0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13~14 где: r0~r13 - регистры PSG; ctrl,wf,ms,mw,ch,dur - соответсвенно ctrl, waveform, modstep, modwidth, chanconfig и duration (2 байта) аналогично функции sound(). Примечание 1. Формат записи строки для sound1() также поддерживается утилитой PSG Extra Editor (см. примечание выше). Примечание 2. ПС "МЕДИА" не является компонентой ПС "МАЭСТРО" и разработано другим автором для использования совместно с ПС "МАЭСТРО". ПС "МЕДИА" может быть поставлено по дополнительному заказу и включает в себя интерактивный музыкальный редактор с расширеными средствами музыкального макроязыка MML+, а также специальный раздел Библиотеки функций для работы с данными, порожденными при помощи этого музыкального редактора и музыкальными очередями из программ, написанных на BDS C в рамках ПС "МАЭСТРО". Кроме того, этот раздел библиотеки включает некоторые дополнительные общесистемные функции, не входящие в Библиотеку функций ПС "МАЭСТРО". dump(sadr,eadr) unsigned sadr,eadr; Dump RAM с адреса sadr по адрес eadr на экран для Screen 0. ldump(sadr,eadr) unsigned sadr,eadr; Dump RAM с адреса sadr по адрес eadr на принтер. char rwsector(operation,drive,from_sec,count,buf) char operaiton,drive,count,*buf; unsigned from_sec; Запись и чтение информации с диска по секторам с возвратом системного кода ошибки (если ошибка имела место при выполнении операции). operation: 0 - читать 1 - записывать drive: A:0, B:1, C:2,... from_sec: начиная с сектора from_sec count: количество подряд идущих секторов (0~255) buf: буфер в памяти для данных Возвращает: FF - ОК (успешное окончание) 01 - Write Protect (зашита записи) 02 - Not Ready (не готов) 03 - Seek Error (ошибка подвода головки) 04 - Record Not Found (запись не найдена) 05 - Write Error (ошибка записи) 06 - Other Error (другие ошибки) Примечание. Некоторые ROM, обеспечивающие работу MSX с диском, могут выдавать коды ошибок, несколько отличающиеся от приведенных выше. speech(data_adr,data_len) unsigned data_adr,data_len; Произнести данные, подготовленные при помощи программы "Master Voice" Ван дер Путтена. int swapin2(fname,adr,maxlen) char *fname; unsigned adr,maxlen; Альтернативная версия swapin() Л.Зольмана. Проверяет размер файла на диске перед загрузкой его в память и сравнивает его с maxlen. Возвращает отрицательный размер файла в байтах в случае, если его длина превышает maxlen или ERROR (-1) в случае любой ошибки ввода/вывода. Если файл успешно загружен в память по адресу adr - возвращает длину файла в байтах. int swapout(fname,adr,len) char *fname; unsigned adr,len; Запись данных, находящихся по адресу adr длиной len байт в дисковый файл fname. Возвращает ERROR (-1) в случае любой ошибки создания/записи/закрытия файла (включая переполнение диска). Раздел Библиотеки GRPLIB5 (ТОЛЬКО ДЛЯ MSX1) ========================= ВНИМАНИЕ! Данный раздел библиотеки опирается на терминологию, используемую в программе Pattern Composer. Для ознакомления с ней рекомедуется изучить документ "Компоновщик/Редактор знакоместной графики" - описание применения. Кроме этого, рекомендуется ознакомиться с описанием утилиты Extra Data Linker и библиотечной функцией geteda2(). gameini(MNTfile,screensX,screensY,LIBfile,SPRfile,sprsize,magn,mode) char *MNTfile,*LIBfile,*SPRfile,screensX,screensY,sprsize,magn,mode; Назначение: стандартная инициализация игровой программы. Распределение RAM для MNT (Multi-screen Name Table) при помощи sbrk(), установка Screen 2, заполнение Name Table экрана нулями, установка параметров gwindow (графического окна) по максимальному размеру экрана 30х22, загрузка таблицы перекодировки для стандартного расположения алфавитно-цифровых паттернов в библиотеке и загрузка файлов MNT, LIB и SPR в абсолютном некомпрессированом формате с диска, если не найдены соответсвующие компрессированые файлы с ТЕМИ ЖЕ ИМЕНАМИ. Файлы LIB и SPR могут быть прикомпонованы к концу области External (-f), а MNT - к концу кода (-c). Файлы LIB и SPR переписываются непосредственно в VRAM и могут более не перезагружаться, а MNT загружается с диска или расширяется из компрессированого формата в область, предварительно зарезервированную при помощи sbrk() после того, как файлы LIB и SPR уже переписаны в VRAM. Если вместо SPR-файла написан 0 - соответсвующая область VRAM для спрайтов заполняется из файла LIB с рекомпозицией формата LIB в SPR (16х16). Параметры: screenX, screenY - размеры MNT. Должны совпадать с размерами, указанными при создании и сохранении MNT при помощи PAC - в противном случае диагностируется ошибка. sprsize - SIZE_8 или SIZE_16. magn - MAGNIFIED или UNMAGNIFIED mode - SINGLE or SIMULTANEOUS. Последние три параметра аналогичны параметрам функции sprctl(). Внутри функции gameini() производится автоматический вызов grpini(), lodlib(), lodmnt() и др. gameini2(screensX,screensY,sprsize,magn,mode) char screensX,screensY,sprsize,magn,mode; Назначение: то же самое, что и gameini(), но данная функция НЕ ЗАГРУЖАЕТ файлы LIB, SPR и MNT. вы должны сами вызывать функции lodlib() и lodmnt() (см.ниже) в явном виде. Это дает возможность компрессировать/не компрессировать (по Вашему усмотрению) данные в файлах, присваивать компрессированым файлам имена, отличные от некомпрессированых файлов, перезагружать эти файлы перед началом каждого повторяющегося исполнения Вашей программы и пр. Кроме того, это дает Вам возможность по-разному прикомпоновывать LIB, SPR и MNT файлы в зависимости от организации Вашей программы. Примечание. Автором обычно используется следующее правило для размещения и прикомпоновки различных данных: - данные, которые перемещаются в VRAM и в дальнейшем не не подвергаются там модификации, прикомпоновываются к концу области External ('-f' EDL) с тем, чтобы после загрузки их в VRAM, эта область памяти освобождалась для размещения рабочих областей, переменыых и пр. - данные, которые могут подвергаться модификации, прикомпоновываются к концу кода (до начала области External) в компрессированом или некомпрессированом формате и экспандируются/переписываются в рабочую область RAM (в том числе в те адреса, которые освободились после загрузки данных, прикомпонованых с '-f', в VRAM) перед началом каждого повторяющегося выполнения программы. clrscr(SCRline,SCRcolumn,width,height) char SCRline,SCRcolumn,width,height; Очистить прямоугольный участок экрана в Scrеen 2 с координатой левого верхнего угла SCRline (0~23 по Y) и SCRcolumn (0~31 по X), шириной width (1~32) и высотой height (1~24), заполнив соответсвующие байты Name Table экрана нулями. gopen(libbase,framtop,framleft,framwidth,framheight) char libbase,framtop,framleft,framwidth,framheight; Открыть Graphic Window (Графическое Окно): нарисовать рамку, очистить содержимое и запомнить координаты окна в системной рабочей области для использования их в дальнейшем функцией gwind(). libbase является номером паттерна в библиотеке знакомест (0~249), начиная с которого располагаются 6 паттернов рамки: 4 паттерна для углов, горизонтальная линия и вертикальная линия. Если Вы используете стандартную библиотеку знакомест, то можете указывать в качестве libbase ключевые слова STD_RED и STD_BLUE. Параметры framtop и framleft задают координаты верхнего левого угла рамки, а framwidth и framheight - ее ширину и высоту. topen(libbase,framtop,framleft,framwidth,framheight) char libbase,framtop,framleft,framwidth,framheight; Открыть Text Window (Текстовое Окно со скроллингом текста) для использования функции tprintf(). Параметры аналогичны параметрам gopen(). gdef(windline,windcolumn,windwidth,windheight) char windline,windcolumn,windwidth,windheight; Определить параметры Graphic Window, но не рисовать рамку и не очищать содержимое окна. Используется внутри gopen(). tdef(windline,windcolumn,windwidth,windheight) char windline,windcolumn,windwidth,windheight; Определить параметры Text Window, но не рисовать рамку и не очищать содержимое окна. Используется внутри topen(). gframe(libbase) char libbase; Нарисовать/перерисовать рамку с очисткой окна для уже открытого или определенного графического окна. unsigned absntab(y,x) unsigned y,x; Получить абсолютный адрес внутри VRAM Name Table по двум координатам экрана y (0~23) и x (0~31). unsigned absptab(y,x) unsigned y,x; Получить абсолютный адрес внутри первого из трех VRAM Pattern Generator Table по двум координатам паттерна y (0~7) и x (0~32) unsigned absctab(y,x) unsigned y,x; Получить абсолютный адрес внутри первого из трех VRAM Colour Table по двум координатам паттерна y (0~7) и x (0~32) char *absmntab(y,x) unsigned y,x; Получить абсолютный адрес внутри MNT по координатам y и x. Максимальные значения этих координат зависят от конфигурации и размеров MNT. lodlib(LIB_link,SPR_link,base,LIB_file,SPR_file) char *LIB_file,*SPR_file,*LIB_link,*SPR_link; unsigned base; Экспандировать и загрузить прикомпонованые и компрессированые LIB и SPR файлы в VRAM: LIB_link и SPR_link - имена этих файлов, base - codend() для '-c' endext() для '-f' 0, если Extra Data не используется (в этом случае не производится попытки найти LIB_link и SPR_link) Если LIB_link или SPR_link не найдены в Extra Data, производится попытка загрузки с диска НЕКОМПРЕССИРОВАНЫХ файлов LIB_file и SPR_file (с диагностикой соответствующих ошибок ввода/вывода). Если вместо SPR_link или SPR_file написан 0 - в качестве данных для Sprite Generator Table используется LIB_link или LIB_file с соответствующей рекомпозицией паттернов к размеру спрайтов 16х16. lodlib2(LIB_link,SPR_link,base) char *LIB_file,*SPR_file; unsigned base; Сокращённая версия lodlib() без загрузки файлов с диска. Экспандировать прикомпонованые и компрессированые LIB и SPR файлы в VRAM: LIB_link и SPR_link - имена этих файлов, base - codend() для '-c' endext() для '-f' Если вместо SPR_link написан 0 - в качестве данных для Sprite Generator Table используются данные из LIB_link с соответствующей рекомпозицией паттернов к размеру спрайтов 16х16. lodmnt(MNT_link,base,MNT_file) char *MNT_link,*MNT_file; unsigned base; Экспандировать и загрузить прикомпонованый и компрессированый файл MNT (в абсолютном формате - F7) в RAM /предварительно выделенный при помощи gameini() или gameini2()/. base используется аналогично lodlib(). Если base равно нулю или файл MNT_link не найден в Extra Data - производится загрузка НЕКОМПРЕССИРОВАНОГО файла MNT_file с диска. После этого загружается стандартная таблица перекодировки. bwind(MNTline,MNTcolumn,framtop,frambottom) unsigned MNTline,MNTcolumn; char framtop,frambottom; Block Winlow: вывести блок из MNT с координатами верхнего левого угла MNTline (Y), MNTcolumn (X) на экран начиная со строки экрана framtop (верхняя строка) и кончая строкой экрана frambottom (нижняя строка). Ширина блока: всегда 32 знакоместа. Для данного типа окна не предусмотрены операции OPEN/DEFINE и рамка. Этот тип окна имеет максиммальную скорость отображения данных из MNT на физический экран. gwind(MNTline,MNTcolumn) unsigned MNTline,MNTcolumn; Graphic Window: вывести блок из MNT с координатами верхнего левого угла MNTline (Y), MNTcolumn (X) на экран в область, предварительно определенную при помощи gopen() или gdef(). swind(MNTline,MNTcolumn,SCRline,SCRcolumn,width,height) unsigned MNTline,MNTcolumn; char SCRline,SCRcolumn,height,width; Sub-Window: вывести блок из MNT с координатами верхнего левого угла MNTline (Y), MNTcolumn (X) на экран в область с координатами верхнего левого угла SCRline (0~23 по Y), SCRcolumn (0~31 по X). Ширина и высота выводимого блока: width (1~32) и height (1~24). Для данного типа окна не предусмотрены операции OPEN/DEFINE. Рамка может быть специально нарисована при помощи sframe() (см.ниже). sframe(libbase,SCRline,SCRcolumn,width,height) char libbase,SCRline,SCRcolumn,width,height; Нарисовать рамку и очистить область внутри нее нулями. Параметры аналогичны параметрам gopen(). putchr(SCRline,SCRcolumn,c) char SCRline,SCRcolumn,c; Вывести символ 'c' на экран (непосредственно в VRAM Name Table) без перекодировки в позиции SCRline (0~23) и SCRcolumn(0~31). char getchr(SCRline,SCRcolumn) char SCRline,SCRcolumn; Взять символ (байт) с экрана (непосредственно из VRAM Name Table) находящийся в позиции SCRline (0~23) и SCRcolumn(0~31). putstr(SCRline,SCRcolumn,str,len) char SCRline,SCRcolumn,*str,len; Вывести строку str длиной len на экран без перекодировки в позиции SCRline (0~23) и SCRcolumn(0~31). putstrt(SCRline,SCRcolumn,str) unsigned SCRline,SCRcolumn; char *str; То же самое, что putstr(), но строка автоматически перекодируется перед выводом на экран с использованием стандартной таблицы перекодировки и должна оканчиваться двоичным нулем. Внимание! Компилятор BDS C гасит старший бит во всех литеральных строках и, поэтому, буквы кириллического алфавита не будут сохраняться в генерируемом коде (они будут транслитерированы в латинские). Для решения этой проблемы без модификации компилятора рекомендуются следующие приемы: 1. Хранить все русско-язычные сообщения в MNT и выводить их на экран при помощи putstr() или swind(). 2. Хранить все русско-язычные сообщения в отдельном ASCII файле, подготовленом при помощи текстового редактора, и, перед выполнением программы, загружать его в память. После этого может быть использована функция putstrt(). 3. Записывать все кириллические символы внутри литеральных строк программы при помощи восьмеричных констант. Для этий цели можно воспользоваться утилитой DUMP.COM, входящей в состав ПС "МАЭСТРО". Следует заметить, что первые два приема являются наиболее предпочтительными и при использовании любых других компиляторов, в том числе, не подавляющих кириллические символы. Это свзано с тем, что таким образом обеспечивается дополнительная независмость программы от данных и свобода в изменении диалога, ведущегося программой (в том числе, перевод его на другой язык) без изменения и перекомпиляции самой программы. tframe(libbase) char libbase; Нарисовать/перерисовать рамку с очисткой окна для уже открытого или определенного при помощи topen()/tdef() текстового окна. tprintf(format) char *format; Форматированый вывод в предварительно открытое или определенное текстовое окно с перекодировкой. Параметры - такие же как у функции printf() Л.Зольмана. Внутри окна производится локальный скроллинг текста. sprite1(baseplan,PAT1,x1,y1,col1,...,PAT4,x4,y4,col4) char baseplan,PAT1,PAT2,PAT3,PAT4,x1,y1,x2,y2,x3,y3,x4,y4,col1,col2,col3,col4; Функция, аналогичная sprite() (см.выше), но имеющая прямое управление цветом спрайта (MSX1) и выводящая не более 4-х спрайтов одновременно. В случае, если используется менее 4-х спрайтов - записывается 0 вместо PAT2~PAT4 после цвета последнего использованного спрайта. sprcol1(plane,colr) char plane,colr; Изменить цвет плана спрайта. prtscrnt() Вывести на принтер шестнадцатеричный dump всей текущей Name Table (для отладки). stornt(SCRline,SCRcolumn,width,height,buf) char SCRline,SCRcolumn,width,height,*buf; Сохранить блок с экрана (из VRAM Name Table) в RAM для последующего восстановления при помощи restnt() или restnt2(). Размер буфера buf для сохранения блока должен быть не меньше произведения размеров блока width на height. restnt(SCRline,SCRcolumn,width,height,buf) char SCRline,SCRcolumn,width,height,*buf; Восстановить блок, сохраненный при помощи stornt(), на экране (в VRAM Name Table). Первой восстанавливается верхняя строка блока. Параметры аналогичны параметрам stornt(). restnt2(SCRline,SCRcolumn,width,height,buf) char SCRline,SCRcolumn,width,height,*buf; Восстановить блок, сохраненный при помощи stornt(), на экране (в VRAM Name Table). Первой восстанавливается нижняя строка блока. Параметры аналогичны параметрам stornt(). char getchrm(SCRlin,SCRcol,gwbaseY,gwbaseX) char SCRlin,SCRcol; unsigned gwbaseY,gwbaseX; Взять символ из MNT, отраженный на экран при помощи gwind() с координатами левого верхнего угла (gwbaseY,gwbaseX), пользуясь для этого координатами экрана, а не координатами MNT. putchrm(SCRlin,SCRcol,gwbaseY,gwbaseX,c) char SCRlin,SCRcol,c; unsigned gwbaseY,gwbaseX; Поместить символ 'c' в MNT, пользуясь для этого координатами экрана аналогично getchrm(). st_swind(MNTline,MNTcolumn,SCRline,SCRcolumn,width,height,buf) unsigned MNTline,MNTcolumn; char SCRline,SCRcolumn,width,height,*buf; Функция swind() с предварительным сохранением изменяемой части экрана в буфере buf. Комбинация stornt() и swind() (см.выше). Дополнительные макро-функции и некоторые системные переменные общего пользования из заголовка GRPLIB0.H ==================================================== MSX2 системная переменная (устанавливается grpini() при инициализации) TRUE, если Ваш компьютер - MSX2. VRAM_128 системная переменная (устанавливается grpini() при инициализации) TRUE, если у Вашего компьютера 128 Кбайт VRAM. MEMORY_MAPPER системная переменная (устанавливается grpini() при инициализации) TRUE, если у Вашего компьютера есть аппаратура Memory Mapper TEXTWIDTH(width) /* macro */ Установить максимальную ширину текстовой строки width для Screen 0. MOUSE1(x,y) /* macro */ Записать в переменные x,y относительные приращения координат мыши, поключенной к порту 1. MOUSE2(x,y) /* macro */ Записать в переменные x,y относительные приращения координат мыши, поключенной к порту 2. USE_MOUSE(mouse_num) /* macro */ Альтернативный метод опроса мыши: активация специального процесса, вызываемого из totick(). Этот процесс вычисляет абсолютные координаты мыши (0~511 или 0~256 для экранов с низким разрешением) каждый "тик" и помещает их в системные переменные MOUSE_X, MOUSE_Y (абсолютные координаты) и RMOUSE_X, RMOUSE_Y (относительные координаты). Только одна мышь (mouse_num 1 или 2) может опрашиваться этим процессом. UNUSE_MOUSE деактивирует этот процесс (установлен по умолчанию). Этот процесс не зависит от TICKON/TICKOFF и TICKSTART/TICKSTOP. UNUSE_MOUSE /* macro */ Деактивация механизма USE_MOUSE. MOUSE_X системная переменная вы можете написать, например, x=MOUSE_X; для получения абсолютной Х-координаты мыши, если активирован USE_MOUSE, а также присвоить этой переменной значение координаты Х для программного позиционирования курсора MOUSE_X=x; MOUSE_Y системная переменная вы можете написать, например, y=MOUSE_Y; для получения абсолютной Y-координаты, если активирован USE_MOUSE, а также присвоить этой переменной значение координаты Х для программного позиционирования курсора MOUSE_Y=y; RMOUSE_X системная переменная То же самое для относительной X-координаты. RMOUSE_Y системная переменная То же самое для относительной Y-координаты. GETTIME(h,m,s) /* macro */ Записать текущее значение часов, минут и секунд в переменные h, m и s соответственно. GETDATE(y,m,d) /* macro */ Записать текущее значение года, месяца и дня в переменные y, m и d соответственно. DIS_INTERRUPT /* macro */ Выполнить команду Z80 'DI'. ENA_INTERRUPT /* macro */ Выполнить команду Z80 'EI'. DIS_SCREEN /* macro */ Запретить вывод на экран (Disable Screen) ENA_SCREEN /* macro */ Разрешить вывод на экран (Enable Screen) EXIT /* macro */ Выход в MSXDOS с восстановлением Screen 0 и параметров цвета экрана из энерго-независимой памяти MSX2 или GRPMSX1.H MSX1. PAUSE(beep_num) /* macro */ Подача beep_num звуковых сигналов и ожидание нажатия клавиши SHIFT с периодическим обращением к totick(). Используется для отладки программ, работающих с графическими экранами. DUMP(msg,sadr,eadr) /* macro */ char *msg; unsigned sadr,eadr; Выводить на текстовой экран (Screen 0) идентификационное сообщение msg и шестнадцатеричный dump памяти начиная с sadr и кончая eadr. GDUMP(fg,bg,msg,sadr,eadr) /* macro */ char fg,bg,*msg; unsigned sadr,eadr; Выводить на графический экран (Screen 5~8) идентификационное сообщение msg и шестнадцатеричный dump памяти начиная с sadr и кончая eadr. fg и bg - палитры для переднего и заднего плана соответсвенно. Начальная позиция: левый верхний угол экрана. DIR_GET_CHAR /* macro */ DIR_PUT_CHAR /* macro */ Напишите эти две макровызова вне тела главной программы и других функций (это компилируемые переопределения функций getchar() и putchar()) и ВЕСЬ консольный ввод/вывод будет направлен непосредственно через ROM BIOS вместо BDOS - это гарантирует отсутствие проверки на ^C и другие специальные коды (^S, ^P, ...) и, кроме того, несколько быстрее. INKEY /* macro */ Функция, аналогичная inkey$ языка Бейсик. Напишите c=INKEY; и вы получите код символа, введенного с консоли или 0, если ни одна клавиша не была нажата. Эта функция работает через BDOS 6 - нет ожидания, нет проверки на ^C и другие специальные коды, нет отображения символа на экран. VARPARMS(first_arg_in_list) /* macro */ Напишите VARPARMS внутри любой функции сразу после описаний внутренних переменных функции, если таковые имеются, (VARPARMS является выполняемым макросом) и используйте после этого PARM(n) для извлечения параметра функции по его номеру n. (первый параметр имееет номер 0). Пример: main() { foo(1,"txt"); } foo(arglist) unsigned arglist; /* 'arglist' used for argaddr extraction */ { char zot; VARPARMS(arglist) printf("%d %s",PARM(0),PARM(1)); } В результате выполнения данной программы будет напечатано: 1 txt PARM(n) /* macro */ Используется для извлечения параметра функции по номеру n вместе с макросом VARPARMS. Первый параметр в списке имеет номер 0. Номер n может быть переменной. KBDOFF /* macro */ отключить опрос клавиатуры и обработку прерываний в BIOS KBDON /* macro */ включить опрос клавиатуры и обработку прерываний в BIOS KBDRESTORE /* macro */ восстановить опрос клавиатуры и обработку прерываний в BIOS 4. РЕКОМЕНДАЦИИ ПО ИСПОЛЬЗОВАНИЮ И ФОРМАТЫ ДАННЫХ ================================================= 4.1. Внимание! #include grplib0.h или #include grpmsx1.h обязательно должны присутствовать в качестве самой первй строки (не считая комментариев) в Вашей программе, использующей Библиотеку! (bdscio.h вызывается автоматически из grplib0.h). Эти заголовки содержат рабочие области и макроопределения, абсолютно необходимые для нормальной работы функций Библиотеки. 4.2. Одна из функций grpini(), gameini() или gameini2() обязательно должна быть выполнена до обращения к другим функциям Библиотеки. Эти функции инициализируют рабочую область Библиотеки и устанавливают стандартные значения "по умолчанию". 4.3. Имена, начинающиеся с подчеркивания '_' зарезервированы для системного использования. 4.4. Так как некоторые процессы могут пользоваться одними и теми же системными ресурсами (Графический аккумулятор, аккумулятор позиций текстового курсора, шаг печати для графических экранов и др.) - обращайте особое внимание на то, чтобы не использовать значения, которые остаются и сохраняются в таких ресурсах - они могут быть оставлены другим процессом при мультизадачной работе! 4.5. Область External НИКОГДА НЕ ДОЛЖНА НАХОДИТЬСЯ НА СТРАНИЦАХ 0 и 3 (адреса памяти 0~3FFF и C000~FFFF) RAM. Используйте '-e4000' для cc и clink как минимум! Это связано с тем, что механизм работы со слотами и мэппером, реализованый в Библиотеке, находится в External и может работать только в страницах 1 или 2 (в отличие от оригинального механизма MSX ROM BIOS, который работает некорректно и при некоторых межслотовых вызовах сам себя выбрасывает из памяти). 4.6. Если вы хотите вызывать BIOS или SUBROM сами (механизм вызова описан в GRPLIB0.H) - никогда не передавайте в них указатели на данные, которые могут оказаться в странице 0 (например на литеральные строки из текста программы, находящейся в RAM). Это связано с тем, что во время работы BIOS или SUBROM страницу 0 занимает сам ROM (библиотечные функции в подобных случаях предварительно буферизируют данные в стеке). 4.7. Ниже приводится описание "компрессированного" формата данных, который используется в некоторых библиотечных функциях. Компрессия достигается за счет сжатия "однородностей" - одинаковых слов идущих последовательно друг за другом. Алгоритм неадаптивный, т.е. ориентрованый на фиксированную длину слова - в данном случае 1 байт. Компрессированые данные состоят из элементов данных, каждый из которых в свою очередь, состоит из "признака", "счетчика" и "данных". "Признак" занимает один бит и означает компрессию (1) или обычную последовательность данных (0). "Счетчик" занимает 7 бит. "Данные" представляют собой один байт (в случае компрессии) или от 1-го до 127 байт в случае "некомпрессируемой" последовательности байтов. Таким образом, "элементы" могут выглядеть следующим образом: 0-й байт 1-й байт +-----------+-----------+ | 1xxx xxxx | zzzz zzzz | "повторение байта 'zzzz zzzz' +-----------+-----------+ 'xxx xxxx' (0~127) раз" 0-й байт 1-й байт N-й байт +-----------+-----------+ --- +-----------+ | 0xxx xxxx | yyyy yyyy | ... | zzzz zzzz | N (xxx xxxx) байт для +-----------+-----------+ --- +-----------+ "прямого" копирования 0-Й байт +-----------+ | 0000 0000 | "больше нет данных" +-----------+ Изображения в формате COPY (Data) (см.выше) для Screen 5~8 имеют заголовки из двух слов (по 2 байта каждое слово) с указанием ширины и высоты изображения в точках. Для компрессированых изображений ширина (1-е слово) записывается в отрицательном виде, т.е. -ширина. Этот признак используется функциями Библиотеки для автоматического распознавания компрессированого формата изображения. Отрицательная ширина может быть установлена при помощи утилиты Picture Compressor - PICO.COM (поставляется по отдельному заказу - см.выше). Другие данные, не имеющие таких заголовков, могут быть компрессированы или расширены при помощи утилиты Files Compressor/Expander - FCX.COM и библиотечной функции expand(). 4.8. Внимательно ознакомьтесь с файлами GRPLIB0.H и GRPMSX1.H - они содержат много полезной информации и дополнительных ключевых слов для использования в текстах Ваших программ. Будьте осторожны - не переназначайте имена системных переменных! 5. Работа с портами джойстика (2022) ============================= Если вы хотите опрашивать порты джойстика для того чтобы с ними можно было работать одновременно с опросом клавиш курсора, пробела (триггер 1) и клавишей GRAPH (триггер 2), добавьте дополнительный #include в вашу программу: #include grpstick.h В этом случае порты джойстика будут опрашиваться автоматически и добавляться по ИЛИ к нажатиям клавиш на клавиатуре. Вы сможете пользоваться такими функциями, как isspbar(), isleft() и др. без изменения текста вашей программы. При этом, надо учитывать то, что мышь, опрашиваемая как джойстик, может давать постоянные срабатывания кнопок Вправо и Вниз. Для того, чтобы этого избежать можно использовать специальную функцию chkmouse() из grpstick.h которая сама определит по этим признакам подключена ли мышь к порту джойстика и, если она подключена, исключит этот порт из опроса как порт джойстика. Кроме этого, вы можете сами использовать системные переменные _NoMous1 и _NoMous2 для 1-го и 2-го портов соответственно, задавая им значения TRUE или FALSE в явном виде. В этом случае использование функции chkmouse() будет необязательным. По умолчанию grpini() устанавливает _NoMous1=FALSE и _NoMous2=TRUE т.е. считает, что к порту 1 подключена мышь, а к порту 2 джойстик. Если вы хотите чтобы работало автоопределение мыши для обих портов с помощью функции сhkmouse(), то предварительно установите _NoMous1=TRUE. Если вы хотите использовать только джойстик в порте 2 без автоопределения мыши и сократить размер кода, вы можете также написать #define JOY2ONLY перед #include grpstick.h Утилиты ======= АННОТАЦИЯ В данном документе содержится описание применения утилит, входящих в ПС "МАЭСТРО". Документ предназначен для разработчиков программного обеспечения на компьютерах MSX2 и MSX и содержит следующие разделы: "Назначение утилит", "Условия применения", "Порядок работы с утилитами, форматы данных и особенности использования". Все утилиты ПС "МАЭСТРО" являются авторскими разработками А.Б.Родионова (Москва, 1986~1988). Оригинальная документация ведется на английском языке для совместимости с компьютерами и другим оборудованием, не имеющим кириллических знакогенераторов и может быть поставлена по специальному заказу. По этой же причине англоязычными являются все комментарии и диалоги, ведущиеся утилитами, а также другими компонентами ПС "МАЭСТРО". Данный документ не следует рассматривать как учебное пособие по компьютерам MSX2 и MSX - напротив он расчитан на подготовленых программистов, знающих архитектуру этих компьютеров, но испытывающих затруднения в выборе инструментальных средств для разработки своих программ. -------------------------------------------------------------------- ПС "МАЭСТРО" является первым в СССР программным продуктом, обладающим имеющим законную силу Copyright (C) - правом на тиражирование и копирование. -------------------------------------------------------------------- 1. НАЗНАЧЕНИЕ УТИЛИТ BLADE.COM Bload Address Extractor - извлечение адресов из BLOAD/BSAVE файлов. CDEX.COM C Documentation Extractor - извлечение документации из автодокументированых Си-программ. DS.COM Directory Sorter - вывод оглавления диска на экран в отсортированом виде. DT.COM Disk to Tape - перезапись файлов с диска на магнитную ленту. DUMP.COM Dump - дамп/объединение различных источников информации. DURATION.COM Duration - подсчет длительности интервалов времени. EDL.COM Extra Data Linker - прикомпоновка данных к COM-файлам, созданным при помощи BDS C. FCX.COM Files Compressor/Expander - компрессор/экспандер для сжатия/расширения файлов. FICO.COM Files Collector - диалоговый сборщик нескольких файлов в один файл. HC.COM Hardcopy - вывод файлов на принтер. SS.COM Sector Server - копирование/проверка дисков по секторам. TD.COM Tape to Disk - перезапись файлов с магнитной ленты на диск. Все утилиты написаны на языке С (компилятор BDS C) и ассемблер (GEN80) с использованием "Графической Библиотеки MSX для BDS C". 2. УСЛОВИЯ ПРИМЕНЕНИЯ Для работы утилит требуется MSX компьютер с 64 Кбайт оперативной памяти и как минимум одним диск-драйвом. Большинство утилит может выполняться как на MSX1 так и на MSX2. Случаи использования MSX2 оговариваются особо. Операционная система: MSXDOS версии 1.03 (COMMAND.COM 1.11). Внимание! Для нестандартных модификаций операционной системы и консольного процессора нормальная работа утилит не гарантируется. 3. ПОРЯДОК РАБОТЫ С УТИЛИТАМИ, ФОРМАТЫ ДАННЫХ И ОСОБЕННОСТИ ИСПОЛЬЗОВАНИЯ. Ниже приводятся описания параметров командных строк и функций утилит ПС "МАЭСТРО". Примечание. Большинство утилит, не ведущих диалог, выводит краткое описание своих командных строк при вызове их без параметров. Формат записи параметров: в квадратных скобках '[' и ']' записываются необязательные параметры, в фигурных '{' и '}'- альтернативные значения параметров, в угловых '<' и '>'- смысловые значения параметров. Вертикальная черта '|' служит для разделения альтернатив ("или"), многоточие '...' - для указания на группу однотипных параметров. 3.1. УТИЛИТА BLADE.COM ---------------------- Полное название Bload Address Extractor Назначение Извлечение адресов из BLOAD/BSAVE файлов. Формат командной строки blade [] Параметры - любая стандартная маска набора файлов MSXDOS с расширением "!" - [and] not. Если не указан - *.* Особенности Файлы, релевантные маске, сортируются по алфавиту и проверяются на наличие FE в первом байте файла. В случае присутствия FE на экран выводится имя файла и три шестнадцатеричных слова: адрес загрузки, адрес конца и адрес передачи управления. Примеры A>blade A>blade *.gm? 3.2. УТИЛИТА CDEX.COM --------------------- Полное название C Documentation Extractor Назначение Извлечение документации из самодокументированных Си-программ. Формат командной строки cdex [.c] ... [.c] [=[.doc]] Параметры ~N>[.c] ... [.c]- имена файлов с необязательным суффиксом .C в скоторых находятся исходные тексты программ на языке Си. [[.doc]] - имя файла, в который будет выводиться документация. Если не указан - .doc Особенности В файл документации выводятся все строки программы, находящиеся на нулевом уровне вложенности фигурных скобок: глобальные переменные, имена функций и описания их параметров. На этом же уровне вложенности рекомендуется писать комментарии, описывающие назначение функций и параметров. Примеры A>cdex myprog A>cdex myprog1 myprog2 =myprog.cdx 3.3. УТИЛИТА DS.COM ------------------- Полное название Directory Sorter Назначение Вывод оглавления диска на экран в отсортированом виде. Формат командной строки ds[/p] Параметры /p - вывод копии экрана на принтер. - любая стандартная маска набора файлов MSXDOS с расширением "!" - [and] not. Если не указан - *.* Особенности Файлы, релевантные маске, выводятся на экран в отсортированом по алфавиту суффиксов, а внутри них - по именам файлов виде. Примеры A>ds A>ds b: A>ds *.c 3.4. УТИЛИТА DT.COM ------------------- Полное название Disk to Tape Назначение Перезапись файлов с диска на магнитную ленту Формат командной строки dt {A|B|C|U} {len|*} [{H|L}] [B] Параметры diskfile - имя файла на диске tapefile - имя файла на ленте (6 символов или * для формата UNDEF) {A|B|C|U} - формат выводного файла на ленте: А - ASCII, B - BSave, C - CSave, U - UNDEF (неопределенный - без заголовка). {len|*} - длина файла в байтах: len - в виде числа в явном виде, * - исходя из размера дискового файла или из длины, вычисленной из заголовка дискового файла для BSave. [{H|L}] - плотность записи на ленте (необязательный параметр): H - высокая, L - низкая. [B] - Batch (необязательный параметр): не ожидать нажатия на клавишу SHIFT после запуска мотора магнитофона для начала записи информации. Особенности 1. За одно выполнение утилиты можно записать на ленту файл размером не более 32 Кбайт. 2. CTRL STOP прерывает выполнение утилиты. 3. Вместо однобуквенных сокращений параметров можно записывать их полное наименование (см. пример). Примеры A>dt pacman.gm PACMAN bload * high batch A>dt pacman.gm PACMAN b * l b 3.5. УТИЛИТА DUMP.COM --------------------- Полное название SUPER DUMP Назначение Дамп/объединение различных источников информации. Форматы вызова для дампа файла: dump file [B[#]n] [S[#]n] [L[#]n] [H] [D] [P] [X[#]n] [{=|%|$|-}outfile] сектора на диске: dump (n) [B[#]n] [S[#]n] [L[#]n] [H] [D] [P] [X[#]n] [{=|%|$|-}outfile] памяти: dump #n[/p[s]] [M[#]m] [L[#]n] [D] [P] [X[#]n] [{=|%|$|-}outfile] видопамяти: dump #{0|1}.n [L[#]n] [R] [D] [P] [X[#]n] [{=|%|$|-}outfile] Параметры n - десятичное целое число в диапазоне 0~65535; #n - шестнадцатеричное число в диапазоне #0~#FFFF; B - BASE: базовое (начальное) значение счетчика адреса от начала дампа (в том числе, от начала SKIP); S - SKIP: пропуск [#]n байтов после BASE; L - LENGTH: длина данных (после SKIP, #FFFF по умолчанию); H - HEADER: отделить 7 байт BLoad-заголовка при выводе на экран; D - DISASSEMBLY (пока не реализован); P - PRINTER: вывод дампа на принтер; X[#]n - XOR: подвергать операции xor каждый выводимый байт с числом n (0~255) или #n (#0~#FF); =|%|$|- - префикс и тип выводного файла outfile: = ASCII шестнадцатеричный и символьный, % ASCII восьмеричный, $ BINARY - двоичная копия источника дампа, - BINARY - двоичная копия источника дампа без вывода на экран; /p[s] - первичный и вторичный слоты; M - MEMORY MAPPER: страница m (0~255) или #m (#0~#FF); 0|1 - нижние (0) или верхние (1) 64 Кбайт видеопамяти; R - использовать регистры V9938 вместо вызова BIOS/SUBROM (для MSX1 с V9938 и 128 Кбайт VRAM). Особенности 1. Нажатие любой клавиши останавливает/продолжает дамп. Нажатие клавиши STOP приводит к выходу в MSXDOS. 2. При помощи утилиты DUMP можно объединить несколько разных фрагментов разных источников в один файл - разделителем источников в командной строке является символ '&' (см. пример). 3. В качестве отдельных источников в командной строке могут использоваться специальные параметры (без пробелов) :hh...hh для записи байтов в шестнадцатеричном виде >a.....z для записи байтов в символическом виде 4. Если в качестве источника (источников) используется файл CON (консоль) - утилита запрашивает на консоли, в каком виде предполагается осуществлять ввод - шестнадцатеричном или символическом. При этом в режиме шестнадцатеричного ввода все не-шестнадцатеричные символы игнорируются. Примеры 1. вывести на консоль первые 100 байт файла foo.dat A>dump foo.dat l100 2. Объединенить в выводной файл outdat.gro: нижние 256 байт RAM начиная с адреса 0, 110 байт файла frotz.dat (предварительно пропустив 512 байт), сектор 0. A>dump #0 l#100 & frotz.dat s512 l110 & (0) -outdat.gro 3.6. УТИЛИТА DURATION.COM ------------------------- Полное название Duration Назначение Подсчет длительности интервалов времени. Формат командной строки duration [{z|Z}] Параметры z - запомнить текущее время в локальный счетчик, Z - запомнить текущее время в локальный и глобальный счетчики. Особенности 1. Для правильной работы утилиты необходим компьютер MSX2. 2. Если утилита вызывается без параметров - она выводит на консоль разницу между текущим значением времени и значениями, записаными в локальный и глобальный счетчики времени. 3. Если локальный или глобальный счетчики равны нулю - они автоматически устанавливаются на текущее время. 4. cc.com v1.50aR при каждом выполнении автоматически записывает в счетчик локального времени текущее время. Примеры 1. Подсчет времени компиляции файла gro.c A>cc gro A>duration 2. Подсчет времени компоновки файла gro.crl A>duration z A>clink gro -f grplib4 grplib3 grplib2 grplib1 grpliba -s -e4000 A>duration 3.7. УТИЛИТА EDL.COM -------------------- Полное название Extra Data Linker Назначение Прикомпоновка данных к COM-файлам, порожденным при помощи BDS C для последующего использования этих данных при помощи библиотечных функций geteda() и geteda2(). Формат командной строки edl [-c ] [-e ] [-f ] Параметры COM_file - файл порожденный clink (записывается без суффикса .COM) new_COM_file - новый COM-файл с прикомпоноваными к нему данными (записывается без суффикса .COM) -c - прикомпоновывать данные после конца кода, -e - прикомпоновывать данные в начале области External -f - прикомпоновывать данные после конца области External (free RAM) - файлы данных, записаные через пробел: -c file1 file2 file3 Особенности 1. Если используется более одного ключа одновременно - порядок их следования должен быть возрастающим (по адресам прикомпоновки): -c ... -e ... -f ... 2. Префиксы диск-драйвов не попадают в оглавления имен прикомпонованых данных, а суффиксы (.расширение) - являются неотъемлемой частью каждой точки входа в оглавление. Примеры A>edl mygame newgame -c game.mnt b:game.dat -f game.lib game.spr В результате выполнения данной строки будет создан новый файл NEWGAME.COM, состоящий из файла MYGAME.COM с прикомпоноваными к нему после конца кодов (и до начала области External) файлами GAME.MNT и GAME.DAT (последний считывается с драйва B:) и после конца области External файлами GAME.LIB и GAME.SPR. Это типичный пример использования EDL для создания окончательного файла игровой программы. 3.8. УТИЛИТА FCX.COM -------------------- Полное название Files Compressor/Expander Назначение Компрессор/экспандер для сжатия/расширения файлов. Компрессированые файлы могут быть экспандированы в программе пользователя при помощи библиотечной функции expand(). Формат командной строки fcx -{c|x} Параметры - исходный файл - результирующий файл -c - режим компрессии (Compress) -x - режим экспандирования (eXpand) Особенности 1. Компрессирование основано на сжатии "однородностей" с элементом компрессии длиной 1 байт (алгоритм неадаптивный). Поэтому, файлы имеющие очень небольшое количество одинаковых подряд идущих байтов могут компрессироваться неэффективно и иногда даже возрастать в объеме (попробуйте компрессировать уже компрессированый файл). 2. Для предварительной оценки степени компрессии без создания результирующего файла на диске, удобно использовать системный файл NUL в качестве . Примеры A>fcx game.mnt nul -c A>fcx game.mnt gamec.mnt -c 3.9. УТИЛИТА FICO.COM --------------------- Полное название Files Collector Назначение Диалоговый сборщик нескольких файлов в один файл. Формат командной строки fico Параметры - результирующий файл на диске Особенности 1. Files Collector ведет диалог с пользователем, запрашивая последовательно: - нужен ли 7-ми байтовый FE-заголовок (в BLOAD/BSAVE формате) для результирующего файла; - имена считываемых файлов с количеством байт, которое необходимо пропустить перед копированием и количеством байт, которое после этого необходимо копировать в результирующий файл. 2. Цифровые значения могут задаваться в десятичном или шестнадцатеричном виде - в последнем случае первым символом числа должен быть символ '#'. 3. CR (возврат каретки) предполагает ответ по умолчанию (обычно 0). Примеры A>fico resfile.dat 3.10. УТИЛИТА HC.COM -------------------- Полное название Hardcopy Назначение Вывод файлов на принтер. Формат командной строки hc [] [file] [] [file2] ... Параметры Необязательные параметры (options), относящиеся к управлению печатью каждого файла, записываются перед именами соответсвующих файлов и имеют в качестве первого символа слэш '/'. 1. Параметры, относящиеся к управлению принтером MSX STAR: /N NORMAL - нормальная ширина букв; /P PROPORTIONAL - ширина букв (то же самое, что NORMAL, но для точечной графики); /E ELITE - средняя ширина букв; /C CONDENCED - сжатая ширина букв; /X EXPANDED - удвоеная ширина букв для /N, /P, /E, /C; /S SMALL - уменьшеная высота букв (используются верхние индексы); /IT ITALIC - курсив (наклон вправо); /H ENHANCED - сдвиг на пол-точки с двойной печатью; /D DOUBLE strike - двойной удар; /Wnnn WIDTH - ширина строки nnn символов; /V+ VERTICAL step - подача бумаги для новой строки на 1/6 дюйма; /V- VERTICAL step - подача бумаги для новой строки на 1/8 дюйма; /Vnn VERTICAL step - подача бумаги для новой строки на nn/144 дюйма; /Fnnn FORMAT tape - длина страницы для подачи бумаги (Form Feed) nnn строк - по умолчанию 2 строки; /ESC... вывести код ESC и символы, следующие за ним - этот параметр должен быть последним в списке (если используется). 2. Другие параметры: /I+ выводить информационную строку с названием файла, датой и временем печати (/I+ установлен по умолчанию); /I- не выводить информационную строку; /L+ используются отдельные листы бумаги - отключение детектора конца бумаги и небольшое сокращение длины каждой страницы; /L- отключить механизм нумерации страниц - может быть использован совместно с /L+; /Lnnn nnn - количество строк на каждой странице (обычно автоматически вычисляется исходя из размера шрифта и вертикальной подачи бумаги) - может быть использован совместно с /L+ и /L-; /$nnn задать начальный номер страницы nnn; /#nnn печатать, начиная со страницы nnn (пропустить nnn-1 страниц), по умолчанию 1. Особенности 1. Каждый файл печатается с параметрами, которые встретились ДО ЕГО ОПРЕДЕЛЕНИЯ - последний параметр из группы альтернативных (например, выбора шрифта) имеет больший приоритет. 2. Если имя файла отсутствует - принтер будет настроен на тип печати при помощи управляющих кодов. 3. Если вместо имени файла написана звездочка '*' - на принтер выводится копия текущего экрана. 4. Для всех файлов, встретившихся в командной строке без указания параметра /$nnn сохраняется единая нумерация страниц. 5. По концу каждой страницы предусмотрено ожидание нажатия пользователем клавиши после проверки/коррекции установки бумаги. Примеры A>hc/c/i- grpmsx1.h A>hc/c/s * 3.11. УТИЛИТА SS.COM -------------------- Полное название Sector Server Назначение Копирование/проверка дисков по секторам. Формат командной строки ss {d1|*} d2 [d1s d1e d2s] [-p] [-b] [-v] Параметры d1 - имя диск-драйва источника (откуда считывать); * - в качестве источника используются специальные кодовые последовательности, генерируемые утилитой Sector Server для проверки качества записи на диск. d2 - имя диск-драйва приемника (куда записывать); d1s - Disk 1 Start - начальный сектор источника; d1e - Disk 1 End - последний сектор источника; d2s - Disk 2 Start - начальный сектор приемника; -p - Pause - пауза перед начальным опросом диск-драйвов для установки требуемых дисков; -b - Batch - отмена запроса на подтверждение копирования для работы в потоке заданий; -v - Verify - считывание и проверка каждого сектора после записи (собственными средствами утилиты Sector Server). Особенности 1. Имена диск-драйвов источника и приемника могут записываться без двоеточия. 2. Если при копировании диска на диск не указывается диапазон копируемых секторов - копируются все секторы, включая резервные. 3. Если в качестве источника используется '*' - информация на диске-приемнике в указаном диапазоне секторов будет разрушена тестовыми последовательностями проверки качества поверхности диска. Если таким образом проверяются секторы 0~13 - после проверки диск необходимо форматировать. Примеры 1. Копировать с А: на А: секторы 1~13 в секторы 1427~1439: A>ss a a 1 13 1427 2. Копировать А: на B: с паузой и проверкой: A>ss a b -p -v 3. Проверка качества поверхности всего диска на B: A>ss * b 0 1439 3.12. УТИЛИТА TD.COM -------------------- Полное название Tape to Disk Назначение Перезапись файлов с магнитной ленты на диск. Формат командной строки td [] Параметры - дисковый файл, в который выводится протокол работы пользователя с утилитой для последующего анализа введенных файлов, а также для подготовки заданий для утилиты DT.COM. Особенности Утилита ведет диалог с пользователем, выводя на экран меню управляющих клавиш и назначеных им функций. При работе с утилитой допускается, что пользователь не знает, в каком формате (в каких форматах) записаны файлы на магнитной ленте и, поэтому, ему предоставляется возможность перед непосредственной записью на диск произвести предварительный анализ файла (файлов) на типы заголовков и данных. Все операции по анализу файлов на ленте могут записываться в файл протокола и/или выводиться на принтер. Пользователю предоставляется также возможность вписывать в файл протокола произвольные комментарии во время анализа магнитной ленты. Основными форматы данных, "понимаемыми" утилитой являются ASCII, CLOAD, BLOAD и UNDEF для MSX-машин. Примеры A>td tape1.pro Компоновщик/Редактор Знакоместной Графики версия 3.04 (c) А.Родионов ==================================================================== Pattern Composer v3.04 АННОТАЦИЯ В данном документе содержится описание применения программы "Pattern Composer" версии 2.02. Документ предназначен для разработчиков программного обеспечения на компьютерах MSX2 и MSX и содержит следующие разделы: "Назначение", "Условия применения", "Порядок работы", "Форматы данных", "Рекомендации по использованию". "Pattern Composer" является авторской разработкой А.Б.Родионова (Москва, 1987~1988). Оригинальная документация ведется на английском языке для совместимости с компьютерами и другим оборудованием, не имеющим кириллических знакогенераторов и может быть поставлена по специальному заказу. По этой же причине англоязычными являются все комментарии и диалог, ведущийся программой, а также другими компонентами ПС "МАЭСТРО". Данный документ не следует рассматривать как учебное пособие по компьютерам MSX2 и MSX - напротив он расчитан на подготовленых программистов, знающих архитектуру этих компьютеров, но испытывающих затруднения в выборе инструментальных средств для разработки своих программ. -------------------------------------------------------------------- ПС "МАЭСТРО" является первым в СССР программным продуктом, обладающим имеющим законную силу Copyright (C) - правом на тиражирование и копирование. -------------------------------------------------------------------- 1. НАЗНАЧЕНИЕ Программа Pattern Composer (Компоновщик Знакоместной графики) предназначена для разработки знакоместной графики в Screen 2. В качестве инструментальной машины используется MSX2 (дополнительная память и мышь), но результирующие файлы полностью совместимы с MSX1. Программа использует в работе графические меню, выбор из которых осуществляется при помощи манипулятора мышь. Основным режимом работы программы является режим компоновки знакомест на полиэкране из знакоместной библиотеки, которая может быть создана с помощью этой же программы, или может быть получена загрузкой файла, содержащего копию VRAM для Screen 2. Такой файл может быть подготовлен при помощи других графических редакторов или даже программы, написанной на языке Бейсик. Pattern Composer позволяет разрабатывать различные фазы движущихся объектов, редактировать их, получать копии изображений на бумаге, сохранять их в файлах в различных форматах, манипулировать с библиотеками знакомест, экранов и др. Форматы хранения данных совместимы с форматами, используемыми "Библиотекой функций MSX для BDS C" (далее просто "Библиотека функций"). Полиэкран может иметь различные конфигурации в зависимости от требований пользователя. Имеется встроенная функция "Help" с подразделами описаний форматов файлов, используемой терминологии и др. 2. УСЛОВИЯ ПРИМЕНЕНИЯ Для работы программы Pattern Composer (в дальнейшем именуемой PAC) необходим компьютер MSX2 оснащенный манипулятором мышь (в дальнейшем просто мыш"). Основное назначение РАС - подготовка графики для программ, которые работают в Screen 2 и Screen 4 (для V9938 Graphics 2 и Graphics 3). Компьютер MSX2 используется в качестве инструментальной машины из-за расширеных требований к человеко-машинному интерфейсу PAC (работа с мышью, оконные меню и пр.) и наличия большего количества оперативной памяти для реализации функций РАС. Графика, порождаемая РАС полностью совместима с MSX1. При работе с РАС, наиболее предпочтительными являются компьютеры MSX2, имеющие аппаратуру Memory Mapper и более 64 Кбайт оперативной памяти (RAM). Это связано с тем, что при наличии Memory Mapper, РАС размещает все свои оверлейные программные сегменты и полиэкран пользователя в мэппируемой памяти и не производит дополнительных обращений к диску во время работы. Тем не менее, РАС может работать и на компьютерах MSX2, имеющих только 64 Кбайт RAM и 128 Кбайт VRAM. В этом случае, полиэкран пользователя располагается в VRAM (что несколько замедляет работу по сравнению с Memory Mapper), a программные сегменты подгружаются по мере необходимости с диска. РАС написан на языке С (компилятор BDS C) с использованием "Графической Библиотеки MSX для BDS C". 3. ПОРЯДОК РАБОТЫ 3.1 Для вызова РАС с диска, введите с клавиатуры компьютера: A>pac После этого РАС будет загружен в память и начнет работать. При этом, РАС будет использовать стандартную демонстрационную библиотеку знакомест (Patterns/Colours Library), которая находится в нем самом. Если вы модифицируете эту библиотеку и захотите сохранить ее в виде отдельного файла - воспользуйтесь функцией SAVE LIBRARY в меню РАС (файлам библиотек рекомендуется давать расширение .LIB при сохранении их на диске) Для того, чтобы познакомиться с возможностями PAC, загрузите в него файл DEMO.MNT, выбрав функцию LOAD в меню РАС (MNT - Multi-screen Name Table - полиэкран) и попробуйте модифицировать его. Если вы захотите сохранить полиэкран на диске - воспользуйтесь функцией SAVE ALL NAME TABS в меню РАС (файлам полиэкранов рекомендуется давать расширение .MNT при сохранении их на диске). Если вы хотите сохранить отдельный экран - воспользуйтесь функцией SAVE SINGLE NAME TAB (используйте расширение .SNT). Пробуйте вызывать различные функции PAC и учитесь пользоваться ими - это не должно занять у вас слишком много времени. 3.2 Полный формат командной строки РАС: pac [l=libfile] [screenfile] Если вы разработали свою собственную библиотеку знакомест и полиэкран для нее (и, конечно, сохранили их на диске!), то Вы должны вызывать РАС, указывая имена Ваших файлов в командной строке РАС. Предположим, что Ваша библиотека называется MYPIC.LIB, а полиэкран - MYPIC.MNT, в этом случае командная строка вызова РАС будет выглядеть следующим образом: A>pac l=mypic.lib mypic.mnt Специальный batch-файл P.BAT поможет Вам упростить вызов PAC: А>p mypic Одной из особенностей РАС является возможность загружать файлы библиотек знакомест присоединяя их к уже загруженым - поэтому, если вы воспользуетесь функцией LOAD для загрузки библиотеки из меню РАС, когда РАС уже загружен в память и работает, вы присоедините "новую" библиотеку к "старой". "Новая" библиотека будет размещена в пространстве "старой" начиная с позиции "первого свободного знакоместа" (там, где находится указатель "первого свободного" "старой" библиотеки) и будет добавляться к "старой" за исключением всех повторяющихся знакомест (одинаковых паттернов, имеющих одинаковую окраску). Таким же образом вы можете загрузить в РАС экран, подготовленный другим редактором (например "Graphic Master" Sony) или Бейсиком. При этом РАС определит по первому байту файла, какие данные и в каком формате вы предлагаете ему загрузить и, если это экран Бейсика или библиотека знакомест - попытается присоединить их к уже загруженой библиотеке. В случае экрана Бейсика, РАС будет пытаться восстановить исходное изображение (конечно, насколько это будет возможно исходя из наличия свободного места в уже загруженой библиотеке). Замечания. 3.2.1. Как уже было указано, тип загружаемого файла распознается РАС автоматически исходя из первого байта файла (см. "Files" в "Help" меню РАС и раздел 5 данного документа). 3.2.2. вы можете сохранять отдельные экраны (SNT-файлы) и загружать их в произвольные места полиэкрана (MNT-файла), которые могут, в том числе, не совпадать с точными границами отдельных экранов. 3.2.3. MNT-файлы могут быть сохранены в двух основных форматах: "Абсолютном" и "Переместимом" ("Absolute" и Relocatable"). "Абсолютный" формат является отображением памяти всего полиэкрана "строка за строкой" и используется в рамках "Библиотеки функций" для загрузки и дальнейшей работы со знакоместной графикой. Ширина и высота полиэкрана (в отдельных экранах) являются неотъемлемой частью данных этого формата и автоматически восстанавливаются в РАС при загрузке файла с диска на основе данных, записанных в "абсолютный" файл при его сохранении. "Переместимый" формат является отображением памяти полиэкрана "экран за экраном" и, поэтому, не связан жестко с конфигурацией полиэкрана. "Переместимый" файл может быть загружен в любую конфигурацию полиэкрана (с любыми высотой и шириной) без ее изменения. "Библиотека функций" не поддерживает загрузку "переместимых" полиэкранов и этот формат используется, в основном, для изменения размещения экранов в рамках РАС как альтернатива сохранению одиночных экранов (SNT) в виде отдельных файлов с последующей их одиночной загрузкой. Тем не менее, этот формат может быть эффективно использован в программах пользователя в том случае, когда не требуется скроллинг полиэкрана. 3.2.4. Постарайтесь не использовать в Библиотеках знакоместа с латинскими буквами, цифрами и фрагментами рамок для других паттернов когда создаете свою собственную библиотеку. Это предотвратит временное искажение внешнего вида меню самого РАС (текущая версия РАС не защищает системную библиотеку знакомест, которая полностью доступна пользователю для любых модификаций). Эта рекомендация имеет смысл и применительно к "Библиотеке функций", так как стандартная таблица перекодировки для вывода алфавитно-цифровых символов на экран с использованием функций putstrt(), tprintf() и др. ориентирована на существующее расположение этих символов в стандартной библиотеке знакомест. Тем не менее, это требование не является обязательным - вы можете полностью изменить стандартную библиотеку РАС - РАС будет продолжать работать (если, конечно, вы сможете работать с искаженными меню РАС). 3.3. Управление РАС РАС имеет два основных режима работы: "Меню" и "Компоновка" (Menu и Compose). Сразу после загрузки РАС, он переходит в режим Menu, в котором вы можете выбирать такие функции РАС как COPY, CUT, PASTE,... или вызывать некоторые подсистемы, такие как Pattern Editor+, простым нажатием на левую кнопку мыши с указаним стрелкой на выбранную Вами функцию. Для переключения РАС между режимами Menu/Compose нажимайте правую кнопку мыши. В режиме Compose все меню РАС исчезают с экрана и, используя кнопки мыши вы можете брать паттерны с экрана и располагать их там, где считаете необходимым (при этом РАС модифицирует только Name Table). Примечание: двойное нажатие на правую кнопку мыши (Double Click) в режиме Compose приводит к появлению/исчезновению в верхней трети экрана библиотеки знакомест, из которой вы можете брать паттерны, которых в данный момент нет на экране. В основном, все режимы работы РАС могут быть выбраны при помощи мыши (Single-click, Double-click, DRAG - нажать кнопку и перемещать мышь до отпускания кнопки), но часть наиболее часто используемых функций продублирована при помощи клавиш клавиатуры (см. "Help" в меню РАС). Кроме того, скроллинг полиэкрана (MNT) может осуществляться ТОЛЬКО при помощи клавиш КУРСОРА (с использованием или без использования клавиши GRAPH). Лучший способ научиться - это практика: загрузите файл DEMO.MNT, просмотрите его (используя клавиши курсора и GRAPH), модифицируйте полиэкран в режиме Compose (перейдя в него при помощи UNDO), загрузите Pattern Editor+ (нажав ESC или вызвав эту подсистему из меню), модифицируйте Библиотеку знакомест, попробуйте Animaion (динамическую смену фаз)... Может быть РАС поможет Вам так же, как он помогает своему автору? 4. ФОРМАТЫ ДАННЫХ Файлы, которые в настоящий момент могут быть подготовлены при помощи РАС и сохранены на диске, классифицируются следующим образом: 1. Multi-screen Name Table (MNT) - полиэкран, состоящий из одиночных экранов общим количеством до 21 (каждый одиночный экран - Single-screen Name Table (SNT) 768 байт). Полиэкран может быть сконфигурирован пользователем с различными шириной и высотой, задаваемых в количестве SNT (см. "Screen Config" в меню РАС) и сохранен в различных вариантах: "Абсолютном" и "Переместимом" (см.выше). 2. Singe-screen Name Table (SNT) - текущее положение окна физического экрана на полиэкране (MNT) - 768 байт Name Table. 3. Library (LIB) - Библиотека знакомест: pattern-библиотека (2048 байт) + colour-библиотека (2048 байт). При работе РАС и в большинстве других приложений Библиотека чаще всего является общей для всех 3 частей экрана в Screen 2: верхней, средней и нижней. Однако, это не исключает того, что Ваша будущая программа сможет использовать до трех независимых друг от друга различных Библиотек для различных третей экрана. Как уже было отмечено выше, РАС сам различает форматы файлов, которые ему предлагают загрузить и сохраняет файлы с признаком формата сохранения. Для идентификации различных форматов записи файлов, создаваемых и загружаемых РАС, используется первый байт (первые байты) каждого файла. Ниже приводятся стандартные значения этого байта (байтов) с соответствующими комментариями. F7 - MNT в "Абсолютном" (сторка за строкой MNT) формате. Последующие 2 байта являются шириной и высотой MNT в одиночных экранах (SNT). РАС поддерживает загрузку и сохранение таких файлов. F8 - Special. Использовался для разработки собственно РАС. РАС поддерживает только сохранение таких файлов. F9 - MNT в "Переместимом" (экран за экраном SNT) формате с шириной и высотой MNT. В настоящее время не поддерживается. Используется для совместимости со старыми версиями РАС только в режиме загрузки. FA - Sprites (2048 байт) - пока не поддерживается РАС. FB - SNT - 768 байт. РАС поддерживает загрузку и сохранение таких файлов. FC - MNT в "Переместимом" (экран за экраном SNT) формате. Нет байтов ширины и высоты MNT. РАС поддерживает загрузку и сохранение таких файлов. FD - Библитека знакомест: Pattern Generator (2048 байт) + Colour Table (2048 байт) + 1байт. Последний байт является "указателем первого свободного" знакоместа для алгоритма автоматического размещения/добавления знакомест РАС. РАС поддерживает загрузку и сохранение таких файлов. FE - Стандартный формат BSave/BLoad для VRAM MSX Бейсика. Следующие 3 слова (по 2 байта) являются адресами загрузки, конца данных и исполнительным адресом (не имеет смысла для VRAM). РАС поддерживает только загрузку таких файлов. 5. РЕКОМЕНДАЦИИ ПО ИСПОЛЬЗОВАНИЮ РАС является достаточно большой и сложной программой с простым интерфейсом пользователя. Так как теоретически в любой большой (и даже уже исправленой) программе всегда есть как минимум 3 ошибки, автор предполагает, что они есть и в РАС. Поэтому, в случае обнаружения этих ошибок при работе с РАС - просьба сообщить о них автору. Для того, чтобы эта информация принесла реальную пользу, при обнаружении ошибки нажмите, пожалуйста, клавишу SELECT и запишите ряд цифр, которые появятся в нижней строке экрана (клавиша SELECT включает и выключает встроеный механизм трассировки РАС). Эти цифры (вместе с номером версии РАС, которую вы эксплуатируете и объемом оперативной памяти Вашего компьютера) помогут автору при поиске причины нарушения нормальной работы РАС. Музыкальный пакет "MEDIA" 1. Введение. Музыкальный пакет "MEDIA" является инструментальным программным средством (ПС) для разработки музыкального сопровождения учебных, игровых и демонстрационных программ для ПЭВМ MSX. Пакет состоит из музыкального редактора MED и библиотеки функций для языка C. ПЭВМ MSX оснащены трехголосным программируемым звукогенератором (PSG) GI AY-3-8910, имеющим диапазон 8 октав и генератор шума. Для программной поддержки PSG в языке Бейсик имеется оператор PLAY с встроенным языком MML (Music Macro Language), позволяющим в символической форме представлять нотную запись а также управлять громкостью и формой звукового сигнала; однако среда Бейсика мало приспособлена для создания программ профессионального уровня. В системе же MSX DOS музыкальные средства отсутствуют. Пакет "MEDIA" предоставляет разработчикам программ в MSX DOS удобный инструмент подготовки музыкальных фрагментов для PSG, включения их в программу и управления исполнением, создания музыкальных и шумовых эффектов. Пакет "MEDIA" разработан в рамках идеологии ПС "МАЭСТРО" и предназначен для использования вместе с ПС "МАЭСТРО". Автор выражает благодарность А.Родионову за идейную и техни- ческую поддержку разработки. 2. Язык MML+. В качестве основы нотной записи использован язык MML MSX-Бейсика ([1],[2]) со следующими дополнениями: - при записи нот большие и малые буквы обозначают разные октавы, большие буквы относятся к октаве, указанной в операторе 'О', a a малые - к O+1 ; это существенно сокращает количество операто- ров О в нотной записи. напр. о3AbCda A,C- октава 3, а b,d,a- октава 4. - оператор Zn[-] повышает (а если указан "-" -понижает) все последующие звуки на "n" полутонов. - оператор Un[-] понижает или повышает все последующие звуки, увеличивая или уменьшая на "n" единиц делитель частоты PSG. - знак ':' устанавливает на первую следующую за ним ноту или паузу указатель начала цикла для очереди пакетов данного голоса (см. описание функции play()). - разрешено произвольное количество пробелов в строке, они игнори- руются; это позволяет поддерживать "вертикальность" записи аккордов. - текст между операторами < и > рассматривается как комментарий и не транслируется. - трансляция заканчивается, если встречен символ '%' или '\0'. О ператоры для управления LFO и шумом (LFO - Low Frequency Oscillation - изменение частоты звучания генератора относительно основной загруженной ноты). - операторы [ и ] включают и выключают LFO для соответсвующего голоса; за оператором [ может следовать цифра 0, 1 или 2, задающая форму LFO: /\, \/ или _П. - операторы { и } включают и выключают LFO для шума; за оператором { может следовать цифра 0, 1 или 2, задающая форму LFO: /\, \/ или _П. - операторы ( и ) включают и выключают шум в соответствующем голосе. - оператор *a задает амплитуду LFO для данного голоса. - оператор *t задает период LFO для данного голоса. - оператор /a задает амплитуду LFO для шума. - оператор /t задает период LFO для шума. - оператор /f задает период шума. Исключен из языка оператор X подстановки переменной Бейсика. Данный язык будет в дальнейшем обозначаться MML+. 3. Руководство программиста по использованию библиотеки GRPLIBM. Функции из библиотеки GRPLIBM.CRL предназначены для использования в программах, написанных для компилятора BDS C. Они подключаются к программе на шаге редактирования (clink). При этом в операторе -f командной строки clink имя библиотеки GRPLIBM должно быть указано раньше имен библиотек GRPLIBx ПС "МАЭСТРО". Музыкальные отрывки на MML+ подготавливаются, транслируются и проверяются с помощью редактора MED, а затем записываются на диск в виде готовых к исполнению музыкальных фрагментов в формате системной музыкальной очереди (СМО) MSX. Структура музыкального фрагмента: ---------------------------------------------- ... ----...-------...---- |VAlen |VAptr | VBlen |VBptr |VClen |VCptr | VAq | VBq | VCq | ----------- ---------------------------------- ... ----... ------...---- где: - VAq, VBq, VCq - очереди пакетов для голосов A, B и С, подготовленные функцией mmq; - VAlen, VBlen, VClen - их длины (включая завершающие 0хFF); - VAptr, VBptr, VCptr - указатели начала цикла для каждого голоса. Эти фрагменты могут быть присоединены к программе заранее с помощью EDL ( Extra Data Linker), входящего в ПС "МАЭСТРО", либо загружаться динамически в процессе выполнения программы, например, функцией swapin(). Программа должна быть составлена с учетом следующих требований: - должны быть указаны #include для grplib0.h и grpmus.h. - в начале выполнения вызываются функции grpini(), musini() и, если используется LFO, lforeset() (в указанном порядке!). - функция tickexit() должна содержать вызов функции mutick(), а если используется LFO - также и lfotick(). - должен быть включен механизм прерываний (TICKON). Когда эти условия выполнены, можно вызывать функцию play(). Она сбрасывает предыдущее состояние PSG и СМО и "запускает" исполнение указанного музыкального фрагмента однократно или в цикле. Все дальнейшие операции с музыкальной очередью производятся асинхронно. Функция mutick(), вызываемая в подпрограмме tickexit(), переносит максимально возможное число музыкальных пакетов из входной очереди в системную; если входная очередь исчерпана и нет признака цикла, заносит признак окончания очереди в СМО данного голоса. Интерпретация пакетов и непосредственное управление PSG осуществляетсяпод программой обработки СМО, входящей в состав обработчика прерываний BIOS MSX. Исключением являются пакеты управления LFO и шумом, которые интерпретируются функцией mutick() и в системную очередь не переписываются; поэтому, например, включения и выключения шума, заданные операторами ( и ), не синхрони- зированы с теми местами нотной записи, где стоят ( и ), а наступают раньше. В случае, если ( и ) стоят близко к началу записи, они оба могут быть обработаны mutick() при начальном заполнении системной очереди, до начала исполнения, и шум вообще не включится; однако при циклическом исполнении фрагмента при втором и последующих проходах включение и выключение шума будет происходить. С помощью функции ismus() можно определить состояние СМО для каждого из голосов; функция musoff() "выключает" музыку и сбрасывает все очереди. Для случаев, когда музыкальные фрагменты не могут быть оттран- слированы заранее, например, для разработки диалоговых музыкальных программ, в пакет MEDIA включен транслятор с MML+, оформленный в виде функции mmq(), который транслирует исходную строку на MML+ во внутренний формат СМО - последовательность музыкальных пакетов 4. Функции, входящие в библиотеку GRPLIBM: - функции управления музыкaльной очередью: play(cycle,qad) char *qad; int cycle; - ставит музыкальный фрагмент с адресом 'qad' в муз. очередь. Eсли cycle=0, элемент играется один раз; в противном случае mutick(), встретив байт 0xFF, не переписывает его в системную очередь, а начинает с места данной входной очереди, указанного в Vptr. Если в нотной строке не было операторов ':', указатель содержит 0; если встретилось несколько операторов ':', указатель соответствует последнему из них. Вызывает lf4init(), включает шум. play(cycle,qad) char *qad; int cycle; - то же, что play(), исключая вызов lfo4init() mutick() - вызывается в tickexit() для периодической перезаписи музыкальных пакетов в системную музыкальную очередь и интерпретации пакетов управления LFO и шумом. musoff() - "выключает" музыку, сбрасывает системные очереди. musini(p) char *p; - инициализирует глобальные переменные; сбрасывает сис- темные очереди. Если p=0, в качестве области параметров LFO берется 80 байтов в рабочей области Бейсика, начиная с адреса 0xF418, иначе эта область помещается по указанному адресу p. char ismus() - возвращает байт, разряды 0-2 которого соответствуют состоянию системных очередей голосов 1-3. Например, если ismus()=0, все три голоса молчат; если ismus()=4, играет только голос 3. xmus() - приостанавливает музыку, "замораживает" очереди. При повторном вызове продолжает исполнение с места остановки. autoplay(va,vb,vc) char *va,*vb,*vc; - "шарманка"; обеспечивает автоматическое (без подкачки по mutick() ) проигрывание музыкальных очередей va,vb,vc. Каждая из очередей при этом должна иметь длину 129 байтов или 1 байт (включая замыкающие 0xFF). Для подгонки длины можно вставлять фиктивные операторы m, разбивать ноты по длительности и т.п. int mmq(pa,pq,yy,tm) char *pa,*p; unsigned *tm,*yy; - транслятор MML+; транслирует символическую строку MML+, находящуюся по адресу pa, в последовательность музыкальных пакетов, оканчивающуюся 0хFF, и помещает ее по адресу pq; возвращает длину полученной очереди пакетов, а при ошибках трансляции - номер позиции в исходной строке, содержащей ошибку, со знаком минус; в слово по адресу yy заносит указатель цикла Vptr; в слово по адресу tm заносит суммарную продолжительность звучания в тиках. /теоретически возможный случай продолжитель- ности > 65536 тиков, т.е. > 18 мин. в расчет не принимается ввиду его практической невероятности и бесполезности./ int lftq(qn) char qn; - сообщает число свободных байтов в системной музыкальной очереди канала qn. putq(qn,byte) char qn,byte; - помещает byte в системную музыкальную очередь канала qn. - функции для прямого управления PSG: int setlfo(v,typ,t,a) int t,a; char v,typ; - заносит параметры LFO: тип (0-2), период и амплитуду (0-32767) для голосов 1-3 (v=0-2) или для шума (v=3) в блок управления LFO и инициализирует этот блок. ( Структура блока управления задана в GRPMUS.H. Включение и выключение LFO для голоса или шума произво- дится установкой в 1 или 0 глобальных переменных _FMFL[i] ). Если входные значения ошибочны, возвращает -1. lfinit(p) struct _LF *p; - инициализирует рабочие переменные LFO в указанном в p блоке управления LFO в соответствии с задаными ранее параметрами. lf4init() - выполняет lfinit() для всех четырех блоков управления LFO. lfreset() - сбрасывает все параметры LFO, выключает LFO для всех голосов и шума. lfotick() - вызывается в tickexit(); управляет LFO, меняя частоту PSG. noisep() - загружает период шума в PSG из глобальной переменной _NP. (пять младших битов _NP). noise() - включает шум в голосах, которым соответствуют '0' в маске. Маска находится в трех старших (левых) битах _NP. noisev(v,on) char v,on; - включает (если on=1) или выключает (on=0) шум в голосе v. xnoise(v) char v; - поочередно включает/выключает шум в указанном голосе v. /* notick() - вызывается в tickexit(); осуществляет модуляцию шума (linear noise oscillation, LNO): если установлен глобальный флаг _NMFL, "базовый" период шума, заданный в noisep(), модулируется через каждые NТ тиков случайным приращением в диапазоне (-NA,NA). Значения NT, NA и периода шума NP хранятся в глобальных переменных, определенных в GRPMUS.H. Первоначально они устанав- ливаются в 0 функцией musini(). */ xlno() - включает/выключает модуляцию шума. - функции для поддержки 4-х цветов и мерцания в режиме TEXT2 для MSX2: setblnk(txt,bg,on,off) int txt,bg,on,off; - задает параметры мерцания (все четыре параметра должны быть в диапазоне 0-15). txt и bg задают альтернативную пару цветов текст/фон. Мерцающие символы поочередно высвечиваются то основными, то альтернативными цветами. ( Позиции экрана, в которых должно происходить мерцание, задаются установкой соответствующих битов в Color Table). Период мерцания задается величинами on - время высвечи- вания альтернативным цветом и off - основным (*1/6 сек.). Если оn и off равны 0, мерцания нет, все выводится в основных цветах. Если on=15, а off=0, мерцания также нет, но позиции, помеченные в Color Table, выводятся альтернативными цветами, т.е. появляется возможность работать в режиме TEXT2 с четырьмя цветами. rstblnk() - устанавливает период мерцаний равным 0, т.е. выключает мерцание на всем экране, не изменяя Color Table. clrblnk() - обнуляет Color Table, т.е выключает мерцание для каждой позиции экрана. blink(x,y,len) int x,y,len; - включает мерцание для len позиций экрана, начиная с позиции с координатами (x,y). xblink(x,y,len) int x,y,len; - переключает мерцание для len позиций экрана, начиная с позиции с координатами (x,y) (т.е. включает для выключенных, выключает для включенных). dblink(x,y,len) int x,y,len; - выключает мерцание для len позиций экрана, начиная с позиции с координатами (x,y). 5. Ограничения, накладываемые звукогенератором и механизмом прерываний. 1. Длительность звучания ноты измеряется в тиках - 1/60 сек ( на некоторых машинах - 1/50). Она определяется по формуле: d=14400/(t*l) (на 50-гц машинах - 12000), минимальная длительность равна двум тикам, максимальная - 4095. Систематическая погрешность округления при нецелом частном может приводить к рассинхронизации голосов, которую приходится устранять вручную, вставляя дополнительные ноты и контролируя длительности голосов в поле 'Ticks' на экране музыкального редактора. 2. В моменты обращения к диску системный обработчик прерываний получает управление с задержкой, что приводит к искажению длительностей нот, загруженных в это время в звукогенератор. 3. Если tickexit() в программе пользователя слишком долго не получает управления (например, при неправильно организованном ожидании ввода с клавиатуры; при использовании отладочной функции dump() с большим объемом выдачи и т.п.), и успевают доиграть все пакеты, поставленные mutick() в системную очередь, может произойти отключение или рассинхронизация голосов. Поэтому надо внимательно отслеживать возможные источники задержек, обязательно вставлять totick() в продолжительные или зависящие от внешних событий циклы и функции, осторожно пользоваться DIS_INTERRUPT, TICKOFF и TICKSTOP. Если специфика программы такова, что гарантировать регулярное выполнение tickexit() невозможно, остается воспользоваться функцией autoplay(). Примечание: grpini(), tickexit(), totick(), dump(), DIS_INTERRUPT, TICKOFF, TICKSTOP - функции, входящие в ПС "МАЭСТРО". swapin() - функция BDS C. 6. Работа с музыкальным редактором MED. Музыкальный редактор MED позволяет вести экранное редактирование нотной строки, состоящей из четырех строк - по одной для каждого из трех голосов и строки комментариев. При этом осуществляется гори- зонтальный скроллинг нотной строки. MED транслирует нотную запись MML+ в формат системной музыкальной очереди, обеспечивает прослушивание полученных фрагментов однократно или в цикле. Можно также включать шум в каждом из голосов, менять характеристики шума, управлять LFO независимо в каждом голосе. При этом текущее состояние параметров LFO и шума непрерывно отобра- жается на экране. Записанные музыкальные фразы могут быть сохранены на диске в исходной (MML+) форме или в виде оттранслированного, готового к исполнению программой пользователя музыкального фрагмента, а также могут быть загружены с диска. Редактор снабжен четырьмя страницами подсказок, которые высвечива- ются в верхнем окне экрана. Первая страница описывает клавиши управле- ния редактированием, вторая - операторы языка MML+, третья - операторы MML+ для прямого управления PSG, четвертая - формы огибающих для оператора S MML+. После вызова программы MED на экране появляются нотная строка, CUT/PASTE буфер , окно музыкальной очереди, окно прямого управления PSG и строка главного меню с подсвеченным курсором. Нажатием клавишей -> и <- курсор меню устанавливается на нужную функцию; для вызова функции надо нажать пробел или возврат каретки (CR). Из главного меню вызываются функции: EDIT - переход в режим редактирования. LOAD - загрузка символического файла для редактирования. Если первым символом файла является '%', файл загружается в строчные буфера, начиная с буфера комментариев. Загрузка в каждом буфере начинается с позиции, в которой находился курсор. Разделителями голосов являются знаки '%' или '\0'(0). Знаки-разделители в буфер не переписыва- ются. Также подавляются знаки с шестнадцатеричным значением < 0x20. Максимальная длина каждого голоса 700 байтов. Если редактор при вызове функции LOAD находился в режиме замены (OVERTYPE), то старое содержимое буферов, начиная с позиции курсора, стирается; если был включен режим вставки (>INSERT<), это старое содержимое добавляется в конец буфера после вновь загруженного; при этом стирается буфер CUT/PASTE. Если первыЙ символ файла не '%', файл переписывается в буфер CUT/PASTE (700 байтов), а строчные буфера не изменя- ются. SAVE - строчные буфера переписываются в файл на диске. Если в записи содержится символ '%', то символы, стоящие в строке данного голоса правее %, не записываются на диск. Первым символом файла, а также после каждого голоса записыва- ются '%'. BLOAD - файл с диска ( музыкальный фрагмент ) переписывается в область музыкальной очереди редактора (до 10500 байтов). Фрагмент можно затем прослушать функцией play редактора. Дальнейшее редактирование фрагмента невозможно. BSAVE - готовый музыкальный фрагмент из области музыкальной оче- реди редактора записывается на диск. Во всех четырех дисковых функциях после выбора функции в верхнем окне экрана появляется запрос: "enter file name:", в ответ на который следует ввести требуемое имя файла. Для отмены функции и возврата в меню можно нажать STOP или ESC. QUIT - выход из редактора в MSX DOS. Режим редактирования. После выбора функции 'EDIT' главного меню строка меню стирается с экрана, на ее месте появляется строка подсказки; кроме того, в верх- ней части экрана появляется текущая страница подсказки. Переклю- чение страниц подсказки производится нажатим SHIFT-F5. Редактирование осуществляется в режиме скроллинга строки при не- подвижном курсоре. При этом номер позиции, в которой находится курсор, высвечивается над нотной строкой. Клавиши управления редактированием: "вверх" и "вниз" перемещают курсор со строки на строку. "влево" и "вправо" ('<-' и '->') двигают строку. SHIFT+'<-' и SHIFT+'->' двигают строку с шагом 20 символов. HOME - устанавливает курсор на начало строки. HOME+SHIFT - устанавливает курсор на последний символ в строке. INS - переключает режимы вставки/замены символов (текущий режим указан надписью >INSERT< / OVERTYPE в правой части экрана). BS (backspace) - стирает символ слева от курсора. DEL - стирает символ, на который указывает курсор. SHIFT+CTRL+DEL - стирает все символы текущей строки справа от курсора. GRAPH - PASTE: содержимое CUT/PASTE буфера копируется в нотную строку, начиная с позиции курсора. CUT/YANK: TAB (1-е нажатие) - переход из режима редактирования в режим CUT/YANK; в этом режиме можно только управлять движением нотной строки; при этом помечается блок текста. Выход из режима CUT/YANK может осуществляться следующими способами: TAB (2-e нажатие) - YANK: отмеченный блок копируется в CUT/PASTE буфер; возврат в режим редактирования. TAB (2-e нажатие)+SHIFT - CUT: отмеченный блок пересылается в CUT/PASTE буфер; возврат в режим редактирования. TAB (2-e нажатие)+CTRL - возврат в режим редактирования. SELECT - транслирует содержимое строчных буферов голосов 1-3 в музыкальную очередь; в каждой из строк трансля- ция прекращается по достижении последнего непробела или символа '%'. В окне музыкальной очереди высвечи- вается информации о длине музыкальной очереди для каждого из голосов и общей длине музыкального фрагмента, а также продолжительность звучания каждого голоса - в тиках и в секундах. Запускает исполнение музыки. CR - play; запускает исполнение музыки, однократно или в цикле. Во время исполнения можно продолжать редактирование. STOP - "выключает" музыку. STOP+SHIFT - приостанавливает/продолжает исполнение музыки. F1-F3,F4 - включает/выключает LFO для голосов 1-3 и шума. Для голосов, в которых включен LFO, подсвечивается соответствующая колонка в строке 'LFO on' окна прямого управления. F5 - устанавливает/сбрасывает признак циклического исполнения. Если установлен признак цикла, на экране появляется подсвеченная надпись 'CYCLE'. F1-F3+SHIFT - включает/выключает шум в голосах 1-3. Для голосов, в которых включен шум, подсвечивается колонка в строке 'Noise on' окна прямого управления. F1-F4+CTRL - меняет форму LFO для голосов 1-3 и шума. <-,->+CTRL - перемещение курсора LFO по строке параметров LFO. В этой строке отображаются текущие значения параметров *a, *t для каждого из голосов и /a, /t, /f для шума. Up+CTRL, Down+CTRL - увеличение или уменьшение параметра LFO, на который указывает курсор LFO. ESC+SHIFT - сброс всех параметров LFO, выключение LFO и шума. ESC - выход из режима редактирования в главное меню. Окно подсказки стирается, музыка выключается. ------------------------------------------------------------------------ Литература. [1] MSX Technical Data Book. [2] Справочное руководство по языку Бейсик для КУВТ Ямаха. ------------------------------------------------------------------------- Приложение. Версии пакета MEDIA. Версия 1.3 - в MML+ добавлен оператор > (указатель начала цикла) - оператор MML+ z сдвигает частоту на n полутонов, а не октав - введен сокращенный (по сравнению с Бейсиком) формат муз. пакетов - не работает функция xmus() - приостановки/продолжения музыки - добавлены в редактор и библиотеку функции работы с шумом: включение/выключение шума и изменение его частоты Версия 1.4 - оператор MML+ > заменен на : - введены операторы комментариев MML+ < > - функция xmus() вновь работает - добавлены функции LFO для шума - 3 страницы HELP Версия 1.5 - добавлены функции LFO ( /\, общее для трех голосов ) Версия 1.6 (внутренняя) - функции LFO трех форм, с разными параметрами для каждого голоса - в редакторе и библиотеке - усовершенствована функция LOAD редактора (загрузка в режиме вставки и не с начала нотной строки) Версия 2.0 - в MML+ добавлены операторы прямого управления PSG (LFO и шум): [, ], {, }, (, ), *a, *t, /a, /t, /f - упорядочен набор функций управления PSG в библиотеке - изменены некоторые клавиши управления редактором - добавлена 4-я страница HELP - введен динамический мониторинг параметров LFO на экране редактора Версия 2.1 - функция lfotick() частично переписана в машинных кодах для ускорения работы - введен операнд функции musini(p) - указатель области глобальных параметров LFO. - добавлена функция play1() - play из версии 1, без LFO