<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book>
<bookinfo>

<title>Scanner-logiscan</title>
<author>
 <firstname>Andreas</firstname>
 <surname>Beck</surname>
 <affiliation>
  <address>becka@sunserver1.rz.uni-duesseldorf.de</address>
 </affiliation>
</author>

<author>
<firstname>川岸良治 - 日本語訳</firstname>
<surname></surname>
<affiliation>
 <address>kawagisi@yk.rim.or.jp</address>
</affiliation>
</author>

<pubdate>1995/02/14</pubdate>

<revhistory>
 <revision>
 <revnumber>v0.0.4j</revnumber>
 <date>1997年11月15日</date>
 <revremark>この翻訳のリリース</revremark>
 </revision>

 <revision>
 <revnumber>v0.0.4</revnumber>
 <date>1995年2月14日</date>
 <revremark>logiscan-0.0.4 パッケージのリリース</revremark>
 </revision>
</revhistory>

<abstract><para>
LOGITECH SCANMAN+ 400dpi ハンドヘルドスキャナ用ドライバ "logiscan v0.0.4" 
に付属のドキュメント類
</para></abstract>

</bookinfo>


<preface id="aboutthis"><title>この文書について</title>
<abstract><para>
  LOGITECH SCANMAN+ 400 dpi handheld scanner driver  version 0.0.4
</para></abstract>

<para>
  このドキュメントは、 LOGITECH SCANMAN+ 400 dpi ハンドヘルドスキャナ用ドラ
  イバ  Version 0.0.4 に付属のドキュメントを作者 Andreas Beck
  &lt;becka@sunserver1.rz.uni-duesseldorf.de&gt; の許可を得て翻訳したものです。
</para><para>
<literallayout>
  第１部  元のファイル名： README
          ファイルの日付： Feb 14  1995
          作者          ： Andreas Beck
  第２部  元のファイル名： README.ioctl
          ファイルの日付： Dec 24  1994
          作者          ： Andreas Beck
  第３部  demo ディレクトリの中の README
          ファイルの日付： Nov 21  1994
          作者          ： Andreas Beck

  作成日 ： 1997年11月15日
  翻訳者 ： 川岸 良治  &lt;kawagisi@yk.rim.or.jp&gt;
</literallayout>
</para>

<para>
【訳注1】ファイルの入手と展開
</para>
<para>
    このソフト(logiscan0.0.4) は下記から入手できます。

<itemizedlist>
<listitem><para>
<ulink url="ftp://tsx-11.mit.edu/pub/linux/ALPHA/scanner/">
ftp://tsx-11.mit.edu/pub/linux/ALPHA/scanner/</ulink>
</para></listitem>
</itemizedlist>

これをダウンロードしたら次のようにして <filename>/usr/src/</filename> 
ディレクトリに展開します。
</para><para>

<screen>
  # cd  /usr/src
  # tar xvfz ~/logiscan-x.x.tar.gz
</screen>

</para><para>
(上記は <filename>logiscan-x.x.tar.gz</filename> が、<filename>~/
</filename> ディレクトリにある場合ですが、それ以外の
時はそのディレクトリに合わせて変えて下さい)
<filename>/usr/src/logiscan-x.x/</filename> ディレクトリが作られ、
そこにファイルが展開されます。
<filename>logiscan-0.0.4.tar.gz</filename> 
には下記のようなドキュメントファイルが入っています。
</para><para>
<screen>
    (1) README 
    (2) README.ioctl (logi32.o によって提供される ioctl インタフェースを使う
                      アプリケーション開発者のガイドライン)
    (3) CHANGELOG    (変更履歴)
    (4) CREDITS      (このプログラムの作成に協力した人の一覧)
    (5) COPYING      (GNU GENERAL PUBLIC LICENSE  Version 2, June 1991)
    (6) demo ディレクトリの中の README 
</screen>
</para><para>
    この文書 Scanner-HOWTO-logiscan は、上記のうち (1) (2) (6) を訳した
    ものです。 (3) (4) (5) は原文をご覧下さい。
</para>

<para>
【訳注2】最新版とメールアドレス
</para>
<para>
    最新版は、logiscan0.0.5 で下記からダウンロードできます。

<itemizedlist>
<listitem><para>
<ulink url="http://sunserver1.rz.uni-duesseldorf.de/~becka">
http://sunserver1.rz.uni-duesseldorf.de/~becka</ulink>
</para></listitem>
</itemizedlist>

    作者へのメールはアドレスが変更されていますので注意して下さい。
<screen>
  (旧)  becka@hp.rz.uni-duesseldorf.de
  (新)  becka@sunserver1.rz.uni-duesseldorf.de
</screen>

    ここで訳した３つドキュメント自体は 0.0.4 と 0.0.5 で変更が無く、全く同じ
    のようです。作者のメールアドレスは、0.0.5 でも古いままなので要注意です。
</para>

</preface>


<!--##################### chapter 1 README ##########################-->
<!--#################################################################-->

<!--
==============================================================================
第１部  README
==============================================================================
-->

<chapter id="readme">
<title><filename>README</filename></title>

<sect1 id="c1-legal">
<title>Copyright</title>
<para>
<literallayout>
Copyright (C) 1994  Andreas Beck &lt;becka@hp.rz.uni-duesseldorf.de&gt;
【訳注】現在のアドレスは、becka@sunserver1.rz.uni-duesseldorf.de
</literallayout>

</para><para>
    このプログラムはフリーソフトウェアです。あなたは、これを Free Software
    Foundation が発行している GNU General Public License のライセンスのバージ
    ョン２、または(あなたのオプションで)それ以降の条件に従って再配布したり変
    更することができます。
</para><para>
    このプログラムは、役に立つことを期待して配布しています。しかし、いかなる
    保証もありません。商品性や特定用途への適合性についての暗黙の保証すらあり
    ません。詳しくは、GNU の General Public License をご覧下さい。 
</para><para>
    あなたは、このプログラムと一緒に GNU General Public License のコピーを受
    け取るべきです。そうでないならば、
    Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
    に手紙を書いて下さい。
</para>
</sect1>

<sect1 id="c1-introduction">
<title>はじめに</title>
<para>
Hi folks!
</para><para>
これは LOGITECH SCANMAN+ スキャナ用のドライバで、専用のインタフェース
ボードを通してドライブされます。このスキャナにはいくつかのバージョンが
ありますが、このドライバは少なくともそれらのいくつかをサポートします。

<orderedlist>
<listitem><para>
   古い Logitech Scanman : 200dpi 固定の白黒スキャナ
   (どなたかこれをお持ちですか？ これはディザ処理ができますか？
    今のところこれは解像度固定で Scanman32 として扱われます)
</para></listitem>
<listitem><para>
   少し新しい Logitech Scanman32 (aka Scanman+) :
   白黒の 100〜400 dpi のスキャナで、 6x6 ディザ処理(解像度を 1/6 に下げて
   37色にする)が可能。 
</para></listitem>
<listitem><para>
   Logitech Scanman256 :
</para><para>
   100〜400 dpi の グレイスケール・スキャナで、ディザ処理無しで 
   1bit(白黒２値), 4bit(16階調), 6bit(64階調), 8bit(256階調)の解像度が
   あります。
   このタイプのスキャナには注意して下さい旭既に述べたようにこれにはいくつか
   のバージョンがあります(異なったハードウェアを使用しています)。
   ある人が私にこの Rev-03 ボードの扱い方を教えてくれたので、この問題は
   現在ではフィックスされていると思うのですが、もしかして他のものがあった
   としたら...
   従ってドライバが "<computeroutput>incompatible scanner-interface
   </computeroutput>" と報告してきたら
   それは別の互換性の無いボードであるか、あるいはベース I／O アドレスの設定
   が間違っています。このような時は、あなたのスキャナ・ソフトウェア・ディス
   クに入っている <filename>HHSCAND.SYS</filename> を私に送って下さい。
</para><para>
  ドライバは <command>insmod</command> を使ってロードする時にスキャナのタイプ
  を自動検出します。
</para><para>
  ドライバが "Unknown" とレポートするがスキャナは動作するという場合 (これは
  code-tweaking が必要ですが...)、あなたのハードウェアをどのようにして検出
  するかを見つけるよう試して、どのような変更が必要かを私に教えて下さい。
  私は、あなたのパッチを今後のリリースに入れるようにします。 
  全てを変更するようなパッチを私に送らないで下さい。即ち、私は現在のものから
  本当に異なるものを扱うようなスキャナはサポートしません。
</para><para>
  このドライバはスキャナに付属の MS-LOSS 用スキャナドライバ
<footnote><para>
【訳注】 MS-LOSS というのは、タイプミスではないと思います。(^_^)
</para></footnote>
  を逆アセンブル
  して集めた情報を元にしています。これ以外の追加情報、要望、提案、バグ報告
  があれば、遠慮無く私に言って下さい。(下記のバグ報告をご覧下さい)
  私は特に、他のスキャナ・デバイスドライバを書く人からのフィードバックを
  得ることに興味があります。
</para><para>
  私たちは Linux の全てのスキャナドライバに使われるインタフェースを一つに
  まとめることができるかもしれません。そうなれば多くの人達が書くであろう、
  カラフルな X ベースのスキャナプログラムが、多くのスキャナでサポートされ
  動作するようになるでしょう。
</para><para>
  私は既に M105 と A4-tech ドライバの作者とは連絡済みで、私たちはスキャナオ
  プション用の ioctl の"万能"セットの設定にトライしています。
  あなたがこの作業に参加することに興味があるなら(あなたはこのような API の
  経験があるかもしれない) <link linkend="readme.ioctl">README.ioctl</link> を
  読み、私(または Thomas または Michael
  下記参照)に送って下さい。
</para><para>
  また、あなたが素敵なスキャナプログラムを書いたら私に送って下さい。
</para></listitem>
</orderedlist>
</para>
</sect1>

<sect1 id="c1-install">
<title>インストールの方法</title>
<para>

<orderedlist>

<listitem><para>
	   ドライバは、カーネル・ローダブル・モジュールなので、明らかに最初に
           するべきことは `modutils' パッケージを持っていない場合はこれを入手し
           インストールすることです。
</para></listitem>

<listitem><para>
	   <filename>src</filename> ディレクトリに移って <filename>logi32.h
           </filename> の先頭を見て下さい。
           必要に応じて、またハードウェア設定に応じて定義を編集します。
           IOBASE だけはディップスイッチの設定に合わせなければいけませんが、
           IRQ と DMA はソフトウェアで選択可能です。
           IRQ と DMA は他のハードウェアによって使われていないものを使って下さ
           い。(SoundBlaster がインストールされているなら DMA 1 は使われている
           と思います)
</para><para>
           設定できるものは IRQ が 2(9),3,4,5,7,9(2),11,12 で、DMA が 1 または
           3 です。最新のカーネル(スタックドモジュールをサポートしている)と、
           対応した modutils では、モジュールのロード時にこれらの値(と、メジ
           ャーデバイス番号。4)項参照 )を変更することができます。
           これをどのようにするのかは、"<command>man insmod</command>" で
           調べて下さい。
           関係のある変数は <filename>logi32.c</filename> の先頭、または
           ドライバを常駐させた時に
           ksyms の出力の中で見つかります。
</para></listitem>

<listitem><para>
	   <filename>scanner.h</filename> をどこか適当な場所(<filename>
           usr/local/include</filename> がお勧め)に移して
           下さい。<filename>scanner.h</filename> は あなたのシステム上で 
           "ただ一つのバージョン"
           で提供されているのだということをよく覚えておいて下さい。
           私は、ドライバがスキャナソフトウェアではない他の <filename>
           scanner.h</filename> とコンパイルされた時のトラブルを沢山聞いて
           います。
</para><para>
           PINT (UNIX 用の共通スキャナインタフェース。Copyright (C) 1994
           Kenneth Stailey ken@spacenet.com)のサポート下でコンパイルしたいなら
           <filename>Makefile</filename> で <option>-D</option> に相当すること
           をイネーブルにし、&lt;<filename>scanio.h</filename>&gt; ファイル
           を他の適切な場所に移して下さい。(これは他のシステム上の
           <filename>/usr/&lsqb;local&rsqb;/include/sys</filename> にあるよう
           に見えるという点に注意して下さ
           い。だから、それをそこに置くというのは良い考えです)
</para><para>
           ドライバをコンパイルするには、

<screen>
  make
</screen>

           と入力して下さい。
           モジュールを組み込むには、
<screen>
  insmod logi32.o
</screen>

           と入力して下さい。
</para><para>
           シンボルが無いとローダが文句を言ってきた時は、それらを
           <filename>kernel/ksyms.c</filename> に加えて下さい。
           (または、もっと良いのは、そのドライバにとっては本当に古くさい
            カーネルをアップデートすることです...)
</para><para>
           <filename>kernel/ksyms.c</filename> を変更するべきだったなら、
           カーネルを再コンパイル
           し、その変更を反映させるためにリブートする必要があります。
</para></listitem>

<listitem><para>
	   デバイスのスペシャルファイルを作成します。

<screen>
  mknod -m 444 /dev/logiscan c 26 0
</screen>
           <filename>/dev/scan</filename> にシンボルリンクを張ります。

<screen>
  ln -s /dev/logiscan /dev/scan
</screen>

           MAKEDEV の最新バージョンは、適切なデバイスを生成することもできる
           はずです。「MAKEDEV を使う前に」 <filename>logi32.o</filename> が
           ロードされていなければ
           ならないことに注意して下さい。 MAKEDEV は、logitech スキャナドライ
           バを検出し、そこに存在するメジャーデバイスを見つけるために 
           <filename>/proc/devices</filename> の情報を使うからです。
           さらに詳しいことは、関係するドキュメントをご覧下さい。
</para><para>
<note><title>(注)</title>
<para>           上記の `26' はメジャーデバイス番号です。
                 それが既に使われている場合(それをロードしようとする際、ド
                 ライバは「cannot register major number：メジャー番号が登録
                 できません」と文句を言う)は、他の使われていない番号を選び
                 `logi32.h' の LOGI32_SCANNER_MAJOR の定義をそれに変更して
                 下さい。
</para><para>
                 新しいカーネルでは、メジャーを動的に割り付けることができます。
                 このようにしたい時は、定義を 0 に「セットして下さい。
                 但し、こうすると、ドライバをロードする度にメジャーが変わるの
                 で、毎回デバイスのスペシャルファイルを作成する必要があるとい
                 うことに注意して下さい。
</para></note>
</para></listitem>

<listitem><para>
	   `<filename>logi32.o</filename>' をカーネルモジュールをキープする
           ためのどこかにコピーして下さい。
</para></listitem>

<listitem><para>
	   動作確認
</para><para>
                (s)vgalib が動作しているなら、 <filename>./demo</filename> 
                ディレクトリの gifscan
                をビルドして下さい。svgalib が無いなら、このパッケージに入っ
                ているスクリプト scan.sh は不要です。
                だれか、あなたのために小さなスキャンプログラムを作ってくれる
                いい人を見つけるまでは、<command>cat &lt;/dev/scan &gt;
                </command> ファイルのようなやり
                方で満足する他ありません。(または、GIF ファイルに "blind-scan"
                できるようにするために gifscan から全ての vga に関するものを
                取り除く必要があります)
                pbm ファイルに直接スキャンしたものを格納する pbmscan という新
                しいパッケージがあります。これは svgalib が不要で、GIF に書き
                込むよりかなり高速です。
                私は PINT インタフェース用に何があるか知りません。これを使った
                良いアプリケーションを教えて下さい。
                (可能なら)私のドライバで動くなら 
</para></listitem>
</orderedlist>
</para>
</sect1>

<sect1 id="c1-param">
<title>ロード時のパラメータの変更方法</title>

<para>
  新しい <filename>modutils</filename> (と スタックドモジュールサポート)で、
  ロード時に下記のパラメ
  ータの値を与えることができます。従って設定を変えたい場合でも、ドライバを再
  コンパイルする必要はありません。
</para><para>
  "<userinput>insmod logi32.o LOGI_FOOBAR=%d</userinput>" でドライバをロード
  します。<option>%d</option> がパラメータ
  を設定するための値です。この機能に関するより詳しいことは <command>insmod
  </command> のドキュメントをご覧下さい。
</para><para>
  使用できるパラメータは以下のとおりです。
</para><para>
<screen>
  LOGI_DEBUG	これを 0 以外の値にして、デバッグモードでコンパイルすると、
                ドライバはデバッグ情報を出力します。そうでないときはこの変数は
                現れません。

  LOGI_MAJOR	メジャー番号。0 は「カーネルにフリーなものを選択させる」ことを
                意味します。

  LOGI_IOBASE	スキャナのベースアドレスです。これは正しくなければなりません。
                そうでないとドライバは初期化とボードの検出に失敗します。

  LOGI_IRQ	スキャナが使用する IRQ です。

  LOGI_DMA	DMA チャンネルです。

</screen>
</para>
</sect1>

<sect1 id="c1-prog">
<title>プログラマのための注意事項</title>

<para>
  ドライバはスキャナとの通信のために DMA 転送とIRQを使用します。いずれのチャ
  ネルもソフトウェアで設定できます。(詳しくは logi32.h をご覧下さい)
  スキャナは１ラインスキャンする度に割り込み要求を発行するので、有効なデータを
  得るために busy-wait 処理をする必要はありません。
</para><para>
  ドライバは内部に(ダイナミックアロケートの)バッファをキープします。このバッフ
  ァのデフォルトのサイズは、50 スキャンライン分 (<filename>logi32.h</filename> 
  を参照)ですが ioctl
  コールを通して調整可能です。(下記参照) <filename>/dev/scan</filename> を
  使っているプロセスが現在
  実行していてもいなくても、スキャナからのデータ転送はバッファがフルになるまで
  有効であることに注意して下さい。これは、プロセスが停止したりスワップアウトし
  ても、バッファスペースがあるのでデータ抜けは無いということを意味します。
</para><para>
  ドライバは、一回の <function>read(2)</function> コールで任意のバイト数を
  読み込むことができるよう
  になっていますが、内部バッファは一回の read(2) コールでバッファにフィットし
  た以上のバイト数を要求した場合はうまくいかないという点に注意して下さい。
  通常、b/w モードでスキャンする場合は一回に１スキャンライン分を読み込み、
  ハーフトーンモードの場合はたぶん数スキャンライン分を読み込むでしょう。
  read(2) コールがシグナルによって割り込まれると、read(2) は読み込んだバイト数
  を返します。私はこれが EINTR の戻りの `標準的な' 振る舞いとは異なることを
  知っていますが、スキャナではこの方法が理にかなっているのです。(別の方法では
  内部バッファの既存のデータをいくらか失ってしまう)
  スキャナデバイス上で select(2) をすると、バッファの中に最低でも１スキャンラ
  インのデータがあれば、デバイスは `ready' として認識されます。しかしこれも
  変更できます。(下記参照)
</para><para>
  サポートされた ioctl 機能のために、<link linkend="readme.ioctl">
  README.ioctl</link> をお読み下さい。しかし、
  ioctl インタフェースはまだ開発中であり、従って変更がありそうです。
</para>
</sect1>

<sect1 id="c1-bugs">
<title>バグ報告の注意点</title>

<para>
  バグを経験されたら私に教えて下さい。あなたのバグ報告にはそれを再現する方法、
  または少なくとも私が分かるように正確な状況を説明したものを添付して下さい。
  メッセージの中のバグ結果、例えば
</para><para>

<screen>
  general protection: xxxx
  EIP:    0010:xxxxxxxx
  EFLAGS: xxxxxxxx
  eax: xxxxxxxx   ebx: xxxxxxxx   ecx: xxxxxxxx   edx: xxxxxxxx
  esi: xxxxxxxx   edi: xxxxxxxx   ebp: xxxxxxxx
  ds: xxxx  es: xxxx  fs: xxxx  gs: xxxx
  Pid: xx, process nr: xx
  xx xx xx xx xx xx xx xx xx xx
</screen>
</para><para>
  が、画面あるいはシステムログにあれば、それを正確にコピーし、スキャナドライ
  バがロードされているロケーションと比較して、その範囲内かどうかを見て下さい。
  これは <command>insmod</command> を実行すると表示されます。
</para><para>

<screen>
  module `Logi32' (2 pages @ 0x0080c000) created
			     ^^^^^^^^^^ 私が知りたいのはこれです...
</screen>

</para><para>
  これがその範囲内ではない(カーネルのどこか他の所)場合、<filename>zSystem.map
  </filename> で EIP の値 (`0010:'に続いたものではない) を捜し、<filename>
  zSystem.map</filename> の関係ある部分を含めて下さい。
</para><para>
  もしそうならば '<userinput>nm -n logi32.o &gt;logi32.map</userinput>' 
  コマンドを使ってドライバのマップ
  を作り、あなたのレポートにこれを含めて下さい。
  あなたのバグ報告に、これら２つの部分のどちらかが欠けているなら、私にとって意
  味が無いということに注意して下さい。
</para>
</sect1>

<sect1 id="c1-help">
<title>さらなるヘルプと情報</title>

<para>
  ドライバ用のメーリングリストがあり、そこには最新の情報ファイルがあります。
</para><para>
<screen>
  &gt;&gt;&gt;&gt; info logiscan
  &lsqb;Last updated on: Wed Aug 10 10:41:58 1994&rsqb;
                             LOGISCAN MILINGLIST
                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~
</screen>
</para><para>
<caution><title>!!! 重要な注意 !!!</title>
<para>
  このメーリングリストは、LOGITECH の公式なリストではありません !!!
</para>
</caution>

</para><para>
<screen>
 .---------------------------------------------------------------------------.
 |  このメーリングリストは、 Linux 用の Logitech スキャナドライバの開発者    |
 |  (主に Andreas Beck &lt;becka@hp.rz.uni-duesseldorf.de&gt;) とそのユーザ間の    |
 |  コミュニケーションを容易にするためにセットされています。                 |
 |  これは Andreas の、または その他の Linux 用の Logitech スキャナドライバ  |
 |  の新しいバージョンとパッチを配布するためにも使われています。             |
 |                                                                           |
 |  Linux ではない他のオペレーティングシステムで Logitech スキャナの問題が   |
 |  あるときはこのリストを購読しないで下さい。ここではヘルプを得られません   |
 `---------------------------------------------------------------------------'
</screen>

</para><para>
  リストを購読するには、メッセージボディに下記のように書いたメールを
  majordomo@venture.net に送って下さい。
</para><para>

<screen>
  subscribe logiscan &lsqb;return mail address, optional&rsqb;
</screen>
</para><para>
  次に意見等は下記に送って下さい。
</para><para>

<screen>
  logiscan@venture.net
</screen>

</para><para>
  購読をやめるときは、メッセージボディに下記のように書いたメールを
  majordomo@venture.net に送って下さい。

<screen>
  unsubscribe logiscan
</screen>

</para><para>
  この情報のテキストを欲しいときは、下記のように書いたメールを
  majordomo@venture.net に送って下さい。
</para><para>

<screen>
  info logiscan
</screen>

</para><para>
<literallayout>
  Bye, Andreas.

  Andreas Beck		becka@hp.rz.uni-duesseldorf.de
  Germany
</literallayout>
</para><para>
    【訳注】現在のアドレスは、becka@sunserver1.rz.uni-duesseldorf.de
</para><para>

<screen>
  **************************************************************************
  M105 スキャナドライバを書き、かなりベースとなった
  Thomas Faehnle     Thomas.Faehnle@student.uni-ulm.de   に大変感謝します。
  **************************************************************************
  さらに、同じ ioctl インタフェースを使って A4Tech カラースキャナドライバを
  書いた Michael Beck       beck@hp832.informatik.hu-berlin.de にも。
  **************************************************************************
  さらに、同じ ioctl インタフェースを使って GS4500 スキャナドライバを書いた
  Jan Willamowius    jan@janhh.sh.sub.de  にも。
  **************************************************************************
</screen>
</para>
</sect1>

</chapter>

<!--#####################  chapter 2 "README.ioctl" ###################-->
<!--###################################################################-->
<![IGNORE[
==============================================================================
第２部  README.ioctl

  LOGITECH SCANMAN+ 400 dpi handheld scanner driver  version 0.0.3
==============================================================================
]]>

<chapter id="readme.ioctl">
<title><filename>README.ioctl</filename></title>

<sect1 id="readme-intro"><title>はじめに</title>

<para>
Hi folks!
</para><para>
これは専用のインタフェースボードを通してドライブされる LOGITECH SCANMAN+
スキャナ用のドライバです。
</para><para>
これは <filename>logi32.o</filename> によって提供される ioctl インタフェース
を使うアプリケーション開発者のガイドラインです。
</para><para>
どんな提案も歓迎します、そして私は他のスキャナ用デバイスドライバの作者からの
フィードバックを、共通のインタフェースを作成することが出来るように、正当に評
価します。
</para><para>
私は今までに Kenneth Stailey ken@spacenet.com からフィードバックを受け取って
います。彼は、私が将来オプションとしてサポートする予定の PINT と呼ばれる UNIX
用のスキャナインタフェースを既に持っています。
</para><para>
このパッケージの <filename>pint</filename> サブディレクトリにあるドキュメント
を参照して下さい。
これはバージョン 0.0.3 なので、ここで述べた定義はドライバの開発に応じて頻繁
に変更されるかもしれないことに注意して下さい。
</para><para>
私はこれまでスキャナ、または同様のデバイスの ioctl インタフェースを設計した
ことがないということを白状しなければなりません。そこで私のアプローチに何か
間違っている点が無いか、また、どうすればもっとよくなるかを教えて下さい。
</para><para>
また、あなたがこの ioctl API を使って素晴らしいスキャンニング・プログラムを
書かれたら、私に送って下さい。
</para>
</sect1>

<sect1 id="readme-supports"><title>サポートされている ioctl 機能</title>

<para>
以下に、サポートされている ioctl 機能を書きます。
</para>
<para>
<screen>
  **********************************************************************
  #define HSIOCGSCC               0x73e8  /* Get Scanner Capabilities */
  **********************************************************************
</screen>
</para><para>
(ioctls の MAGIC NUMBERS は、近い将来 ioctl の仕様がより安定になり"メジャー
 クリーンアップ"が起きた時に、変更されるだろうと思います)
これはスキャナのシステム・コールの中で最も重要です。
というのは、スキャナにどのようにアクセスし、何がサポートされているのかという
必要な情報のほとんど全てを提供するからです。
</para><para>
この関数は下記の構造体を返します。
</para><para>

<screen>
  struct scanner_capabilities {

          int o_scm_mono;	  /* Options for monochrome mode */
          int o_scm_grey;         /* Options for greyscale  mode */
          int o_scm_true;         /* Options for true-color mode */

          int o_xdpi;             /* Options for x resolution */
          int o_ydpi;             /* Options for y resolution */

          int o_bright;           /* Options for brightness */
          struct minmax bright;
          int o_contrast;         /* Options for contrast */
          struct minmax contrast;
          int o_hue;              /* Options for hue */
          struct minmax hue;
          int o_sat;              /* Options for saturation */
          struct minmax sat;

          int phys_width;         /* Width in mm */
          int phys_length;        /* Length in mm */

          int av_options;         /* Number of available Options (0-32) */

  };
</screen>
</para><para>
頭に '<option>o_</option>' が付くフィールドは全て "オプション・フィールド" 
で下記のフラグと組み合わせることができます。(つまり、これはビットフィールド
です)
</para><para>

<screen>
  #define SCC_SOFTSELECT  0x0001  /* オプションをソフトウェアで選択可能 */
  #define SCC_SOFTDETECT  0x0002  /* オプションをソフトウェアで検出可能 */
  #define SCC_HARDSWITCH  0x0004  /* オプションはハードウェアスイッチ   */ 
                                  /* (ユーザの関与が必要) */
  #define SCC_EMULATE     0x0008  /* オプションはドライバでエミュレートされる */
  #define SCC_CANDO       0x000f  /* 上記の何かがセットされたらドライバが */
                                  /* サポートするオプション */
</screen>
</para><para>
このオプションをどのように使うかの例を示します。
</para><para>
ハードウェアスイッチを使ってスキャナの dpi を選択できて、その設定をドライバ
が読み込むことができるなら、このように書きます：
</para><para>

<screen>
  SCC_SOFTDETECT|SCC_HARDSWITCH
</screen>

</para><para>
スキャナが１つの dpi 設定に固定されているなら"ハードウェアスイッチ" はありま
せんが、ふつうドライバは固定レートを "検出可能" であるというふりをします。 
(しかしレートは固定なので本当に検出する必要はありません)：
</para><para>

<screen>
  SCC_SOFTDETECT
</screen>

</para><para>
スイッチで dpi 設定を選択できるが、ドライバがその設定を読み込む方法が無い
(これは実際にはあるはずがないが、世の中には奇妙なハードウェアがあります)
という場合は、SCC_HARDSWITCH をセットしなければなりません。
</para><para>
これのアプリケーションにとっての意味は
</para><para>
SCC_SOFTDETECT が指定されていない場合、パラメータの値を知らないのでない限り
それを入力するよう促されるべきです。(私は SCC_SOFTSELECT が SCC_SOFTDETECT を
含まないというようなケースを想像できません...) そして値をドライバに教えるため
に明示的に SMOD-call によってセットしなければなりません。
</para><para>
SCC_HARDSWITCH は、アプリケーションがユーザにハードウェアを正しく設定するよう
に促す必要があることを意味するでしょう。(これが既に行われていることが分かって
いる、例えば SOFTDETECT が処理した...場合を除く)
</para><para>
SCC_EMULATE オプションは、これが選択されたとき、ハードウェアが他のモードで
あっても、またはこのモードをサポートしていなくてもドライバはこのモードをエミ
ュレートするだろうということを意味します。
(例えば、全てのモノクロスキャナは通常、モノクロデータを全ての３ RGB 値に拡張
することによりトゥルーカラーモードをエミュレートします)
</para><para>
<option>phys_*</option> フィールドは、最大スキャンウィンドウの物理的サイズを 
mm で表します。
</para><para>
<structname>minmax-structs</structname> は、パラメータの範囲、下記のように
定義された構造体です。
</para><para>

<screen>
  struct minmax {int min,max;};
</screen>

</para><para>
<structfield>av_options</structfield> フィールドには、この特別なスキャナの
使用可能なオプションの番号が入ります。この値は、 0-32 (inclusive) の範囲で、
HSIOCGOPT コールからのデータの正確な変換が必要です。
</para><para>

<screen>
  *********************************************************************
  #define HSIOCGOPT               0x73e7  /* Get option descriptions */
  *********************************************************************
</screen>

</para><para>
このコールは、下記フォーマットの32までのオプションデスクリプタ(これは 
<literal>av_options</literal> エントリを予約するには十分でしょう)のフィールド
を返します。
</para><para>

<screen>
  struct scanner_option {int  options;    /* Option availability */
                          char name&lsqb;20&rsqb;;};
</screen>

</para><para>
'オプション'フラグは上記の '<option>o_</option>'の値の一つとして(すなわち、
ハードウェアまたはソフトウェアによってオプションが選択されたら、そしてそれが
ソフトで検出可能、あるいはドライバ機能がエミュレートするようなものならば) 
扱われます。
</para><para>
オプションとして、ユーザがオプションを 選択／非選択／表示 するための
オプション名を示すユーザダイアログを提案します。
</para><para>
これが出来ない、あるいはしたくない(例えば OCR のようなバックグランド処理)場合、
その名前からオプションの意味を引き出すようにするべきです。
</para><para>
互換性を保証するために、デバイスドライバの作成者は、何かの機能の名付けの彼らの
アイデアを私に確認することが奨励されます。これは、同じオプションに対して複数の
名前を避けるために、そしてこの文書を私が更新することができるようにするため
です。
</para><para>
現在、ドライバによって使われるオプションは１つだけあります。
</para><para>

<screen>
  オプション: "Dithering"
  機能F     : dithered greyscale モードを on/off する
  ドライバ  : logi32.o
  作者      : becka@hp.rz.uni-duesseldorf.de
</screen>

</para><para>

<screen>
  **************************************************************
  #define HSIOCGSCT               0x73e9  /* Get Scanner Type */
  **************************************************************
</screen>

</para><para>
このコールは、通常の ioctl インタフェースではアクセスできない特殊なスキャナの
特別の機能をアプリケーションが使えるようにするために、スキャナハードウェアを
識別します。
下記の構造体を返します。
</para><para>

<screen>
  struct scanner_type {
    char manufacturer&lsqb;20&rsqb;,model&lsqb;20&rsqb;;
  };
</screen>

</para><para>

<screen>
  **********************************************************
  #define HSIOCGMOD               0x73ea  /* Get modeinfo */
  **********************************************************
</screen>

</para><para>
このコールは、スキャナの現在のモード情報を得ます。
</para><para>

<screen>
  struct modeinfo_struct {
    int xdpi,ydpi;                /* resolution */
    int sc_mode;
    int depth;                    /* number of different colors (-1) */
    int bpl;                      /* bytes per scanline */
    int left,right;               /* margins in Pixels */
    int top,bottom;               /* margins in Lines */
    int bright;                   /* brightness */
    int contrast;                 /* contrast */
    int hue;                      /* hue */
    int sat;                      /* saturation */
    int options;                  /* enabled options */
  };
</screen>

</para><para>
<structfield>sc_mode</structfield> は、下記のいずれか一つの値をとります。
</para><para>

<screen>
  #define SCM_UNKNOWN 0           /* Scanner modes : */
  #define SCM_MONO 1              /* 1 BitPerPixel   */
  #define SCM_GREY 2              /* 8 BitsPerPixel  */
  #define SCM_TRUE 3              /* 24 Bit RGB      */
</screen>

</para><para>
０の場合、スキャナは未定義の状態です。(起きるべきではない)
新しいモードをセットすることもできますが、むしろアボートするべきです...。
</para><para>
スキャンモードは転送されたデータのフォーマットと異なります：
</para><para>
MONO モードはバイナリエンコードされた黒と白の値のビット列を送ります。
即ち、0x83 0x10 を読み込んだ場合、スキャナヘッドの下のパターンは、
</para><para>

<screen>
  * . . . . . * *  . . . * . . . . ;
</screen>

</para><para>
つまり、１バイトにつき常に８個のピクセル(画素)があり、一行には常に複数の
８ピクセルがあります。(これは左右を通して再現される筈です...)
</para><para>
グレーモードは、0〜255 までの範囲で測定された灰色の値のバイト列を送ります。
実際のデプスは、<structfield>depth</structfield> フィールドを使うことによって
見つけることができますが、たとえ <structfield>depth</structfield> が 0 (即ち、
スキャナが実際に黒白モードである)でも、1 ピクセルにつき常に 0 または 255 を
送ります。即ち、１ピクセルにつき１バイトなのです。  
</para><para>
トゥルーモードは、バイトで RGB 値を送ります。従って、1 ピクセルに付き3バイト
あります。実際のデプスの解像度は 0xrrggbb で、rr はスキャナが識別できる赤色の
番号です。 
即ち、24ビットモデルだと 0xffffff とレポートするべきところを 4096色のスキャナ
(4ビットの赤、緑、青)では 0x0f0f0f とレポートするわけです。
</para><para>
<structfield>bpl</structfield> は、read コールでアプリケーションに送られる 
bytes per line (1ラインあたりのバイト数) の数です。
</para><para>
<structfield>Left, right, top, bottom</structfield> は、マージンをセット
します。
</para><para>
Bright, Contrast, Hue, Saturation は、画像のそれぞれの特性値です。
</para><para>
オプションは、選択されたオプションのビットフィールドとしてみなされます。
</para><para>

<screen>
  **********************************************************
  #define HSIOCSMOD               0x73eb  /* Set modeinfo */
  **********************************************************
</screen>

</para><para>
このコールは、スキャナモードをセットするために使います。
あなたが与えた構造体はスキャナまたはドライバが扱うことの出来る本当の値を反映
するために"変更される"という点に注意して下さい。
</para><para>
例えば、400dpi(X方向), 600dpi (y方向), フル・デプスで 24ビットモード、
マージンは 5-1003 (方向x),13-4000 (y方向) という条件でスキャンさせたい場合
下記のようにして SMOD をコールします。
</para><para>

<screen>
  { 400,600,
    SCM_TRUE,
    0xffffff,
    0,/* bpl doesn't matter */
    5,1003,13,4000,
    ...
  }
</screen>

</para><para>
スキャナが両方の軸で 300dpi しかサポートできない場合、ハードウェアスイッチを
経由して SCM_MONO にセットします。(そしてドライバはデータを変換できない &lsqb;!&rsqb;)
８の倍数で１０インチまでのページ長の水平方向の境界のみサポートし、
構造体は次のように変更されるでしょう。
</para><para>

<screen>
  { 300,300,
    SCM_MONO,
    0,
    126,/* Bytes per line filled in */
    0,1008,13,3000
  }
</screen>

</para><para>
ドライバは TRUE-MOD をエミュレートできる必要があるという点に注意して下さい。
怠けもののソフトウェアがそれをあてにするかもしれませんから...
</para><para>

<screen>
  *************************************************************************
  #define HSIOCGREG               0x73ec  /* play with strange registers */
  #define HSIOCSREG               0x73ef
  *************************************************************************
</screen>

</para><para>
これはドライバの開発に使用し、通常はユーザレベルのアプリケーションにはアクセ
ス出来ません。このコールの機能は、スキャナからスキャナへ、あるいはドライバか
らドライバへ、とは違います。
</para><para>

<screen>
  *************************************************************************
  #define HSIOCGBUF               0x73f0  /* get/set current buffer size */
  #define HSIOCSBUF               0x73f1
  *************************************************************************
</screen>

</para><para>
スキャンするラインの現在のバッファサイズを取得／設定します。
</para><para>

<screen>
  *************************************************************************
  #define HSIOCSSTH               0x73f2  /* get/set select(2) threshold */
  #define HSIOCGSTH               0x73f3
  *************************************************************************
</screen>

</para><para>
スレッシュホールドの選択値を取得／設定します。
</para><para>

<screen>
  *********************************************************************
  #define HSIOCGSIB               0x73f4  /* get scanlines in buffer */
  *********************************************************************
</screen>

</para><para>
これはスキャナの内部バッファの fill-gauge の一種として使われるでしょう。
これは典型的にはデータフローの量をユーザが制御するスキャナ(例えばハンドスキャ
ナ)によって使われ、バッファが満杯になったときにユーザにもっと遅くスキャンする
よう伝えることが出来るようにします。
</para><para>

Bye, Andreas.

</para>
</sect1>

<sect1 id="c2-appendix">
<title>付録</title>
<![IGNORE[
============
= 付録 =
============
]]>

<para>
この仕様を使ったスキャナドライバの開発者
</para><para>

<screen>
  Andreas Beck            becka@hp.rz.uni-duesseldorf.de          (logi32)
  【訳注】現在のアドレスは、becka@sunserver1.rz.uni-duesseldorf.de
  Thomas Faehnle          Thomas.Faehnle@student.uni-ulm.de       (m105)
  Jan Willamowius         jan@janhh.sh.sub.de                     (GS4500)
  Michael Beck            beck@hp832.informatik.hu-berlin.de      (A4Tec)
  Willem Dantum           willemd@knoware.nl                      (Genius B105G)
</screen>

</para><para>
この仕様を利用できるスキャナプログラム
</para><para>

<screen>
  gifscan :     Thomas Faehnle によってかかれ Andreas Beck によって変更された
                オリジナルの svgalib ベースのデモアプリケーション
  pbmscan :     Andreas Matthias &lt;andy@titan.central.de&gt; によって書かれた
                pbm ファイルにスキャン(結果を格納)するコマンドラインツール
</screen>
</para>
</sect1>

</chapter>

<!--#################### chapter 3 "demo/README" #######################-->
<!--####################################################################-->

<!--
第３部  demo ディレクトリの中の README
-->
<chapter id="demo-readme">
<title><filename>demo/README</filename></title>
<abstract><para>
LOGITECH SCANMAN 400 dpi ハンドヘルド・スキャナドライバ用の GIFSCAN 
version 0.0.3
</para></abstract>

<sect1 id="c3-copyright">
<title>Copyright</title>
<para>
<literallayout>
Copyright (C) 1994  Andreas Beck &lt;becka@hp.rz.uni-duesseldorf.de&gt;
【訳注】現在のアドレスは、becka@sunserver1.rz.uni-duesseldorf.de
</literallayout>
</para><para>
    このプログラムはフリーソフトウェアです。あなたは、これを Free Software
    Foundation が発行している GNU General Public License のライセンスのバージ
    ョン２、または(あなたのオプションで)それ以降の条件に従って再配布したり変
    更することができます。
</para><para>
    このプログラムは、役に立つことを期待して配布しています。しかし、いかなる
    保証もありません。商品性や特定用途への適合性についての暗黙の保証すらあり
    ません。詳しくは、GNU の General Public License をご覧下さい。 
</para><para>
    あなたは、このプログラムと一緒に GNU General Public License のコピーを受
    け取るべきです。そうでないならば、
    Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
    に手紙を書いて下さい。
</para>
</sect1>

<sect1 id="c3-demo-prog">
<title>デモプログラムについて</title>
<para>
Hi folks!
</para><para>
これは LOGITECH SCANMAN+ スキャナ用ドライバのための小さなデモンストレーション
プログラムです。
</para><para>
このプログラムの一部は、Thomas Faehnle 
&lt;Thomas.Faehnle@student.uni-ulm.de&gt;
によって書かれたもので、私は彼の努力に感謝したいと思います。
</para><para>
私はオリジナルの 'scandemo' を LOGI32 ドライバ／スキャナの拡張された能力(スキャ
ナの識別、SIB-ioctl,ディザ中間調)に合わせ、且つスキャンした画像を共通のフォーマ
ットに格納するための信頼できる方法を提供するためにかなり変更しました。
</para><para>
scandemo のこのバージョンは gifscan にリネームし、このパッケージの早期バージョ
ンで提供されていたスクリプトをすっかり置き換えました。
</para><para>
スクリプトは、スキャナが送っているライン幅を正しく決定するための可能性が
無いし、従って異なったスキャナや間違ったパラメータで使った時、間違った結果を
作るのでスクリプトは捨てました。
</para><para>
私は主に下記の理由から GIF フォーマット(これは (c) by Compuserve だと思う)を
選択しました。

<itemizedlist>
<listitem><para>
ほとんどのグラフィックスパッケージがこれを扱っている。
</para></listitem>
<listitem><para>
私は既に Gif への格納を扱う C のソース(Mess按OSから)を書いている
</para></listitem>
<listitem><para>
圧縮率が極めてよい
</para></listitem>
</itemizedlist>

<note><title>【訳注】</title><para>
Mess按OS というのは MS-DOS のことを茶化しているのです。
</para></note>

</para><para>
GIF 圧縮は遅く PBM フォーマットは記述するのが大変容易であることに気が付いている
ので、私はその能力をも追加しました。申し訳ないけど誰がオリジナルの PPM (P4)コー
ドを gifscan に追加したか思い出せません。(彼に感謝します)
私はそれを Greyscale (P5) 画像に書くための変更をしたところです。
</para><para>
プログラムをビルドするために "make" をします。 
#include &lt;scanner.h&gt; は、スキャナドライバをコンパイルするために使われる
ものと同じであることに注意して下さい。
このファイルは頻繁に変更されるので、常に最新版を /usr/local/include に入れる
ようにして下さい。
ioctl インタフェースはまだまだ工事の最中ですから、古い gifscan のバイナリは
これを新しいドライバと共に使うと通常はブレークします。
</para><para>
Logitech スキャナには黒白モードとグレースケールモードがあります。
これは不幸にもソフトウェアで検出不可能です。(それともだれかこの方法を知って
ますか？)
</para><para>
そこで私は -g x というスイッチ(x はグレースケール・マトリクスのサイズ)を
追加しました。(未熟なオプション処理であることは分かっていますが、たった一つ
のスイッチのために getopt をインクルードしたくなかったのです...)
</para><para>

<screen>
  **************************************************************************
  現バージョンでもこのスイッチは使えますが、新しいスタイルのスキャナドライバ
  はオプションとしてディザを提供する(Logi32 は)筈なので、今後は使うべきでは
  ありません。
  **************************************************************************
</screen>

</para><para>
黒白モードにはこれを１(デフォルト)に、グレースケールモードには６をセットし
なければなりません。(これはスキャナ内部マトリクスのサイズなので)
１から１６までの範囲の値は、他のスキャナでは有効かもしれませんが、LOGITECH
では強いモアレ効果が出てしまいます。
</para><para>
<note><title>【訳注】</title><para>
モアレ効果というのは、原画像には無い模様が発生する現象です。
</para></note>

</para><para>
今度サポートされた Scanman256 には真のグレースケールモードがあります。
そのモードの全て(黒白、4,6,8 bit)が、今サポートされるべきでした。
</para><para>
スキャン中は下記のキーが使えます。(ビジー待ちや、入力されるスキャンデータの
選択をしたくないのでキーは、スキャナが動くまでは認識されません)
</para><para>

<screen>
  &lt;Esc&gt;,q,x,Q,X   : gifscan を終了します。
  i,I             : (I)nverse モードを切替えます。
  w,W             : スキャン速度ワーニングモードを切替えます。
                    (バッファが満杯に近くなると、画面が赤／紫になります)
  f               : GIF ファイルへの格納を開始します。
                    (何らかのキーを押すと停止します)
  p               : ppm ファイルへの格納を開始します。
  0-9             : オプション番号を切替えます。
  b/B,c/C,h/H,s/S : Brightness(輝度)、Contrast(コントラスト)、Hue(色調)、
                    Saturation(彩度)を調整します。
  'm'             : 強制的に SCM_MONO (モノクロモード)処理にします。
  'g'             : force SCM_GREY-operation
                    強制的に SCM_GREY (グレースケールモード)処理にします。
  'a'             : SCM (スキャナモード)の自動検出を許可します。
</screen>

</para><para>
オプションは起動時に表示されます。これらのキーはファイルをスキャン(セーブ
モード)中は無効であることに注意して下さい。これは、(読み取り幅や bpp のような)
スキャン画像の基本パラメータを変更し、セーブするコードをあいまいにするかも
しれないからです。(GIF では異なるライン幅を使うことはできません)
</para><para>
また、GIF 圧縮は能率的ですが遅く、特に 1ビット GIF でエンコードすると
セーブモードを使った場合、スキャナをかなり遅く操作する必要があります。
</para><para>
このオプションはすぐに消え去るだろうから、だれも "bit-count-code" (私は以前の
バージョンであるとほのめかした)を書き直す必要はありません。
</para><para>
Bye, Andreas.
</para>
</sect1>

<sect1 id="c3-todo">
<title>TODO</title>
<para>

<simplelist columns="2" type="horiz">
<member>やるべきこと：</member>
<member>より良いユーザインタフェース、ファイルのネーミング、例えば
ダイアログボックスとか...</member>
<member></member>
<member></member>
<member>BTW (？)：</member>
<member>svgalib グラフィックスを持っていない／欲しくない／必要でない人の
ために PBMSCAN と呼ばれる新しいコマンドラインのスキャンツールがあります。
</member>
</simplelist>

</para><para>
<literallayout>
Andreas Beck		becka@hp.rz.uni-duesseldorf.de
Germany
</literallayout>

</para><para>
【訳注】現在のアドレスは、becka@sunserver1.rz.uni-duesseldorf.de
</para><para>

<screen>
  **************************************************************************
  Thomas Faehnle		Thomas.Faehnle@student.uni-ulm.de
  には深く感謝します。
  **************************************************************************
</screen>
</para>

<para>
<screen>
=====================================================
 Ryoji Kawagishi   E-Mail: kawagisi@yk.rim.or.jp
                           KFA02544@niftyserve.or.jp
=====================================================
</screen>
</para>

<para>
(sgml conversion, y.senda, ysenda@pop01.odn.ne.jp, 2001/09)
</para>

</sect1>

</chapter>

</book>
