[BACK]Return to MGLAPI.doc CVS log [TXT][DIR] Up to [jp.NetBSD.org] / othersrc / mgl / mgl2

File: [jp.NetBSD.org] / othersrc / mgl / mgl2 / MGLAPI.doc (download)

Revision 1.6, Sat Sep 9 03:42:01 2000 UTC (18 years, 2 months ago) by suz
Branch: MAIN
CVS Tags: ALPHA_018p9, ALPHA_018p10
Changes since 1.5: +11 -10 lines

alpha 018p9

API の説明

#include "mgl2.h"

以下の関数名は、MGL_PREFIX を define するとすべて、mgl_ のプレフィクス
が付きます。

int open_graph(void)
	グラフィック画面を使用可能にします。

	戻り値 1 成功 0 失敗

	グローバル変数を変更することで、いくつかオプションの設定ができます。
 
	SCREEN_WIDTH=xsize
	SCREEN_HEIGHT=ysize 

		希望する画面サイズの指定。
	mgl_apli_type = AT_MAIN or AT_MINIAPLI

		MGLサーバを使ったとき、どちらの領域を使うか指定します。

	戻り値

	SCREEN_WIDTH
	SCREEN_HEIGHT

		実際に割り当てられた画面サイズ


void close_graph(void)

	グラフィック画面の使用を終ります。

void set_color(int col) 

	描画するときの色を指定します。

	色は、COLOR_BLACK:黒 COLOR_DARKGRAY:暗いグレー 
        COLOR_LIGHTGRAY:明るいグレー COLOR_WHITE:白 COLOR_REVERSE:反転

	色調/彩度/明度での指定の仕方。

		#include "mglcol.h"

		set_color(packMC(色調,彩度,明度))
			色調  0 -- 11
			彩度  0 -- 15
			明度  0 -- 15

	関係する機能は、clear_screen , draw_pixel, draw_rect,fill_rect
	,draw_string,draw_font	です。

	設定した色は、pen_color に保存されます。
	
void clear_screen(void)
	全画面を塗りつぶします。

void draw_pixel(int x, int y)
	点を x,y に描画


int draw_line(int x1, int y1, int x2, int y2)
	(x1,y1) から (x2,y2) まで線を引きます。

void draw_rect(int x, int y, int xs, int ys)
	x,y から xs,ys のサイズの箱を書きます。

void fill_rect(int x, int y, int xs, int ys) 
	x,y から xs,ys のサイズの箱を塗りつぶします。

void set_font(int size, int attr)
	フォントサイズと属性を指定します。
	size は、12,16,24 のどれか

		オプションフォントをロードすると 8(8x8) 10(12x10)
		も指定可能です。

	attr は、FA_NORMAL か FA_ITALIC か FA_BOLD かその両方を指定します。

void draw_string(int x, int y, char *str,int dir)

	x,y から、str の文字列を描画します。
	文字コードは、EUC で 半角カナはサポートしていません。
	注意) x,y は、文字の左上の座標です。
 
	dir は方向の指定 
		DIR_NORTH:0 左から右
		DIR_WEST: 下から上
		DIR_SOUTH: 右から左
		DIR_EAST: 上から下
	
void draw_font(int x, int y, int code, int dir) 
	x,y から、code の文字を描画します。
	文字コードは、2バイト文字 (EUC1バイト目 * 256 + EUC2バイト目)
	1バイト文字 (<256) です。
	注意) x,y は、文字の左上の座標です。

        dir には、以下の指定が可能です。
        DIR_NORTH       : 上向き (通常)
        DIR_WEST        : 左 90 度回転
        DIR_SOUTH       : 下向き (180 度回転)
        DIR_EAST        : 右 90 度回転

void bitblt(struct screen *dst, int dx, int dy,
            struct screen *src, int sx, int sy, int xsize, int ysize, int op) 
	dst の dx,dy に src の sx,sy から xsize,ysize のイメージを
	転送します。

	op に、BLT_TILING を指定すると、src は、タイリングされた
	無限に大きなスクリーンと見なされます。

	op に BLT_MASKING+色 を指定すると 指定した色は透明として
	処理します。

        BLT_TILING も BLT_MASKING も指定せず、dx,sxがバイト境界
	(4ドット)における同じ位置の場合に高速化されます。
	(例:縦スクロール,移動量が4の倍数の横スクロール)

	dst に NULL を指定すると、描画に使用しているスクリーンが
	指定されたものとします。

	src に NULL を指定すると、描画に使用しているスクリーンが
	指定されたものとします。

struct screen *create_memscreen(int xs, int ys, char *bitmap,int kind,int op)
	メモリスクリーンを作成します。
	xs,ys でビット単位のサイズを指定します。
	bitmap は、NULL のとき自動作成されます。
	注意) 自動作成されたときのみ free_screen で bitmap も free されます。

	kind には、スクリーンタイプを指定します。

	STK_NATIVE		
	STK_GENERIC_4COLOR
	STK_GENERIC_192COLOR
	STK_GENERIC_FULLCOLOR


	STK_NATIVE は画面と同じタイプ。これを使うと bitblt が早くできます。
	STK_GENERIC_4COLOR は、2bpp メモリを節約できます。
	STK_GENERIC_FULLCOLOR は、16bpp 最大の色情報を保存できます。
	STK_GENERIC_192COLOR は、8bpp 両者の中間になります。

	op は、bitblt 時に指定する op と同じです。
	設定すると、bitblt の指定 より 優先されます。
	生成時に指定した方が性能が良くなる場合があります。


struct screen *create_subscreen(struct screen *org, int x, int y,
                                int xs, int ys)
	org の x,y の位置から、xs,ys のサイズの
	部分スクリーンを作成します。
	部分スクリーンは、org のビットマップをそのまま使用しますので、
	org を free したら使用できません。

	この単位でクリッピングします。(未実装)

void free_screen(struct screen *s)
	create_memscreen かcreate_subscreen で作成したスクリーンを
	free します。

void push_screen(struct screen *s)
	描画するスクリーンを指定するとともに、前のスクリーンをセーブします。

void pop_screen(void)
	描画するスクリーンを元に戻します。

int get_pixel(int x, int y, int op)
	カレントスクリーンの x,y の色を読みます。
	op では、bitblt の op のうち、BLT_MASKKING が指定できます。

	MASK と一致した色は、戻り値が COLOR_TRANSPARENT になります。

	また、FULLCOLOR の場合、読みだした色に COLOR_DITHER ビットが
	立ちます。
	

int put_pixel(int x, int y, int col)
	col で指定した色を 書き込みます。

	COLOR_REVERSE を指定すると反転します。普通明るさだけが反転します。
	また、2 回 呼ぶことにより 色がもとに戻ります。

	COLOR_TRANS_PARENT を指定するとなにもしません。
	COLOR_DITHER ビット を立てると 普通ディザがかかります。

	注意) 普通としたのは、必須かどうかはまだ未定という意味。

get_pixel,put_pixel には、次の派生バージョンがあります。
画像変換/フォント描画などまとめて変換したい場合に使用します。

int get_pixstream(int x, int y, int *buf, int length, int dir,int op)
int put_pixstream(int x, int y, int *buf, int length, int dir)
int put_pixstream_rect(int x, int y, int *buf, int length, int dir,int width)

	int の配列にまとめて 読み描きします。
	putpixstream_rect では、矩形領域が指定できます。

	また、方向を dir で指定できます。
		DIR_NORTH:0 左から右
		DIR_WEST: 下から上
		DIR_SOUTH: 右から左
		DIR_EAST: 上から下

int get_font_width(void)

	font の幅を返します。

int get_font_height(void)

	font の高さを返します。

void   refresh(void)

	画面を強制的に update したとき使います。

	get_key/key_select を呼び出せば、画面は update されますので、
	どうしても必要なときだけ使用してください。

struct textscreen *create_textscreen(struct screen *s, int x, int y,
                                     int xs, int ys, int attr)
	カレントスクリーンの (x,y) から (xs,ys) のサイズの
	textscreen を生成します。

	attr には、
		TS_SAVE		free 時にもとに戻す。
		TS_BORDER	4dot のボーダを付ける。
		TS_BLINE	ボーダを付けたとき line を引く。

	が指定できます。

void free_textscreen(struct textscreen *t)
	textscreen を フリーします。
	TS_SAVE が指定されている場合、イメージを元に戻します。

void ts_clear(struct textscreen *t)
	textscreen を クリアします。

void ts_put_string(struct textscreen *t, char *str, int op)
	ストリングを書きます。op には、0 か 1 が指定でき、
	1 を指定した場合、上書きします。

	注意) イタリックやボールドを設定した場合、上書きオプション
	      でないと文字列がきれいに出力されません。

void ts_goto(struct textscreen *t, int x, int y)
	x,y の位置にカーソルを移動します。

void ts_set_bgcolor(struct textscreen *t, int c) 
	textscreen のバックグラウンドカラーを指定します。
	(デフォルトは、COLOR_WHITE)

void ts_put_image(struct textscreen *t, struct screen *s,
                  int sx, int sy, int w, int h, int op)
	イメージを書きます。

	op には、BLT_TILING と BLT_MASKING+色 が指定できます。

int get_key_im(int timeout)
	IMPUT メソッド付き キー入力

int get_key(int timeout)
	タイムアウト付き キー入力

	timeout は、1/10 秒単位で指定します。
	また、-1 で無制限の意味になります。

	タイムアウト時は、(-1) が戻ります。

int key_select(int nfds, fd_set *readfds, int timeout)
	select の代替機能、

	timeout は、1/1000 秒単位で指定します。
	また、-1 で無制限の意味になります。

	入力用の fd として かならず 0 を指定してください。
	readfds に 0 が セットされて戻った場合、get_key で入力可の
	意味になります。

int load_font(char *fname, int width, int height)
	外部フォントを使用できるようにします。
	( 使用できる外部フォントは、合計2つ
	  12x10, 10x8 フォントを想定しています。)

	fname フォントファイル名、MGLDIR にインストールする必要があります。
	width 漢字フォントの幅(bit)
	height 漢字フォントの高さ(bit)

	フォーマット
		32 バイト ( ヘッダ: 未使用)
		ANK フォント (256 文字分)
		漢字フォント (8064 文字分: 区点コードの順(区*96 + 点))

		フォントのデータは、横のデータ(byte に alignされている)が
		高さ分あるもので、bit の順番は、左端が MSB です。

void write_screen_xpm(char *name, struct screen *s)
	カレントスクリーン全体をダンプします。
	フォーマットは、XPM

void write_screen_mgr(char *name, struct screen *s,int kind)
	カレントスクリーン全体をダンプします。
	フォーマットは、MGL 専用フォーマット
	kind には、
		1: 2bpp
		2: 8bpp
		3: 16bpp
	が指定できます。
	2 および 3 を指定した場合 テキストフォーマットになります。

struct screen *read_screen_mgr(char *name)
	MGR フォーマットのファイル name を読み込み、メモリスクリーンに
	格納して返します。

struct screen * conv_screen_from_mgr(char *buf,int kind)

	文字列版 mgr フォーマット(2 or 3) から screen を生成します。
	kind は、生成したいスクリーンフォーマット

char *conv_screen_to_mgr(struct screen *s,char *buf,int len)
	
	screen から mgr フォーマットに変換します。
	buf が NULL のとき malloc します。
	length は buf を指定したときのサイズ

	s はスクリーン, NULL を指定すると描画スクリーンになります。

struct screen *conv_screen_from_v1(struct screen_v1 *s,int kind)

	MGL1 のスクリーンフォーマットを変換します。
	kind は、生成したいスクリーンタイプ

	注意) MGL1 のスクリーンフォーマットの構造体名は
		struct screen_v1 になりました。

virtual_key --- 設定した矩形領域をクリックすると、定義したキーコード
が発生する機能です。矩形領域は、木構造で定義できます。
キーコードは、実際のキーコードを割り当てても良いですが、
専用のコードも用意されています。(MK_V1,MK_V2 ...)

struct virtual_key;
extern int vk_x,vk_y;

struct virtual_key *create_virtual_key(int x,y,xs,ys,keycode)

	矩形領域と、キーコードを定義する構造体を作ります。
	xs,ys で、矩形領域のサイズを x,y で 位置を指定します。
	x,y の原点は、vk_attach するときの親の矩形領域の左上です。

	コンテナとして使いたい場合は、keycode に、MK_V0 を指定します。

void vk_attach(struct virtual_key *parent,*vk)

	virtual_key を、親の矩形領域にマップします。
	後に vk_attach した vertual_key ほど優先順位が高くなります。

	また、親の矩形領域からはみ出した vertual_key は、意味をなしません。

	parent に NULL を指定した場合、mgl に 登録され、get_key()
	, get_key_im() でキーコードが取得できるようになります。

	また、get_key(),get_key_im() で取得した最後の virtual_key の 
	x,y 座標は、 vk_x,vk_y に格納されます。

void vk_detach(struct virtual_key *vk,int clean_mode)

	virtua_key 構造体を、木構造から外します。
	clean_mode が true の場合は、再帰的に free します。


void mgl_set_key_mode(int mode)

mode に MGL_SK_RAW を指定することで、get_key を RAW モード
にすることができます。

RAW モードでは、get_key() で得られる コードは、ASCII コードではなく、
キーそのものに対応した 7bit の キーコード と 1bit の状態
が 得られます。

例:
	ESC を 押した -> 0x01
	ESC を 離した -> 0x81

元のモードにするには、

mode に MGL_SK_TRANSLATED

を指定します。

また、MGL_SK_EXTRANSLATED を指定すると、
ASCII コード に モデファイヤー情報を付加した値が得られます。

得られるモデファイヤーは、
	MGL_SKM_CAPS
	MGL_SKM_SHIFT
	MGL_SKM_CTRL
	MGL_SKM_ALT
です。

また、モデファイヤーを取り除くには、

~MGL_SKM_MASK で & を取ってください。

例:
	c = get_key(-1);
	val = c & ~MGL_SKM_MASK;
	shift = c & MGL_SKM_SHIFT;

注意) モデファイヤーを単独で押し/離した 場合 
	モディファイヤー情報 | MGL_SKM_NOTICE
      が得られます。MGL_SKM_NOTICE が立っている場合は、キーコードは
      意味を持ちません。


ge_key_im で使われる 入力メソッド(以下 im) とのインターフェイス
単純に get_key_im を呼ぶだけで、変換ウインドウが適当に出ますが
場所を多少コントロールできるようになりました。

void im_avoid_point(int x,int y,int clean)

im に対し、避けて欲しい矩形領域を通知します。
いままでの設定をリセットしたいときは、clean を 1 にします。

次のプライオリティで場所を決定します。

設定した領域の右に出せるとき  -> 近接して右
設定した領域の下に出せるとき  -> 近接して下
設定した領域の上に出せるとき  -> 近接して上

この設定は im が無視する場合があります。

例
	mgterm では、カーソルのある場所を通知しています。

void im_impart_point(int x,int y,int clean)

im に対し、常に使ってよい場所を通知します。
いままでの設定をリセットしたいときは、clean を 1 にします。

int im_view_point(int xs,int ys,int *xp,int *yp);

im が使う API です。
使いたい領域を xs,ys に設定して呼ぶと *xp,*yp に その領域の
開始点(左上)を返します。

戻り値
	0 強制的に場所を割り当てた。
	1 避けるべきところを避けた。
	2 割り当ててもらった領域内。



スクリーン指定関数群

以下の関数は、第一引数に screen を指定します。
対象が current_screen から指定した screen に変更になる以外は、
上記 prefix なし関数と同じ動作をします。

void mgl2_clear_screen(struct screen *s);
void mgl2_put_pixel(struct screen *s,int x, int y, int col);
int mgl2_get_pixel(struct screen *s,int x, int y, int op);
void mgl2_get_pixstream(struct screen *s,int x, int y,int *buf,int length,int dir,int op);
void mgl2_put_pixstream(struct screen *s,int x, int y,int *buf,int length,int dir);
void mgl2_put_pixstream_rect(struct screen *s,int x, int y,int *buf,int length,int dir,int op);
void mgl2_set_color(struct screen *s,int col);
void mgl2_draw_pixel(struct screen *s,int x, int y);
int mgl2_draw_line(struct screen *s,int x1, int y1, int x2, int y2);
void mgl2_draw_rect(struct screen *s,int x, int y, int xs, int ys);
void mgl2_fill_rect(struct screen *s,int x, int y, int xs, int ys);
void mgl2_set_font(struct screen *s,int size,int type);
void mgl2_draw_font(struct screen *s,int x, int y, int code, int dir);
void mgl2_draw_string(struct screen *s,int x, int y, char *str, int dir);

-------- MGL1 から削除

	draw_pixel_wc
		get_pixel に変更されました。
		# define されているので使えないことはないです。

	draw_font_clipping
		クリッピングは汎用機能として提供されました。


-------- 引数が追加変更されたもの

	draw_font
	draw_string
	create_memscreen

	追加分は、0 を埋めれば互換になります。

-------- オプション
	write_screen_xpm
	conv_screen_from_xpm
	write_screen_native

---------- 追加/変更 予定のもの

	1. screen 指定 API 。(結局 追加しました。)

	2. virtual_key  多分 API が少し変わります。

---- ここでおしまい。