═══ 1. StWTV ═══ Welcome to StWTV. StWTV is an TV application which uses the WinTV/PCI to display a TV image. You need the device driver WCAST.SYS from Abbotsbury Software. StWTV has the following features:  Definitions of stations  Settings of every station with color, contrast and brightness  Free defineable toolbars with station buttons  Free sizeable TV image  Record and playback of movies  A REXX API  and more This document gives you a short overview of the application, its settings and possibilities. Please excuse my bad english. Help me to make this online help better and make suggestions to me. The elements of StTWV Settings dialogs Glossary The future Step by Step What do if ... Known problems ═══ 1.1. About this online help ═══ This online help for StWTV was written by the programmer of the application. Everybody knows that a programmer is not the best candidate for writing documentations or online help for his own programm, So please be indulgent if this documentation is incomplete or uninteligible. Feel free to make suggestions to me. ═══ 1.2. The author ═══ Stefan Milcke KБferstraсe 45 28779 Bremen Germany Stefan.Milcke@t-online.de http://home.t-online.de/home/stefan.milcke/homepage.htm ═══ 1.3. What is StWTV ═══ With StWTV you can watch TV if you have a WinTV/PCI card and the device driver from Abbotsbury Software. You can create and manage a pool of stations. You can attach every station from this pool to user defineable toolbars for easy access. The main window of StWTV can be defined as float on top and the CPU usage can be adjusted. You can record and playback short movies (without sound). StWV remembers all settings inclusive all window positions and the last active station and recalls them at the next startup. There is a REXX API implementet. Some events in StWTV causes specific scripts to be executed. Have much fun with StWTV. ═══ 1.4. Legal ═══ 1. This software is shareware. If you want to use this programm you have to register. 2. The use of this programm is at own risk. I am not liable for any damage caused by using this programm. 3. It is not allowed to change any part of this software package. 4. It is not allowed to disassemble or analyse this dieses programm. 5. Everyone can make as much copies of this programm as he wants. Please remember allways 1. 6. No part of this software should be ported to the windows platform. 7. To be continued ;-) ═══ 1.5. Credits ═══ Much thanks to: Tim Snape (Programmer of the driver WCAST.SYS and the toolkit) for his tips and help for this project. John Rodriguez (Employee Firma Hauppauge) FБr sein Engagement bei seiner Firma fБr die Entwicklung eines neuen Treibers. IBM For their really good operating system. ═══ 2. Installation ═══ The installation of this programm is very simple: Just copy all files that came with this package into a directory of your choice. The start the install script INSTALL.CMD. You'll be asked for Language Enter the language code. EN for english. DE for german. card name Enter the name of your card (Normally wcast) number of card Enter the number of this card (Normally 1) After this the software will start for the final setup. ═══ 3. The elements of StWTV ═══ At the top directly under the menu you see the toolbars. They can be dragged and dropped with the right mouse button away from the main window. The first toolbar from the left contains some usefull tool buttons. All following toolbars are user defined station toolbars. Below the toolbars you see the TV window where the TV image received by the card is displayed. At the bottom there is a status bar. Every field in the status bar can be switched on or off. They have the following meanings: Feld 1 Name of the station Feld 2 Channel number Feld 3 Frequency Feld 4 Frames per second Feld 5 Signal quality Remarks to field 4: Frames per second is what could be managed by the blitter, not the driver or hardware. Remarks to field 5: Showing the signal quality is very CPU intensive. ═══ 4. Settings dialogs ═══ The following sttings are available:  Driver information  Register software  Window settings  Blitter settings  Properties of station XXX  Station pool settings  Toolbar settings  Movie settings  Script settings  Driver variables ═══ 4.1. Driver information ═══ The values in this dialog are received directly from the driver:  Product information  Manufacturer info  Version  Image format  Max. digitized size  Max. destination size  Max. overlay size  Volume  Balance  Cable tuner  TeleText support This values must not be the reality. You can see it with the value TeleText support This value is until version 1.020L allways yes, but the driver is not ready for TeleText. ═══ 4.2. Register software ═══ As you have seen in chapter Legal you must send a mail to the author of this software. After this you'll receive a software key to register the programm. With this dialog you can register the software. Fill out the fields with the key you've received from the author. ═══ 4.3. Window settings ═══ Here you can define some values for the main behaviour of the TV window: main window station switching toolbar status bar ═══ 4.3.1. Main window ═══ Allways on top When active, the main window is allways on top of all other windows. ═══ 4.3.2. Station settings ═══ Softswitching If checked, the TV-window becomes black before the station changes. After this the brightness is increased to the value that is defined for the station. ═══ 4.3.3. Toolbar ═══ Toolbar Here you can define witch buttons of the utility toolbar (left side) are visible. ═══ 4.3.4. Status bar ═══ Here you can define if the fields in the status line are visible or not. 1. The number below the station name is the initial length for this field. 2. Enabling signal quality can consume much CPU performance. ═══ 4.4. Blitter settings ═══ In this dialog box you can change some settings for the blitter. See chapter blitter in Verfahren Time (in msec) between blits Between two blits to the screen StWTV delays for a little time to not use the CPU too much. This value is the length for the delay. If you set this value to zero and Priority class is equal to three then it will be set to four to prevent a system hang. Priority class Every thread in OS/2 can be executed in one of four priority classes. This value is the priority class of the blitter. Priority level Every thread in a priority class can be executed in a level from 1 to 31. This value is the priority level for the blitter thread. Blitted size This is the size of the image generated by the hardware. The greater this value is the better the quality of the image. You need to restart StWTV to make changes active. Watchdog active If checked, StWTV is running an other thread that watches on the TV-image. If there is no change StWTV resets the driver. When this is done, you can hear a short beep from your PC-Speaker. Number of checkpoints Defines the number of points on which the watchdog is checking. If this value is too low, there may be a reset, when it is not neccessary. If this value is too hight, the watchdog consumes too much CPU-performance. ═══ 4.5. Properties of station XXX ═══ In this dialog you can change some settings of the actual station. Every value you set here will be stored for every station separately. Volume Bass Treble This sliders controls the sound settings. Unfortunately the device driver has problems to activate these values. So use your favorite sound mixer programm for this value. If you have a Soundblaster or compatible card StWTV can detect this. Just try the sliders. Brightness Color Saturation Contrast Hue This sliders controls the approbiated settings for the TV-image. ═══ 4.6. Station pool settings ═══ In this dialog box you can define all stations you plan to use in StWTV. Available stations Properties of selected station ═══ 4.6.1. Available stations ═══ In this list box you'll see all available stations in StWTV. To edit a station select it here. To delete a station click on delete. In this listbox you'll see an entry "". This entry is not editeable and can only be added to a toolbar. ═══ 4.6.2. Properties of selected station ═══ After selecting a station in the Available stations you can edit the properties of this station. All changes are made online so you can view it directly. Name Enter a name for the station here. This name is important to identify a station later when adding it to a toolbar. Source This is the input source for the selected station. Channel Choose the channel for the station. The frequency will be set automaticaly. With the button scan you can search for the next channel with good quality. Frequency Choose a frequency for the station. With the button scan you can search for the next frequency with good quality. Bitmap Choose a bitmap for the station. This bitmap is displayed in the toolbar later. With the button search you can search on your harddrive for a bitmap. The bitmaps for stations must be in OS/2 BMP format. The best size for the bitmaps is 21x21 pixels. Region file This file contains frequency to channel definitions. These files are normaly stored in \MMOS2\REGION. This files are part of WarpTV and they are copyright. So they can't be part of StWTV package. Install WarpTV to get the files. ═══ 4.7. Toolbar settings ═══ In this dialog box you can define all station toolbars you plan to use with StWTV. Every toolbar can contain as much stations from the station pool as you like. Available toolbars Properties Attached stations Available stations The checkbox delayed toolbar creation belongs to all toolbars and means that the toolbars are created after complete initialisation of the frame window. ═══ 4.7.1. Available toolbars ═══ This listbox contains all defined toolbars. To view the properties of a toolbar select it here. To add a new toolbar click on new and to delete a toolbar click on delete. ═══ 4.7.2. Properties ═══ Here you can change the following settings: Name Enter a specific name for the toolbar Stations per line The station buttons in a toolbar are ordered in lines. This value is tha maximum number of stations for one line. If a toolbar contains more stations as this value a new line of toolbar buttons will be created. Position This radio button defines the position of the toolbar. Off means that the toolbar is not visible. Float means that the toolbar can be positioned freely on the desktop. ═══ 4.7.3. Attached stations ═══ In this listbox you'll see all stations this toolbar contains. With the button remove you can remove the selected station from the toolbar. With the buttons up and down you can change the position of the station in this toolbar. ═══ 4.7.4. Available stations ═══ Here you can see all stations from the station pool. With the button attach you can add the station as the last station to the toolbar. ═══ 4.8. Script settings ═══ Since version 1.01 build 2071 StWTV can execute scripts. The user can define for some events in StWTV scripts to be executed. Additionally the user can define up to ten user defined scripts that apear as a menu entry in StWTV. Scripts are written in REXX. See RexxApi.TXT for more informations about the API in StWTV. ═══ 4.8.1. Events ═══ In StWTV some events causes scripts to be executed. Here you can define the scripts to be executed. Please keep in mind that there are no stations defined on StWTV startup. So you can't query stations at this time. ═══ 4.8.2. User defined ═══ Enter user defined scripts and their menu text here. ═══ 4.9. Driver variables ═══ Here you can view and edit some driver variables. If you change a value you must use the apply button to apply make the change. After applying StWTV resets the driver to make sure the new values are accepted by the driver. ═══ 5. Glossary ═══ In this chapter i'll try to explain some definitions and terms. ═══ 5.1. Blitter ═══ The blitter is the part of StWTV that makes the TV image visible. To understand the way of the image from the TV-card to the screen i have to explain some internals. The device driver makes sure that the correct channel and frequency on the TV card is set. Then the driver copies the TV image into conventional RAM into your PC. After this the application must decide what to do. With the newer versions of OS/2 IBM has introduced a software interface to manipulate the grafic card directly. This interface is called DIVE (Direct Interface Video Extensions) and stays in the file DIVE.DLL. The fast copy of images from a memory location (here RAM) to an other memory location (here grafic card RAM) is called blitting. StWTV uses the DIVE interface and blitts the image from the conventional memory to the screen. This sounds very simple but it is a little bit complicated. The image from the TV card is in a special format (Y422) and in a fixed size. This format is converted and sized via DIVE. This conversion is very CPU intensive. In StWTV there is an extra thread to handle this blitting. The priority of this thread can be adjusted in very fine steps. ═══ 5.2. Multithreading ═══ For every application under OS/2 there will be started a new process. This process gets a protected adress room for data and code. In this process there is at least one thread (the main thread). In a process can be more than one thread. They all are running quasi paralell and have different jobs to do. Every thread can be executed in several priorities. But not every thread has its own CPU. So these threads are executed sequentially (portionally). Every thread has a priority saying how often it can get CPU time to execute. The length of this time is called time slice. When this time slice is over the thread will be frozen in it's actual state and an other waiting thread gets the CPU. If there are two threads with different priority the thread with the higher priority gets the CPU. In StWTV there are six threads. Thread 1 us running with normal priority. This is the main thread where all windows and dialog boxes are managed. Thread 2 is started by the DIVE engine. Its priority is not under control of StWTV. Thread 3 is the blitter. It makes the TV image visible. Thread 4 is the watchdog (if enabled) Thread 5 is running when playing back or recording movies. Thread 6 is the controll instance for soft station switching. ═══ 5.3. Stations ═══ Stations in StWTV are managed in a station pool. Every station has its own set of properties :  Name  Channel  Frequency  Bitmap  Internal ID-Nummer All this properties (without the internal ID) can be edited in the station pool settings for every station. After definition these stations can be attached to one ore more toolbars. Stations have more properties that can be changed very often:  Volume  Bass  Treble  Color/Saturation  Contrast  Brightness  Hue All this properties are managed in properties of station XXX. ═══ 5.4. Toolbars ═══ The station toolbars are small areas in the main window of StWTV. There can be as many toolbars as you like. Every station toolbar can have as much station buttons as you like. The position of this toolbars are free defineable. ═══ 6. The future ═══ With the WinTV/PCI card there is a cheap and good TV card for OS/2. In this chapter you can read some things about the future of this cards. Again excuse my english !!! ═══ 6.1. GRADD ═══ There is a new device driver modell for grafic adapters. It is called GRADD and is available for some cards. This driver model is a complete 32bit architecture and should enable all grafic card manufacturers to write an OS/2 driver. What has this to do with StWTV ? See New driver. ═══ 6.2. New driver ═══ In the nearest future there will be a new driver for th WinTV/PCI. It will use the new GRADD device driver modell and is able to write direct to the grafic card similar to the PCI-Push technology used under the operatings system whose name i won't write down here. This causes the TV-application not to be so CPU intensive. ═══ 7. Step by Step ═══ Step by Step: Phase 1 Creating stations 1. Open Options->Stations... 2. Be sure that the file in the entry field Regionfile exists. Use the search button if you want to set an other location 3. Press the new button. A new station will be created with the name . 4. Go to the name entry field and enter a name for example MyFirstStation 5. Select the right source (there is a bug in the english version. It is named "Quelle") 6. Spin up or down the channel field or use scan button to select a channel 7. The frequency is automatically set depending on the region file you choosed to use 8. Attach a picture for your new station button or leave it blank to use an X for the bitmap 9. Create another station button in the same way as step 3a) to 3f) 10. Press OK when finished Phase 2: Creating toolbars 1. Open Options->toolbars... 2. In the right toolbox you'll se all stations you have defined in Phase 1 3. Create a new toolbar and attach the stations you like 4. Press the new button. A new toolbar will be created with the name 5. In the name entry field enter a name for example MyFirstToolbar 6. Select a station on the right listbox you want attach to the toolbar and the press the attach button 7. Repeat step 3c) until you have attached all stations you want 8. After you have created a toolbar and attached at least one station to it the toolbar becomes visible in the TV-window 9. Press OK when finished Phase 3: Use the buttons 1. To change a station just press a station button in the toolbar ═══ 8. What do if ... ═══ Make sure that the driver is installed correctly. If the application WTV.EXE is not able to produce a TV image there is a driver problem. Make sure that your grafic driver is DIVE enabled and your system resolution has more than 16 colors. If there is no or only a bad image or the channel/frequency can't be switched try to use an other driver. A good candidate is 1.016D. If there is a problem with StWTV fill out the Problm.rpt and send it back to me. Feel free to make suggestions to me and again please help me in writing a good english online help Attention I'm not reliable for a correct driver installtion. Please make sure the programm WTV.EXE is working correctly before sending an error report to me. If i can see from an error report that the WTV.EXE is not working correctly on your system you may get now answer from me! ═══ 9. Known problems ═══ Don't use mouse pointer with more than two colors. They'll cause a signigcant CPU performance problem and sometimes system hangs. This may be a bug in the DIVE implementation under Warp 4. Under Warp 3 this worked fine. Remedy: Wait until IBM removes this. When there is a WinOS/2 session in the background and float on top is activated sometimes the menu bar is flashing. Remedy: I'm working on this. Sometimes the TV-images stops refreshing. Remedy: After a short time you shold hear a little beep from your PC-Speaker and the driver resets. This is the watchdog function in StWTV. There are new drivers with first GRADD implementation. All these drivers caused problems on my system. Using the VCAIFLT.DLL in the GRADD chain causes a system trap on my system. My application is not GRADD enabled so don't use the switches /USEVCAIMONITOR and/or /USEDIVE.