REFERENCE
=========


DIGITIZER / Screen Machine II
=============================

smClearClips
  short smClearClips(short nSM)
Removes all clips from the internal clip list. A convenience function to empty the clip list and remove them from the live video.
See also: smSetClip, smRemoveClip, smSetClipList


smClose
  short smClose(short nSM)
Turns off video and audio of the appropriate Screen Machine II and decreases the usage count by 1. This is the counterpart to smOpen. Use this when you are done with the Screen Machine II (like at the end of the program).
See also: smOpen


smGetAudio
  short smGetAudio(short nSM)
Returns status of audio for the appropriate Screen Machine II, a value of 0 when audio is muted and 1 when active.
See also: smSetAudio, smGetAudioVolume


smGetAudioBalance
  short smGetAudioBalance(short nSM)
Returns current audio balance, a value between -50 and 50, with 0 as the default (equal balance). Values between -50 and 0 shift the balance towards the left, and values between 0 and 50 towards the right.
See also: smSetAudioBalance, smGetAudioFader


smGetAudioBass
  short smGetAudioBass(short nSM)
Returns current audio bass, a value between -50 and 50, with 0 as the default.
See also: smSetAudioBass, smGetAudioTreble


smGetAudioFader
  short smGetAudioFader(short nSM)
Returns current audio fader setting, a value between -50 and 50, with 0 as the default (equal front/rear balance). Values between -50 and 0 shift the balance towards the back, and values between 0 and 50 towards the front.
See also: smSetAudioFader, smSetAudioBalance, smGetAudioBalance


smGetAudioInput
  short smGetAudioInput(short nSM)
Returns active audio input. Values are between 0 and 2 an correspond to the video inputs. 
 0 = SM_INPUT_BLACK (or SM_INPUT_SVHS)
 1 = SM_INPUT_RED 
 2 = SM_INPUT_YELLOW (on tuners it is connected internally)
See also: smSetAudioInput


smGetAudioTreble
  short smGetAudioTreble(short nSM)
Returns current audio treble, a value between -50 and 50, with 0 as the default.
See also: smSetAudioTreble, smGetAudioBass


smGetAudioVolume
  short smGetAudioVolume(short nSM)
Returns current volume, a value between 0 and 100 with 50 as the default.
See also: smSetAudioVolume, smGetAudio


smGetBandPass
  short smGetBandPass(short nSM)
Returns current value of bandpass filter, an integer between 0 and 3. The default is OFF (0).
See also: smSetBandPass


smGetBrightness
  short smGetBrightness(short nSM)
Returns value of the brightness in effect, a integer between 0 and 63, with a default of 32. A value of 32 is neutral and means that no alteration is in effect.
See also: smSetBrightness


smGetChromaIntensity
  short smGetChromaIntensity(short nSM)
Returns value of the chroma intensity in effect, a float between -50 and 50, with a default of 0.
See also: smSetChromaIntensity, smGetChromaInvert

smGetChromaInvert
  short smGetChromaInvert(short nSM)
Returns YES(1) if input chroma values are being inverted. 
See also: smSetChromaInvert, smGetChromaIntensity


smGetColor
  short smGetColor(short nSM)
Returns YES(1) if color is enabled. Says nothing about whether a color source is connected or if a color image is actually displayed. Returns NO(0) if color is disabled.
See also: smSetColor


smGetContrast
  short smGetContrast(short nSM)
Returns value of the contrast in effect, a float between 0 and 63, with a default of 32. A value of 32 is neutral and means that no alteration is in effect.
See also: smSetContrast


smGetFlipDisplay
  short smGetFlipDisplay(short nSM)
Returns wether the current display is flipped(1) or not (0).
See also: smSetFlipDisplay


smGetHue
  short smGetHue(short nSM)
Returns the current value of hue in the range of 0 to 255 with a default of 0.
See also: smSetHue


smGetInput
  short smGetInput(short nSM)
Returns the currently active video input, one of 
 SM_INPUT_BLACK   = 0
 SM_INPUT_RED     = 1
 SM_INPUT_YELLOW  = 2
 SM_INPUT_SVHS    = 3
Also switches the according audio input.
See also: smSetInput


smGetInputFields
 short smGetInputFields(short nSM)
Returns number of active video fields.
 SM_FIELD_ODD   = 1
 SM_FIELD_EVEN  = 2
 SM_FIELD_BOTH  = 3
See also: smSetInputFields


smGetInputFilter
  short smGetInputFilter(short nSM)
Returns current value of input filter in the range of -1 to 3. A value of -1 means that automatic input filtering is enabled, a value of 0 that input filtering is disabled and anything above different levels of input filtering.
See also: smSetInputFilter


smGetLive
  short smGetLive(short nSM)
Turns video acquisition on or off. If smSetVideo is enabled, setting live to OFF(0) will freeze the live image on screen.
See also: smSetLive


smGetLumaIntensity
  short smGetLumaIntensity(short nSM)
Returns value of the luma intensity in effect, an integer between -50 and 50, with a default of 0.
See also: smSetLumaIntensity


smGetLumaInvert
  short smGetLumaInvert(short nSM)
Returns YES(1) if luma (brightness information) has been inverted, otherwise NO(0).
See also: smSetLumaInvert


smGetMixer
short smGetMixer(short nSM)
Returns YES(1) if mixer in the output stage is active, otherwise NO(0).
See also: smSetMixer


smGetNoiseFilter
  short smGetNoiseFilter(short nSM)
Returns current value of noise filter.
See also: smGetNoiseFilter


smGetPll
  short smGetPll(short nSM)
Returns value for phased locked loop of output mixer in the range of 0 to 1023. 
See also: smSetPll


smGetPosterize
  short smGetPosterize(short nSM)
Returns the value of the active posterize setting.
See also: smSetPosterize


smGetPreFilter
  short smGetPreFilter(short nSM)
Returns YES(1) if input is prefiltered, otherwise NO(0). 
See also: smGetPreFilter


smGetRGB
  short smGetRGB(short nSM, short *pnRed, short *pnGreen, short *pnBlue)
Returns value of the red, green and blue gain in effect, an integer between 0 and 63 with a default of 32. A value of 32 is neutral and means that no alteration is in effect. 
See also: smSetRGB


smGetSaturation
  short smGetSaturation(short nSM)
Returns value of the saturation in effect, an integer between 0 and 63 with a default of 32. A value of 32 is neutral and means that no alteration is in effect. 
See also: smSetSaturation


smGetSharpness
  short smGetSharpness(short nSM)
Returns current value of sharpness.
See also: smSetSharpness


smGetSystem
  short smGetSystem(short nSM)
Returns currently set system, one of:
 SM_SYSTEM_NTSC   = 0
 SM_SYSTEM_PAL    = 1
 SM_SYSTEM_SECAM  = 2
See also: smGetSystem


smGetVideo
  short smGetVideo(short nSM)
Return status of video overlay (ON/OFF).
See also: smSetVideo


smGetVideoFrame
  short smGetVideoFrame(short nSM, short *pnLft, short *pnTop, short *pnRgt, short *pnBot)
Returns the current active video frame.
See also: smSetVideoFrame, smGetWindowFrame, smGetZoomFrame


smGetVideoSource
  short smGetVideoSource(short nSM)
Returns status of time base correction. TBC is used for unstable video sources like camcorders.
See also: smSetVideoSource


smGetWindowFrame
  short smGetWindowFrame(short nSM, short *pnLft, short *pnTop, short *pnWdt, short *pnHgt)
Returns the currently active window frame.
See also: smSetVideoFrame, smSetWindowFrame, smGetZoomFrame


smGetXofs
  short smGetXofs(short nSM)
Returns current horizontal offset of Screen Machine II coordinate system to that of the graphics card.
See also: smSetXofs, smGetYofs


smGetYofs
  short smGetYofs(short nSM)
Returns current vertical offset of Screen Machine II coordinate system to that of the graphics card.
See also: smSetYofs, smGetXofs


smGetZoomFrame
  short smGetZoomFrame(short nSM, short *pnLft, short *pnTop, short *pnRgt, short *pnBot)
Returns active zoom frame.
See also: smSetZoomFrame, smGetVideoFrame, smGetWindowFrame


smInit
  short smInit(short nAdr, short nWdt, short nHgt)
nAdr:  I/O address of the Screen Machine II board
nWdt:  screen width in pixel
nHgt:  screen height in pixel
Initialize all Screen Machine II boards in the system. This has to be the first call. This sets the active Port I/O address of the Screen Machine IIs, so beware of any conflicts. nWdt and nHgt should be the graphics card currently active resolution. Returns the number of boards it has detected in the system (anywhere from 0 to 3). An init with nAdr=-1 uses the preset address from the system.


smOpen
  short smOpen(short nSM)
Opens/resets the Screen Machine II board with number nSM. This should be the first call if you want to send any further commands to a Screen Machine II. When you are done with the Screen Machine II use smClose to release it.
See also: smClose, smInit


smRemoveClip
  short smRemoveClip(short nSM,short clipnum)
Clears clip with number clipnum from screen.
See also: smSetClip, smClearClips, smSetClipList


smReadImage
  short smReadImage(short nSM, unsigned char* imagedata, int *size)
imagedata:
has to be a allocated region of memory in which the image will be placed. Unless the exact size is know before it is safe to pass 1 MB memory buffer. The region is filled with the image in the FLM file format, with YUV Mode 6 data.
size:
actual size of image in imagedata. (hint: convenient size for imagedata on successive reads with the same settings) 
Function to read an image out of the Screen Machine IIs memory and copy it into the specified buffer (imagedata) using the FLM format 6 (see Appendix for details). 
Example:
   FILE             *fp;
   int              imagesize;
   unsigned char    *imagebuffer;

   fp = fopen("test.flm","w");
   imagedata = malloc(1024*1024);
   smReadImage(0,imagedata,&imagesize);
    if(imagesize)
	{
       fwrite(imagedata,imagesize,1,fp);
    }
    fclose(fp);
   free(imagedata);
See also: smWriteImage


smSetAudio
  short smSetAudio(short nSM,short bOn)
Default:  0       OFF
bOn:      0,1
Turns audio ON or OFF.
See also: smGetAudio, smSetAudioVolume


smSetAudioBalance
  short smSetAudioBalance(short nSM, short nVal)
Default:      0
nVal:     -50...50    (left....right)
Sets balance of audio to nVal. Range is from -50 to 50, with 0 being equal volume at left and right, -50 results in the right muted, and 50 in the left muted.
See also: smGetAudioBalance, smSetAudioFader


smSetAudioBass
  short smSetAudioBass(short nSM, short nVal)
Default:      0
nVal:     -50...50    (min....max)
Sets bass of audio to nVal. Range is from -50 to 50, with 0 being neutral. Values <0 results in less bass and values >0 in increased bass in the output audio.
See also: smGetAudioBass, smSetAudioTreble


smSetAudioFader
  short smSetAudioFader(short nSM, short nVal)
Default:      0
nVal:     -50...50    (rear....front)
Sets audio fader (balance between front and rear outputs) to nVal. Range is -50 to 50 with 0 being neutral (equal distribution between front and back). 50 is all to the front, and -50 all to the rear output.
See also: smGetAudioFader, smSetAudioBalance


smSetAudioInput
  short smSetAudioInput(short nSM, short nInput)
Default:   0
nInput:    0,1,2
Set audio input to be active to nInput. The TV-tuner option has audio always on input 2.
See also: smGetAudioInput


smSetAudioTreble
  short smSetAudioTreble(short nSM, short nVal)
Default:     0
nVal:    -50...50    (min....max)
Sets treble of audio to nVal. Range is from -50 to 50, with 0 being neutral. Values <0 results in less treble and values >0 in increased treble in the output audio.
See also: smGetAudioTreble, smSetAudioBass


smSetAudioVolume
  short smSetAudioVolume(short nSM, short nVal)
Default:     50
nVal:      0...100   (off....max)
Sets audio volume to nVal. Linear scaling is used.
See also: smGetAudioVolume, smSetAudio


smSetBandPass
  short smSetBandPass(short nSM, short nBandpass)
Default:       0
nBandpass:   0...3
Sets value of bandpass filter to nBandpass. 0 turns bandpass filtering OFF.
See also: smGetBandPass


smSetBrightness
  short smSetBrightness(short nSM, short nBrightness)
Default:         32
nBrightness:   0...63
Sets brightness of output image according to nBrightness. A smaller value means a darker picture and a larger a lighter picture. Has no effect on the image in memory.
See also: smGetBrightness


smSetChromaIntensity
  short smSetChromaIntensity(short nSM, short nInt)
Default:     0
nInt:    -50...50
Sets the chroma intensity of the input decoder to nInt. A higher value means a more saturated representation, and a lower a colorless/grayscale representation. Belongs to the set of controls affecting the input stage and hence how the image is digitized into memory.
See also: smGetChromaIntensity, smSetChromaInvert


smSetChromaInvert
  short smSetChromaInvert(short nSM, short bOn)
Default:  0    normal
bOn:     0,1
If state is YES(1), the chroma values of the input will be inverted. Affects the image stored in memory. If state is NO(0), the input remains unaltered.
See also: smGetChromaInvert, smSetChromaIntensity


smSetClip
  short smSetClip(short nSM, SMClip theRect)
theRect:
(short)left,(short)right,(short)top,(short)bottom,(short)clipnum,(short)state
clipnum:    0...63
left,righ:  0...max screen resolution
Sets clip number clipnum to size specified by left, right, top, bottom. The state is currently be ignored.
See also: smRemoveClip, smClearClips, smSetClipList


smSetClipList
  short smSetClipList(short nSM, SMClips theClips, int count)
SMClip:
(short)left,(short)right,(short)top,(short)bottom,(short)clipnum,(short)state
left,right:  0...max screen resolution
theClips:    array of SMClips
count:       count of clips in array (0...63)
Most efficient way to manipulate the internal clip list when it is required to do more than one operation. A clip is defined as a region on the screen where the video overlay will be disabled. It is primarily used to allow windows to be placed ontop of the video overlay in a multi window environment. The Screen Machine II can handle up to SM_CLIPLIST_LEN (currently 64) clips.
A SMClip is an array of 6 values describing the location, number and operation of the clip. Location and size are in screen coordinates.
Number SM_CLIP_NUM is between 0 and SM_CLIPLIST_LEN-1
Operation or state CLIP_STATE are ignored in the moment:
SM_REMOVE_CLIP  (clip is not active)
SM_SET_CLIP     (clip is active)
Example:
   SMClip   clipList[4];
   /* Sets 4 Clips from the to left to the bottom right of the screen */
   /* Each 1/4 the width an height of the screen */
   /* swdt and shgt are assumed to be the screen width and height */
   for(i=0;i<4;i++)
   {
        clipList[i][CLIP_LEFT] = (swdt / 4) * i;
        clipList[i][CLIP_TOP] = ((shgt / 4) * i);
        clipList[i][CLIP_RIGHT] = (swdt / 4) * (i+1);
        clipList[i][CLIP_BOTTOM] = ((shgt / 4) * (i+1));
        clipList[i][CLIP_NUM] = i;
        clipList[i][CLIP_STATE] = SM_SET_CLIP;
   }
See also: smClearClips, smRemoveClip, smSetClip


smSetColor
  short smSetColor(short nSM, short bOn)
Default:   1
bOn:      0,1
If state is YES(1), the chroma of the live video is enabled. For a color picture to appear, a color source has to be connected, the correct system has to be set, and the quality controls have to be set accordingly. (Notably the chroma intensity and saturation.) Another reason for a lack of color is if the black input is selected with a SVHS source connected. If state is NO(0), color is disabled. The video can be color regardless of the current WindowServer depth, as long as a color monitor is connected.
See also: smGetColor


smSetContrast
  short smSetContrast(short nSM, short nContrast)
Default:       32
nContrast:   0...63
Sets contrast of output image according to nContrast. The range is from 0 to 63, with 32 being neutral. A smaller value reduces the contrast and a larger a higher contrast of the picture. Has no affect on the image in memory.
See also: smGetContrast


smSetFlipDisplay
  short smSetFlipDisplay(short nSM, short bOn)
Default:   0
bOn:      0,1
Inverts the vertical image axis, resulting in a upside down video image.
See also: smGetFlipDisplay


smSetHue
  short smSetHue(short nSM, short nHue)
Default:    0
nHue:     0...255
Sets hue of output image according to nHue. The range is from 0 to 255, with 0 being neutral. 0 corresponds to 0 deg change and 255 a 360 deg change in the color angle.
See also: smGetHue


smSetInput
  short smSetInput(short nSM, short nInput)
Default:   0	
nInput:    0   black input (composite signal)
           1   red input (composite signal)
           2   yellow input (composite signal)
           3   S-VHS (red input = chroma, black input = luma)
Sets active video input.
See also: smGetInput


smSetInputFields
  short smSetInputFields(short nSM, short nFrm)
Default:   2	
nFrm:      0  even fields
           1  odd fields
           2  odd & even fields
Sets input frame type to nFrm. With the input frame, one can select if the image is generated only for the odd or even fields, or from both fields. Both fields result in a better image resolution, but, on images with a lot of movement, it leads to stripes in the image caused by movement in the image between fields. For pictures with fast movement, one should select odd or even fields.
See also: smGetInputFields


smSetInputFilter
  short smSetInputFilter(short nSM, short nFlt)
Default:   -1
nFLT:   -1...3
           -1   automatic
            0   off
Sets value of input filter to nFlt. Range is from -1 to 3, where -1 is the default. A value of -1 turns automatic input filtering ON.
See also: smGetInputFilter


smSetLive
  short smSetLive(short nSM, short bOn)
Default:  1
bOn:     0,1
Freezes the actual live video. Once digitized into the memory you cant change values like size or resolution. Even any function affecting the input stage of the Screen Machine II has no more effect on that image.
See also: smGetLive


smSetLumaIntensity
  short smSetLumaIntensity(short nSM, short nInt)
Default:     0
nInt:    -50...50
Sets the luma intensity of the input decoder to nInt. A higher value means a brighter representation and a lower a darker a representation. Belongs to the set of controls affecting the input stage and hence how the image is digitized into memory.
See also: smGetLumaIntensity


smSetLumaInvert
  short smSetLumaInvert(short nSM, short bOn)
Default:    0    normal
bOn:       0,1
If bOn is YES(1), the luma values of the input will be inverted. Affects the image in memory of the Screen Machine II. If bOn is NO(0), the input values will remain unchanged.
See also: smGetLumaInvert


smSetMixer
  short smSetMixer(short nSM, short bOn)
Default:   1
bOn:      0,1
If state is bOn the mixer of the output stage will be active, resulting in the data from the graphics card being mixed with the data from the live video. Live video will be displayed where the graphics are black, and no live video where the graphics are white. Useful if graphics should be visible without clipping. If bOn is set to NO(0), the live video data takes precedence, meaning that the graphics data is discarded at the corresponding coordinates. Useful if the video should cover the graphics, without having to change window order. 
See also: smGetMixer


smSetNoiseFilter
  short smSetNoiseFilter(short nSM, short nNoiseFilter)
Default:         0
nNoiseFilter:  0...3
Sets value of input noise filter to nNoiseFilter. 
See also: smGetNoiseFilter


smSetPll
short smSetPll(short nSM, short nPll)
Default:	796
nPll:	0...1023
Sets the phased locked loop of the SM to nPll. Valid range is from 0-1023. Realistic values range from 500-800. This value controls the width and horizontal scale of the live video picture. It acts solely on the output stage of the SM, it has no effect on the digitized images. Setting to extreme values can cause the picture to collapse (just stripes of distorted video on screen). On a system with a resolution above 800x600 the horizontal scale of the input has to be halved by setting setHScale to YES(1), to achieve the correct aspect ratio of the live video on screen.
See also: smGetPll


smSetPosterize
  short smSetPosterize(short nSM, short nVal)
Default:   1     True Color, 24 Bit
nVal:    0...16
Reduces number of colors in steps of 16 (internally).
See also: smGetPosterize


smSetPreFilter
  short smSetPreFilter(short nSM, short nPrefilter)
Default:      1
nPrefilter:  0,1
If nPrefilter is YES(1), the input source is prefiltered, otherwise NO(0).
See also: smGetPreFilter


smSetRGB
  short smSetRGB(short nSM, short nRed, short nGreen, short nBlue)
Default:    32
Values:   0...63
Changes the output image red, green and blue component according to values. A smaller value means less color and a larger more color in the picture. Has no effect on the image in memory of the Screen Machine.
See also: smGetRGB


smSetSaturation
  short smSetSaturation(short nSM, short nSaturation)
Default:        32
nSaturation:  0...63
Sets saturation of output image according to nSaturation. A smaller value means a less saturated and a larger a more saturated picture. Has no affect on the image in memory.
See also: smGetSaturation


smSetSharpness
  short smSetSharpness(short nSM, short nSharpness)
Default:       0
nSharpness:  0...3
Sets sharpness of output image according to nSharpness. A smaller value reduces the sharpness and a larger increases the sharpness of the picture. Has no affect on the image in memory.
See also: smGetSharpness


smSetSystem
  short smSetSystem(short nSM, short nSystem)
Default:   1  PAL
nSystem:   0  NTSC
           1  PAL
           2  SECAM
Sets system of input decoder to nSystem. This also affects the current video frame, which is reset to the maximum resolution according to the system. These values are 756x567 for PAL and SECAM and 640x480 for NTSC.
See also: smGetSystem,smSetVideoFrame,smGetVideoFrame


smSetVideo
short smSetVideo(short nSM, short bOn)
Default:   0
bOn:      0,1
Sets the live overlays status. If set to ON(1) the video will become visible on screen, provided that the overlay is adjusted correctly and that a video source is connected to the active input. If turned OFF (0) the video image is still written into the Screen Machine II memory, images can be acquired using the smReadImage call. To disable video acquisition use the setLive call.
See also: smGetVideo


smSetVideoFrame
  short smSetVideoFrame(short nSM, short nLft, short nTop, short nRgt, short nBot)
Origin:    0,0  upper left corner
Defaults:
PAL,       nLft =  19
SECAM      nTop =  21
           nWdt = 736
           nHgt = 552
NTSC:      nLft =   5
           nTop =  11
           nWdt = 640
           nHgt = 480
Set the video frame to the rectangle values. The video frame is the size and position at which the video image from the input decoder gets transferred into memory. The offset is usually set to skip invalid or noisy data at the beginning of a field. (0,0 = upper left)
See also: smGetVideoFrame, smSetWindowFrame, smSetZoomFrame


smSetVideoSource
  short smSetVideoSource(short nSM, short nMode)
Default:   1	
nMode:    0,1  OFF/ON
If nMode is YES(1), Time Base Correction is applied. Useful if mechanical video sources like video recorders are connected. If nMode is NO(0), Time Base Correction is disabled.
See also: smGetVideoSource


smSetWindowFrame
  short smSetWindowFrame(short nSM, short nLft, short nTop, short nRgt,short nBot)
Origin:   0,0      upper left corner
Default:   ?       depends on current screen resolution
Example: 0,0,1023,0,767  (full screen)
Sets window frame to rectangle values. The window frame is the size and position of the live video image on screen. The minimum size is 16x1, maximum size is the current screen size. The window frame affects the size of the image in memory if it is smaller than the video frame.
See also: smGetWindowFrame, smSetZoomFrame, smSetVideoFrame


smSetXofs
  short smSetXofs(short nSM, short nXOffset)
Default:      75
nXOffset:   0...255
Sets the horizontal offset of the Screen Machine II coordinate system to the coordinate system of the graphics card. This is uses for adjusting the overlay to the graphics card.
See also: smGetXofs, smSetYofs


smSetYofs
  short smSetYofs(short nSM, short nYOffset)
Default:      33
nYOffset:   0...255
Sets the vertical offset of the Screen Machine II coordinate system to the coordinate system of the graphics card. This is uses for adjusting the overlay to the graphics card.
See also: smGetYofs, smSetXofs


smSetZoomFrame
  short smSetZoomFrame(short nSM, short nLft, short nTop, short nRgt, short nBot)
default:  0,0,0,100,100
Range:    0...100       in %
Sets zoom frame to rectangle values. The zoom frame is the portion of the video in memory of the Screen Machine II that is displayed on screen in the currently active video frame. The zoom frame is specified in percent from 0 to 100, and therefore independent of the current window and video frame.
     i.e. nLft = 25  nTop = 25  nRgt = 75 nHgt = 75
See also: smGetZoomFrame, smSetVideoFrame, smSetWindowFrame


smWriteImage
  short smWriteImage(short nSM, unsigned char* imagedata, int size)
imagedata
has to be a allocated region of memory in which the image has been placed. The image data has to be in the FLM format with YUV Mode 6 data
size
actual size of the image in imagedata (dont forget 64 byte FLM header, see Appendix). 
Example:	
     if((fp = fopen("test.flm","r")))    /* Open file */
     {
       if(!fread(buf,64,1,fp))           /* Read in FLM Header */
       {
          fclose(fp);
          break;
       }
       width = (buf[10]+(buf[11]<<8));   /* Decode width & height */
       height = (buf[12]+(buf[13]<<8));
       imagesize = width*height*2+64;	
       /* Calculate image size (Assumes Mode 6 2Bytes per Pixel) */
       /* Have to take the 64 byte FLM header into account */
       imagedata = malloc(imagesize);    /* Allocate the buffer */
       bcopy(buf,imagedata,64);          /* Copy Header into buffer */
       /* Read image data */
       if(!fread(imagedata+64, imagesize-64, 1, fp))
       {
          fclose(fp);
          break;
       }
       fclose(fp);                       /* Close file */
       /* Write image into Screen Machine II */
       smWriteImage(sm,imagedata, imagesize);	
       free(imagedata);                  /* Free buffer */
     }
See also: smReadImage




TV-TUNER OPTION
===============

AFC Tables
==========

smAFC_ChannelNameForFreq
  char* smAFC_ChannelNameForFreq(SMAFCTable *table, int aFreq)
Returns the channel Descriptor for the frequency aFreq. If there is no known channel at the frequency aFreq, "?" is returned. The search range for this function is 13 MHz. The frequency has to be in a range from 4825 to 85525 (48.25 - 855.25 MHz).
See also: smAFC_ChannelNameForVal()


smAFC_ChannelNameForVal
  char* smAFC_ChannelNameForVal(SMAFCTable *table, int aVal)
Returns the channel Descriptor for the table entry aVal. If aVal is not in the table "" is returned.
See also: smAFC_ChannelNameForFreq()


smAFC_Count
  unsigned int smAFC_Count(SMAFCTable *table)
Returns the number of entries in the AFC-Table. The first entry is number 0.
See also: smAFC_InitTableFromFile()



smAFC_FreqForVal
  int smAFC_FreqForVal(SMAFCTable *table, int aVal)
Return the frequency of table entry aVal. If aVal is not in the table -1 is returned.
See also: smAFC_NextValForFreq()


smAFC_InitTableFromFile
  short smAFC_InitTableFromFile(SMAFCTable *table, const char* filename)
This function is the designated initializer for the struct SMAFCTable table. filename has to be the full path to an AFC-Table file. If the file can't be read or does not contain valid entries, 0 is returned. If successfull a 1 is returned.
See also: smSetAFCTable(), smSetAFCTableWithPreset()


smAFC_NextValForFreq
  int smAFC_NextValForFreq(SMAFCTable *table, int aFreq)
Returns the next table entry whose frequency is larger than aFreq. If no larger frequency was found 0 is returned.
See also: smAFC_FreqForVal()


smAFC_TableName
  char* smAFC_TableName(SMAFCTable *table)
Returns the name of the AFC-Table stored in the AFC-Table table.
See also: smAFC_InitTableFromFile()


TUNER PART
==========

smAfcSearch
  int smAfcSearch(short nSM, SMTVControl* control, int frequenz, int system , int norm)
Searches the next valid TV channel on all AFC-frequencies starting at frequenz with system system and norm norm. The frequency has to be in a range from 4825 to 85525 (48.25 - 855.25 MHz). For values of system see smGetSystem() (smLib), for values of norm see smNorm(). If no error occurred the found frequency is returned, otherwise the error is returned. For a further description of all errors see Errors at the end of this chapter. Before using this function an AFC-table has to be set. In every non-error case the returned frequency is set.
See also: smSetAFCTable(), smSetAFCTableWithPreset(), smSearch()


smFrequency
 int smFrequency(short nSM, SMTVControl* control)
Returns the currently set frequency of the TV-Tuner. The frequency is in a range from 4825 to 85525 (48.25 - 855.25 MHz).
See also: smProgFrequency(), smSetChannel()


smInitTuner
  short smInitTuner(short nSM, SMTVControl* control)
Initializes the tuner and sets control to a frequency of 48.25 MHz and a norm of SMTV_NORM_BG and returns on success 1. Before using smAfcSearch() you have to set a AFC-Table with the smSetAFCTable function. On error 0 is returned
See also: smIsTunerConnected()


smIsTunerConnected
  short smIsTunerConnected(short nSM)
Returns 1 if a TV-Tuner is connected to nSM. Otherwise 0 is returned.
See also: smInitTuner()


smNextProgFor
  short smNextProgFor(short nSM, SMTVControl* control, int aProg, short aBool)
Returns the next/previous (aBool equals 1/0) visible channel starting at aProg. If no channel is set visible, or aProg is the only visible channel, aProg is returned. In case of overflow (larger 99/lower 0), the search starts over at the beginning/end of the program table.
See also: smSetVisible(), smProgVisible()


smNorm
  short smNorm(short nSM, SMTVControl* control)
Returns the currently set norm of the TV-Tuner. Possible return values (depending on the type of the TV-Tuner) are :
  SMTV_NORM_M     M
  SMTV_NORM_BG    B/G
  SMTV_NORM_L     L
  SMTV_NORM_Li    L'
  SMTV_NORM_I     I
The norm of a TV system describes the frequency distance between picture and sound carrier. Using wrong norms will result in no sound with a good video picture or good sound with no picture. If your not sure about the standard or the norm used in your country ask your local television/radio dealer or simply experiment until the correct one is found.
See also: smProgNorm(), smSetChannel()


smProgFrequency
  int smProgFrequency(short nSM, SMTVControl* control, int prognr)
Returns the frequency of the stored channel prognr. The frequency is in a range from 4825 to 85525 (48.25 - 855.25 MHz). A return value of -1 means that no frequency is currently set for prognr. All other negative return values indicate that an error occurred. For a further description of all errors see Errors at the end of this chapter.
See also: smStoreProg(), smFrequency()


smProgName
  char* smProgName(short nSM, SMTVControl* control, int prognr)
Returns the name of the stored channel prognr. The name can contain a maximum count of 5 characters. If no name is currently set for prognr an empty string is returned. On error NULL is returned.
See also: smStoreProgWithName()


smProgNorm
  short smProgNorm(short nSM, SMTVControl* control, int prognr)
Returns the norm of the stored channel prognr. For the possible return values see smNorm(). A return value of -1 means that no norm is currently set for prognr. All other negative return values indicate that an error occurred. For a further description of all errors see Errors at the end of this chapter.
See also: smStoreProg(), smNorm()


smProgSystem
  short smProgSystem(short nSM, SMTVControl* control, int prognr)
Returns the system of the stored channel prognr. For the possible return values see smGetSystem() (smLib). A return value of -1 means that no system is currently set for prognr. All other negative return values indicate that an error occurred. For a further description of all errors see Errors at the end of this chapter.
See also: smStoreProg(), smGetSystem() (smLib)


smProgVisible
  short smProgVisible(short nSM, SMTVControl* control, int prognr)
Returns 1 if the stored channel prognr is set to visible. You needn't to use this function when switching channels with the smNextProgFor() function. By default (channel prognr hasn't been already stored) 0 is returned.
See also: smSetVisible(), smStoreProg()


smReadProgs
  short smReadProgs(short nSM, SMTVControl* control, char* dateiname)
Reads an already stored program table from harddisc. dateiname should contain the complete filename of the program table you want to read. If dateiname is an empty string (""), or could not be read from harddisc, this function tries to open the file '.stations' in the users home directory. A return value of 0 means that an error occurred and no table was read.
See also: smWriteProgs(), smStoreProg()


smSearch
  int smSearch(short nSM, SMTVControl* control, int frequenz, int system , int norm)
Searches the next valid TV channel starting at frequenz with system system and norm norm. The frequency has to be in a range from 4825 to 85525 (48.25 - 855.25 MHz). For values of system see smGetSystem() (smLib), for values of norm see smNorm(). If no error occurred the found frequency is returned, otherwise the error is returned. For a further description of all errors see Errors at the end of this chapter. If the returned frequency equals frequenz, is larger than frequenz plus deltafrequenz (smSetSearch()),or is larger than 85525, no valid channel has been found. In every non-error case the returned frequency is set.
Note : This call does not start over at the beginning of the frequency spectrum. You have to do so by your own.
In comparison to smAfcSearch(),this is a distinctly slower function to find valid TV channels because all frequencies are scanned. You should only use this function if you don't have an AFC-table for your country or if the channels your searching for are not based on the AFC-frequencies of your country.
Warning : This function can't be interrupted and it could take quite a long time to scan all frequencies.
See also: smSetSearch(), smAfcSearch()


smSetAFCTable
  void smSetAFCTable(short nSM, SMTVControl* control, SMAFCTable *aTable)
Sets an AFC-table used for the smAfcSearch() function. aTable has to be a set struct of SMAFCTable type. You shouldn't free aTable before finishing your work with the tuner.
See also: smAfcSearch(), smSetAFCTableWithPreset(), smAFC_InitTableFromFile()


smSetAFCTableWithPreset
  void smSetAFCTableWithPreset(short nSM, SMTVControl* control, SMAFCTable *aTable, int aNorm, int aSystem)
Sets an AFC-table used for the smAfcSearch() function. aTable has to be a set struct of SMAFCTable type. In comparison to the function above, this function presets the program table with the values found in the AFC-table. In the AFC-table there is no information concerning the standard or the norm to use. The norm norm and system system will be set for all available frequencies. The available frequencies are set to visible. You shouldn't free aTable before finishing your work with the tuner.
Warning : Only use this function before making changes to the program table. All values of the program table may be destroyed.
See also: smAfcSearch(), smSetAFCTable(), smSetVisible(), smAFC_InitTableFromFile()


smSetChannel
  short smSetChannel(short nSM, SMTVControl* control, int frequenz, int system, int norm)
With this function you can set the frequenz (frequency), the system and the norm directly. The frequency has to be in a range from 4825 to 85525 (48.25 - 855.25 MHz). For values of system see tem() (smLib), for values of norm see smNorm. If no error occurred SMTV_OK is returned, otherwise the error is returned. For a further description of all errors see Errors at the end of this chapter.
See also: smFrequency(), smNorm(), smGetSystem() (smLib)


smSetMonoStereo
  short smSetMonoStereo(short nSM, SMTVControl* control, int monster)
Sets the stereo chip on the TV-Tuner board. This option is not available for all boards. Possible values for monster are :
  SMTV_MONO         Sets to mono sound
  SMTV_STEREO       Sets to stereo sound if possible
  SMTV_A_CHANNEL    Sets to left channel
                    (only possible if twochannel is detected)
  SMTV_B_CHANNEL    Sets to left channel
                    (only possible if twochannel is detected).
On success SMTV_OK else an error is returned. For a further description of all errors see Errors at the end of this chapter.
See also: smStatusAudio()


smSetProg
  short smSetProg(short nSM, SMTVControl* control, int prognr)
Sets the channel that is stored in the program table at position prognr. Be aware that not only the frequency but also the currently set system and norm may change.  If no error occurred SMTV_OK otherwise the error is returned. For a further description of all errors see Errors at the end of this chapter.
See also: smProgFrequency(), smProgNorm(), smProgSystem(), smProgName(), smReadProgs(), smWriteProgs(), smStoreProg()


smSetSearch
  short smSetSearch(short nSM, SMTVControl* control, int deltafrequenz, int breite, int gewichtung)
This call sets the limit and the adjustments for the smSearch() function. The default values for breite and gewichtung (see below) are experienced for german television channels and may not work in your country. You needn't to set values for using smSearch() the first time.
deltafrequenz has a range from 0 to 80000 (default 80000 relates to 800MHz) and describes range of frequency in which should be searched for a valid channel. Keep in mind that a valid channel could only be detected properly if you scan all over to the end of this channel. The best picture quality of a channel you get somewhere in between his visible start and end frequency (see also breite and gewichtung). Use a value of 0 to set to the default.
breite is the minimum range of frequency (in MHz * 100) a channel is detected as a valid TV channel. If you set this minimum to low (default is 150 equals 1.5MHz) you may detect frequencies where you 'can't find' a real TV channel. Use a value of 0 to set to the default.
gewichtung is a percentage value between 0 and 100 (default 75) and represents the frequency that is set and returned by smSearch() in between the found visible start and end frequency. So a value of 100 means use the frequency at the end of the found channel range. Use a value of 0 to set to the default.
Example: The smSearch() function detects a valid TV signal between 50000 and 50200 (500 - 502 MHz). Your start frequency was 45000 (450 MHz) and your deltafrequenz has been set to 10000 (100 MHz). So the end of your range hasn't been reached. The width of the channel (breite) is larger then 150 (50200 - 50000 = 200) what means that a valid channel is detected. Because of the weight (gewichtung) of 75 a frequency of  50150 (501.5MHz) is set and returned.
In case of error the error is returned (For a further description of all errors see Errors at the end of this chapter) otherwise SMTV_OK.
See also: smSearch()


smSetVisible
  short smSetVisible(short nSM, SMTVControl* control, short aBool, int prognr)
If aBool is 1, sets the stored channel prognr visible. This function gives you the opportunity to decide wether a stored channel should be switched to when using the smNextProgFor() function. In case of error the error is returned (For a further description of all errors see Errors at the end of this chapter) otherwise SMTV_OK.
See also: smNextProgFor(), smStoreProg(), smProgVisible()


smStatusAudio
  short smStatusAudio(short nSM, SMTVControl* control)
Returns the status of the stereo chip. A negative return value means that an error occurred. For a further description of all errors see Errors at the end of this chapter. Possible non negative return values are :
  SMTV_MONO        mono sound signal detected.
  SMTV_STEREO      stereo sound signal detected.
  SMTV_TWOCHANNEL  two channel sound signal detected.
  SMTV_NOIDENT     the signal couldn't be detected properly.
It takes the stereo chip a maximum time of about half a second after changing frequency to detect a proper audio signal. If waiting less time this function can return a wrong value (in the most cases not SMTV_NOIDENT).
See also: smSetMonoStereo()


smStatusTV
  short smStatusTV(short nSM, SMTVControl* control)
Returns the status of the TV-Tuner. If a valid TV channel frequency is already set a fine tuning can be done with help of this function. The lower three bits of the return value indicate :
  < 2     Set frequency is to high.
  = 2     Set frequency is ok.
  > 2     Set frequency is to low.
You needn't to use this function after using the search functions described above in this chapter. The search functions already do so. This function may be only useful to you if you develop your own search algorithm.
See also: smStatusVT()


smStatusVT
  short smStatusVT(short nSM, SMTVControl* control)
Returns the status of the VideoText chip. A set Bit 0 (SMTV_TV_QUALITY_BIT) indicates that on the current frequency is a video signal with a sync. That means that this frequency has a valid picture information. A set Bit 1 (SMTV_VT_QUALITY_BIT) indicates a valid Video Text signal. Video Text is not available in the most countries. Even if your TV-Tuner hasn't got a Video Text Chip on board you can use this function to determinate the quality of the currently set frequency.
You needn't to use this function after using the search functions described above in this chapter. The search functions already do so. This function may be only useful to you if you develop your own search algorithm.
See also: smStatusTV()


smStoreProg
  short smStoreProg(short nSM, SMTVControl* control, int prognr, int frequenz, int system, int norm)
Stores the frequency frequenz the system system and the norm norm in the program table at position prognr. Positions from 0 to 99 are available. The range of the other parameters are described in the functions mentioned below (see also). Like the function smSetVisible() this function sets the position prognr to visible.
In case of error the error is returned (For a further description of all errors see Errors at the end of this chapter) otherwise SMTV_OK.
Note : Storage of a program channel means only to store it into the memory of the computer. If you want to store the program table to harddisc you have to use smWriteProgs() even if you loaded your table with the smReadProgs() function.
See also: smStoreProgWithName(), smProgFrequency(), smProgNorm(), smProgSystem()


smStoreProgWithName
  short smStoreProgWithName(short nSM, SMTVControl* control, int prognr, int frequenz, int system, int norm,char* aName)
Stores the frequency frequenz the system system the norm norm and the name aName in the program table at position prognr. Positions from 0 to 99 are available. aName should only be a short form of the channel name because only the first 5 characters are taken for storage. The range of the other parameters are described in the functions mentioned below (see also). Like the function smSetVisible() this function sets the position prognr to visible.
In case of error the error is returned (For a further description of all errors see Errors at the end of this chapter) otherwise SMTV_OK.
Note : Storage of a program channel means only to store it into the memory of the computer. If you want to store the program table to harddisc you have to use smWriteProgs() even if you loaded your table with the smReadProgs() function.
See also: smStoreProg(), smProgFrequency(), smProgNorm(), smProgSystem(), smProgName()


smTunerType
  short smTunerType(short nSM, SMTVControl* control)
Returns the type of the tuner. The different tuner types differ on the norm they support. Currently two types of tuners are available :
  SMTV_GR_MODUL   Supported norms : M, B/G, L
  SMTV_UK_MODUL   Supported norms : B/G, L, L', I
For a further description of norm see smNorm(). All the tuner that are used for ScreenMachine are multinorm tuner. That means that they all support NTSC, PAL and SECAM systems. The tuner used for MovieMachine are singlenorm tuner. They either support PAL or NTSC. SECAM isn't supported at all (for now).
See also: smIsTunerConnected()


smWriteProgs
  short smWriteProgs(short nSM, SMTVControl* control,char* dateiname)
Writes an already stored program table from memory to harddisc. dateiname should contain the complete filename of the program table you want to write. If dateiname is an empty string ("") this functions tries to write the file '.stations' in the users home directory. A return value of 0 means that an error occurred and no table was written.
You needn't to save every change of your program table to harddisc. Usually it is enough to save the program table when quitting your application.
See also: smReadProgs(), smStoreProg()


Tuner Errors :
==============

 SMTV_OK                 No Error occurred.
 SMTV_ERROR              General Error
 SMTV_I2CERROR           Bus Error (try again, check cables and connections)
 SMTV_FREQUENCYERROR     Wrong frequency range
 SMTV_SYSTEMERROR        Wrong system value
 SMTV_NORMERROR          Wrong norm value
 SMTV_PROGRAMERROR       Wrong program channel number given
 SMTV_WEIGHTERROR        Wrong value for weight
 SMTV_MONOSTEREOERROR    Wrong value for the stereo chip given



