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

Annotation of othersrc/mgl/mgl2/MGLAPI.doc, Revision 1.6

1.1       suz         1: API の説明
                      2:
                      3: #include "mgl2.h"
                      4:
                      5: 以下の関数名は、MGL_PREFIX を define するとすべて、mgl_ のプレフィクス
                      6: が付きます。
                      7:
                      8: int open_graph(void)
                      9:        グラフィック画面を使用可能にします。
                     10:
                     11:        戻り値 1 成功 0 失敗
                     12:
                     13:        グローバル変数を変更することで、いくつかオプションの設定ができます。
                     14:
                     15:        SCREEN_WIDTH=xsize
                     16:        SCREEN_HEIGHT=ysize
                     17:
                     18:                希望する画面サイズの指定。
                     19:        mgl_apli_type = AT_MAIN or AT_MINIAPLI
                     20:
                     21:                MGLサーバを使ったとき、どちらの領域を使うか指定します。
                     22:
                     23:        戻り値
                     24:
                     25:        SCREEN_WIDTH
                     26:        SCREEN_HEIGHT
                     27:
                     28:                実際に割り当てられた画面サイズ
                     29:
                     30:
                     31: void close_graph(void)
                     32:
                     33:        グラフィック画面の使用を終ります。
                     34:
                     35: void set_color(int col)
                     36:
                     37:        描画するときの色を指定します。
                     38:
                     39:        色は、COLOR_BLACK:黒 COLOR_DARKGRAY:暗いグレー
                     40:         COLOR_LIGHTGRAY:明るいグレー COLOR_WHITE:白 COLOR_REVERSE:反転
                     41:
                     42:        色調/彩度/明度での指定の仕方。
                     43:
                     44:                #include "mglcol.h"
                     45:
                     46:                set_color(packMC(色調,彩度,明度))
                     47:                        色調  0 -- 11
                     48:                        彩度  0 -- 15
                     49:                        明度  0 -- 15
                     50:
                     51:        関係する機能は、clear_screen , draw_pixel, draw_rect,fill_rect
                     52:        ,draw_string,draw_font  です。
                     53:
                     54:        設定した色は、pen_color に保存されます。
                     55:
                     56: void clear_screen(void)
                     57:        全画面を塗りつぶします。
                     58:
                     59: void draw_pixel(int x, int y)
                     60:        点を x,y に描画
                     61:
                     62:
                     63: int draw_line(int x1, int y1, int x2, int y2)
                     64:        (x1,y1) から (x2,y2) まで線を引きます。
                     65:
                     66: void draw_rect(int x, int y, int xs, int ys)
                     67:        x,y から xs,ys のサイズの箱を書きます。
                     68:
                     69: void fill_rect(int x, int y, int xs, int ys)
                     70:        x,y から xs,ys のサイズの箱を塗りつぶします。
                     71:
                     72: void set_font(int size, int attr)
                     73:        フォントサイズと属性を指定します。
                     74:        size は、12,16,24 のどれか
                     75:
                     76:                オプションフォントをロードすると 8(8x8) 10(12x10)
                     77:                も指定可能です。
                     78:
                     79:        attr は、FA_NORMAL か FA_ITALIC か FA_BOLD かその両方を指定します。
                     80:
                     81: void draw_string(int x, int y, char *str,int dir)
                     82:
                     83:        x,y から、str の文字列を描画します。
                     84:        文字コードは、EUC で 半角カナはサポートしていません。
                     85:        注意) x,y は、文字の左上の座標です。
                     86:
                     87:        dir は方向の指定
                     88:                DIR_NORTH:0 左から右
                     89:                DIR_WEST: 下から上
                     90:                DIR_SOUTH: 右から左
                     91:                DIR_EAST: 上から下
                     92:
                     93: void draw_font(int x, int y, int code, int dir)
                     94:        x,y から、code の文字を描画します。
                     95:        文字コードは、2バイト文字 (EUC1バイト目 * 256 + EUC2バイト目)
                     96:        1バイト文字 (<256) です。
                     97:        注意) x,y は、文字の左上の座標です。
                     98:
                     99:         dir には、以下の指定が可能です。
                    100:         DIR_NORTH       : 上向き (通常)
                    101:         DIR_WEST        : 左 90 度回転
                    102:         DIR_SOUTH       : 下向き (180 度回転)
                    103:         DIR_EAST        : 右 90 度回転
                    104:
                    105: void bitblt(struct screen *dst, int dx, int dy,
                    106:             struct screen *src, int sx, int sy, int xsize, int ysize, int op)
                    107:        dst の dx,dy に src の sx,sy から xsize,ysize のイメージを
                    108:        転送します。
                    109:
                    110:        op に、BLT_TILING を指定すると、src は、タイリングされた
                    111:        無限に大きなスクリーンと見なされます。
                    112:
                    113:        op に BLT_MASKING+色 を指定すると 指定した色は透明として
                    114:        処理します。
                    115:
                    116:         BLT_TILING も BLT_MASKING も指定せず、dx,sxがバイト境界
                    117:        (4ドット)における同じ位置の場合に高速化されます。
                    118:        (例:縦スクロール,移動量が4の倍数の横スクロール)
                    119:
                    120:        dst に NULL を指定すると、描画に使用しているスクリーンが
                    121:        指定されたものとします。
                    122:
                    123:        src に NULL を指定すると、描画に使用しているスクリーンが
                    124:        指定されたものとします。
                    125:
                    126: struct screen *create_memscreen(int xs, int ys, char *bitmap,int kind,int op)
                    127:        メモリスクリーンを作成します。
                    128:        xs,ys でビット単位のサイズを指定します。
                    129:        bitmap は、NULL のとき自動作成されます。
                    130:        注意) 自動作成されたときのみ free_screen で bitmap も free されます。
                    131:
                    132:        kind には、スクリーンタイプを指定します。
                    133:
                    134:        STK_NATIVE
                    135:        STK_GENERIC_4COLOR
                    136:        STK_GENERIC_192COLOR
                    137:        STK_GENERIC_FULLCOLOR
                    138:
                    139:
                    140:        STK_NATIVE は画面と同じタイプ。これを使うと bitblt が早くできます。
                    141:        STK_GENERIC_4COLOR は、2bpp メモリを節約できます。
                    142:        STK_GENERIC_FULLCOLOR は、16bpp 最大の色情報を保存できます。
                    143:        STK_GENERIC_192COLOR は、8bpp 両者の中間になります。
                    144:
                    145:        op は、bitblt 時に指定する op と同じです。
                    146:        設定すると、bitblt の指定 より 優先されます。
                    147:        生成時に指定した方が性能が良くなる場合があります。
                    148:
                    149:
                    150: struct screen *create_subscreen(struct screen *org, int x, int y,
                    151:                                 int xs, int ys)
                    152:        org の x,y の位置から、xs,ys のサイズの
                    153:        部分スクリーンを作成します。
                    154:        部分スクリーンは、org のビットマップをそのまま使用しますので、
                    155:        org を free したら使用できません。
                    156:
                    157:        この単位でクリッピングします。(未実装)
                    158:
                    159: void free_screen(struct screen *s)
                    160:        create_memscreen かcreate_subscreen で作成したスクリーンを
                    161:        free します。
                    162:
                    163: void push_screen(struct screen *s)
                    164:        描画するスクリーンを指定するとともに、前のスクリーンをセーブします。
                    165:
                    166: void pop_screen(void)
                    167:        描画するスクリーンを元に戻します。
                    168:
                    169: int get_pixel(int x, int y, int op)
                    170:        カレントスクリーンの x,y の色を読みます。
                    171:        op では、bitblt の op のうち、BLT_MASKKING が指定できます。
                    172:
                    173:        MASK と一致した色は、戻り値が COLOR_TRANSPARENT になります。
                    174:
                    175:        また、FULLCOLOR の場合、読みだした色に COLOR_DITHER ビットが
                    176:        立ちます。
                    177:
                    178:
                    179: int put_pixel(int x, int y, int col)
                    180:        col で指定した色を 書き込みます。
                    181:
                    182:        COLOR_REVERSE を指定すると反転します。普通明るさだけが反転します。
                    183:        また、2 回 呼ぶことにより 色がもとに戻ります。
                    184:
                    185:        COLOR_TRANS_PARENT を指定するとなにもしません。
                    186:        COLOR_DITHER ビット を立てると 普通ディザがかかります。
                    187:
                    188:        注意) 普通としたのは、必須かどうかはまだ未定という意味。
                    189:
                    190: get_pixel,put_pixel には、次の派生バージョンがあります。
                    191: 画像変換/フォント描画などまとめて変換したい場合に使用します。
                    192:
                    193: int get_pixstream(int x, int y, int *buf, int length, int dir,int op)
                    194: int put_pixstream(int x, int y, int *buf, int length, int dir)
                    195: int put_pixstream_rect(int x, int y, int *buf, int length, int dir,int width)
                    196:
                    197:        int の配列にまとめて 読み描きします。
                    198:        putpixstream_rect では、矩形領域が指定できます。
                    199:
                    200:        また、方向を dir で指定できます。
                    201:                DIR_NORTH:0 左から右
                    202:                DIR_WEST: 下から上
                    203:                DIR_SOUTH: 右から左
                    204:                DIR_EAST: 上から下
                    205:
                    206: int get_font_width(void)
                    207:
                    208:        font の幅を返します。
                    209:
                    210: int get_font_height(void)
                    211:
                    212:        font の高さを返します。
                    213:
                    214: void   refresh(void)
                    215:
                    216:        画面を強制的に update したとき使います。
                    217:
                    218:        get_key/key_select を呼び出せば、画面は update されますので、
                    219:        どうしても必要なときだけ使用してください。
                    220:
                    221: struct textscreen *create_textscreen(struct screen *s, int x, int y,
                    222:                                      int xs, int ys, int attr)
                    223:        カレントスクリーンの (x,y) から (xs,ys) のサイズの
                    224:        textscreen を生成します。
                    225:
                    226:        attr には、
                    227:                TS_SAVE         free 時にもとに戻す。
                    228:                TS_BORDER       4dot のボーダを付ける。
                    229:                TS_BLINE        ボーダを付けたとき line を引く。
                    230:
                    231:        が指定できます。
                    232:
                    233: void free_textscreen(struct textscreen *t)
                    234:        textscreen を フリーします。
                    235:        TS_SAVE が指定されている場合、イメージを元に戻します。
                    236:
                    237: void ts_clear(struct textscreen *t)
                    238:        textscreen を クリアします。
                    239:
                    240: void ts_put_string(struct textscreen *t, char *str, int op)
                    241:        ストリングを書きます。op には、0 か 1 が指定でき、
                    242:        1 を指定した場合、上書きします。
                    243:
1.2       suz       244:        注意) イタリックやボールドを設定した場合、上書きオプション
                    245:              でないと文字列がきれいに出力されません。
                    246:
1.1       suz       247: void ts_goto(struct textscreen *t, int x, int y)
                    248:        x,y の位置にカーソルを移動します。
                    249:
                    250: void ts_set_bgcolor(struct textscreen *t, int c)
                    251:        textscreen のバックグラウンドカラーを指定します。
                    252:        (デフォルトは、COLOR_WHITE)
                    253:
                    254: void ts_put_image(struct textscreen *t, struct screen *s,
                    255:                   int sx, int sy, int w, int h, int op)
                    256:        イメージを書きます。
                    257:
                    258:        op には、BLT_TILING と BLT_MASKING+色 が指定できます。
                    259:
                    260: int get_key_im(int timeout)
                    261:        IMPUT メソッド付き キー入力
                    262:
                    263: int get_key(int timeout)
                    264:        タイムアウト付き キー入力
                    265:
                    266:        timeout は、1/10 秒単位で指定します。
                    267:        また、-1 で無制限の意味になります。
                    268:
                    269:        タイムアウト時は、(-1) が戻ります。
                    270:
                    271: int key_select(int nfds, fd_set *readfds, int timeout)
                    272:        select の代替機能、
                    273:
                    274:        timeout は、1/1000 秒単位で指定します。
                    275:        また、-1 で無制限の意味になります。
                    276:
                    277:        入力用の fd として かならず 0 を指定してください。
                    278:        readfds に 0 が セットされて戻った場合、get_key で入力可の
                    279:        意味になります。
                    280:
                    281: int load_font(char *fname, int width, int height)
                    282:        外部フォントを使用できるようにします。
                    283:        ( 使用できる外部フォントは、合計2つ
                    284:          12x10, 10x8 フォントを想定しています。)
                    285:
                    286:        fname フォントファイル名、MGLDIR にインストールする必要があります。
                    287:        width 漢字フォントの幅(bit)
                    288:        height 漢字フォントの高さ(bit)
                    289:
                    290:        フォーマット
                    291:                32 バイト ( ヘッダ: 未使用)
                    292:                ANK フォント (256 文字分)
                    293:                漢字フォント (8064 文字分: 区点コードの順(区*96 + 点))
                    294:
                    295:                フォントのデータは、横のデータ(byte に alignされている)が
                    296:                高さ分あるもので、bit の順番は、左端が MSB です。
                    297:
                    298: void write_screen_xpm(char *name, struct screen *s)
                    299:        カレントスクリーン全体をダンプします。
                    300:        フォーマットは、XPM
                    301:
                    302: void write_screen_mgr(char *name, struct screen *s,int kind)
                    303:        カレントスクリーン全体をダンプします。
                    304:        フォーマットは、MGL 専用フォーマット
                    305:        kind には、
                    306:                1: 2bpp
                    307:                2: 8bpp
                    308:                3: 16bpp
                    309:        が指定できます。
                    310:        2 および 3 を指定した場合 テキストフォーマットになります。
                    311:
                    312: struct screen *read_screen_mgr(char *name)
                    313:        MGR フォーマットのファイル name を読み込み、メモリスクリーンに
                    314:        格納して返します。
                    315:
                    316: struct screen * conv_screen_from_mgr(char *buf,int kind)
                    317:
                    318:        文字列版 mgr フォーマット(2 or 3) から screen を生成します。
                    319:        kind は、生成したいスクリーンフォーマット
                    320:
                    321: char *conv_screen_to_mgr(struct screen *s,char *buf,int len)
                    322:
                    323:        screen から mgr フォーマットに変換します。
                    324:        buf が NULL のとき malloc します。
                    325:        length は buf を指定したときのサイズ
                    326:
                    327:        s はスクリーン, NULL を指定すると描画スクリーンになります。
                    328:
                    329: struct screen *conv_screen_from_v1(struct screen_v1 *s,int kind)
                    330:
                    331:        MGL1 のスクリーンフォーマットを変換します。
                    332:        kind は、生成したいスクリーンタイプ
                    333:
                    334:        注意) MGL1 のスクリーンフォーマットの構造体名は
                    335:                struct screen_v1 になりました。
                    336:
                    337: virtual_key --- 設定した矩形領域をクリックすると、定義したキーコード
                    338: が発生する機能です。矩形領域は、木構造で定義できます。
                    339: キーコードは、実際のキーコードを割り当てても良いですが、
                    340: 専用のコードも用意されています。(MK_V1,MK_V2 ...)
                    341:
                    342: struct virtual_key;
                    343: extern int vk_x,vk_y;
                    344:
                    345: struct virtual_key *create_virtual_key(int x,y,xs,ys,keycode)
                    346:
                    347:        矩形領域と、キーコードを定義する構造体を作ります。
                    348:        xs,ys で、矩形領域のサイズを x,y で 位置を指定します。
                    349:        x,y の原点は、vk_attach するときの親の矩形領域の左上です。
                    350:
                    351:        コンテナとして使いたい場合は、keycode に、MK_V0 を指定します。
                    352:
                    353: void vk_attach(struct virtual_key *parent,*vk)
                    354:
                    355:        virtual_key を、親の矩形領域にマップします。
                    356:        後に vk_attach した vertual_key ほど優先順位が高くなります。
                    357:
                    358:        また、親の矩形領域からはみ出した vertual_key は、意味をなしません。
                    359:
                    360:        parent に NULL を指定した場合、mgl に 登録され、get_key()
                    361:        , get_key_im() でキーコードが取得できるようになります。
                    362:
                    363:        また、get_key(),get_key_im() で取得した最後の virtual_key の
                    364:        x,y 座標は、 vk_x,vk_y に格納されます。
                    365:
                    366: void vk_detach(struct virtual_key *vk,int clean_mode)
                    367:
                    368:        virtua_key 構造体を、木構造から外します。
                    369:        clean_mode が true の場合は、再帰的に free します。
                    370:
                    371:
1.5       suz       372: void mgl_set_key_mode(int mode)
                    373:
                    374: mode に MGL_SK_RAW を指定することで、get_key を RAW モード
                    375: にすることができます。
                    376:
                    377: RAW モードでは、get_key() で得られる コードは、ASCII コードではなく、
                    378: キーそのものに対応した 7bit の キーコード と 1bit の状態
                    379: が 得られます。
                    380:
                    381: 例:
                    382:        ESC を 押した -> 0x01
                    383:        ESC を 離した -> 0x81
                    384:
                    385: 元のモードにするには、
                    386:
                    387: mode に MGL_SK_TRANSLATED
                    388:
                    389: を指定します。
                    390:
1.6     ! suz       391: また、MGL_SK_EXTRANSLATED を指定すると、
1.5       suz       392: ASCII コード に モデファイヤー情報を付加した値が得られます。
                    393:
                    394: 得られるモデファイヤーは、
1.6     ! suz       395:        MGL_SKM_CAPS
1.5       suz       396:        MGL_SKM_SHIFT
                    397:        MGL_SKM_CTRL
                    398:        MGL_SKM_ALT
1.6     ! suz       399: です。
1.5       suz       400:
                    401: また、モデファイヤーを取り除くには、
                    402:
1.6     ! suz       403: ~MGL_SKM_MASK で & を取ってください。
1.5       suz       404:
                    405: 例:
                    406:        c = get_key(-1);
1.6     ! suz       407:        val = c & ~MGL_SKM_MASK;
1.5       suz       408:        shift = c & MGL_SKM_SHIFT;
1.2       suz       409:
1.6     ! suz       410: 注意) モデファイヤーを単独で押し/離した 場合
        !           411:        モディファイヤー情報 | MGL_SKM_NOTICE
        !           412:       が得られます。MGL_SKM_NOTICE が立っている場合は、キーコードは
        !           413:       意味を持ちません。
        !           414:
        !           415:
1.2       suz       416: ge_key_im で使われる 入力メソッド(以下 im) とのインターフェイス
                    417: 単純に get_key_im を呼ぶだけで、変換ウインドウが適当に出ますが
                    418: 場所を多少コントロールできるようになりました。
                    419:
                    420: void im_avoid_point(int x,int y,int clean)
                    421:
                    422: im に対し、避けて欲しい矩形領域を通知します。
                    423: いままでの設定をリセットしたいときは、clean を 1 にします。
                    424:
                    425: 次のプライオリティで場所を決定します。
                    426:
                    427: 設定した領域の右に出せるとき  -> 近接して右
                    428: 設定した領域の下に出せるとき  -> 近接して下
                    429: 設定した領域の上に出せるとき  -> 近接して上
                    430:
                    431: この設定は im が無視する場合があります。
                    432:
                    433: 例
                    434:        mgterm では、カーソルのある場所を通知しています。
                    435:
                    436: void im_impart_point(int x,int y,int clean)
                    437:
                    438: im に対し、常に使ってよい場所を通知します。
                    439: いままでの設定をリセットしたいときは、clean を 1 にします。
                    440:
                    441: int im_view_point(int xs,int ys,int *xp,int *yp);
                    442:
                    443: im が使う API です。
                    444: 使いたい領域を xs,ys に設定して呼ぶと *xp,*yp に その領域の
                    445: 開始点(左上)を返します。
                    446:
                    447: 戻り値
                    448:        0 強制的に場所を割り当てた。
                    449:        1 避けるべきところを避けた。
                    450:        2 割り当ててもらった領域内。
                    451:
1.4       suz       452:
                    453:
                    454: スクリーン指定関数群
                    455:
                    456: 以下の関数は、第一引数に screen を指定します。
                    457: 対象が current_screen から指定した screen に変更になる以外は、
                    458: 上記 prefix なし関数と同じ動作をします。
                    459:
                    460: void mgl2_clear_screen(struct screen *s);
                    461: void mgl2_put_pixel(struct screen *s,int x, int y, int col);
                    462: int mgl2_get_pixel(struct screen *s,int x, int y, int op);
                    463: void mgl2_get_pixstream(struct screen *s,int x, int y,int *buf,int length,int dir,int op);
                    464: void mgl2_put_pixstream(struct screen *s,int x, int y,int *buf,int length,int dir);
                    465: void mgl2_put_pixstream_rect(struct screen *s,int x, int y,int *buf,int length,int dir,int op);
                    466: void mgl2_set_color(struct screen *s,int col);
                    467: void mgl2_draw_pixel(struct screen *s,int x, int y);
                    468: int mgl2_draw_line(struct screen *s,int x1, int y1, int x2, int y2);
                    469: void mgl2_draw_rect(struct screen *s,int x, int y, int xs, int ys);
                    470: void mgl2_fill_rect(struct screen *s,int x, int y, int xs, int ys);
                    471: void mgl2_set_font(struct screen *s,int size,int type);
                    472: void mgl2_draw_font(struct screen *s,int x, int y, int code, int dir);
                    473: void mgl2_draw_string(struct screen *s,int x, int y, char *str, int dir);
                    474:
1.1       suz       475: -------- MGL1 から削除
1.3       suz       476:
1.1       suz       477:        draw_pixel_wc
                    478:                get_pixel に変更されました。
1.3       suz       479:                # define されているので使えないことはないです。
1.1       suz       480:
                    481:        draw_font_clipping
1.3       suz       482:                クリッピングは汎用機能として提供されました。
1.1       suz       483:
                    484:
                    485: -------- 引数が追加変更されたもの
                    486:
                    487:        draw_font
                    488:        draw_string
                    489:        create_memscreen
                    490:
                    491:        追加分は、0 を埋めれば互換になります。
                    492:
                    493: -------- オプション
                    494:        write_screen_xpm
                    495:        conv_screen_from_xpm
                    496:        write_screen_native
                    497:
                    498: ---------- 追加/変更 予定のもの
                    499:
1.4       suz       500:        1. screen 指定 API 。(結局 追加しました。)
1.3       suz       501:
1.2       suz       502:        2. virtual_key  多分 API が少し変わります。
1.1       suz       503:
1.3       suz       504: ---- ここでおしまい。

CVSweb <webmaster@jp.NetBSD.org>