


IMVFBROTATE(1IM)           IMAGE TOOLS           IMVFBROTATE(1IM)



NAME
     imvfbrotate  -  rotate an image

SYNOPSIS
     #include "im.h"

     ImVfb *ImVfbRotate( srcVfb, degree, dstVfb )
             ImVfb   *srcVfb;
             float    degree;
             ImVfb   *dstVfb;


DESCRIPTION
     ImVfbRotate rotates the _s_r_c_V_f_b about an axis  orthogonal  to
     the  image  plane and positioned at the center of the image.
     The resulting rotated image is returned in _d_s_t_V_f_b, a pointer
     to which is returned as the function value.

     The image  rotation  angle  _d_e_g_r_e_e  is  measured  using  the
     right-hand  rule:  positive angles rotate counter-clockwise,
     while negative angles rotate clockwise.

     If _d_s_t_V_f_b is IMVFBNEW a new destination VFB will be automat-
     ically  allocated  with  the proper size, the same fields as
     _s_r_c_V_f_b, and initialized to zeroes in all fields.  A  pointer
     to the new _d_s_t_V_f_b is returned by ImVfbRotate.

     If _d_s_t_V_f_b is not IMVFBNEW, the VFB must have  at  least  the
     same  fields  as _s_r_c_V_f_b and must be large enough to hold the
     rotated image.  Rotation VFB sizes  may  be  computed  based
     upon the rotation angle using:
          Width = fabs( sin(_d_e_g_r_e_e) * ImVfbQHeight(_s_r_c_V_f_b)) +
               fabs( cos(_d_e_g_r_e_e) * ImVfbQWidth(_s_r_c_V_f_b))

          Height = fabs( sin(_d_e_g_r_e_e) * ImVfbQWidth(_s_r_c_V_f_b)) +
               fabs( cos(_d_e_g_r_e_e) * ImVfbQHeight(_s_r_c_V_f_b))

     _d_s_t_V_f_b contents will be overwritten  by  those  pixels  from
     _s_r_c_V_f_b that constitute the rotated image.  Pixels outside of
     the image (four corner  triangles)  will  be  unmodified  in
     _d_s_t_V_f_b.

NOTES
     Providing a _d_s_t_V_f_b  to  ImVfbRotate  is  appropriate  for  a
     variety  of  effects.   In the simplest case, the _d_s_t_V_f_b may
     contain a background color that matches  the  background  of
     the  _s_r_c_V_f_b.   When  rotated, the _s_r_c_V_f_b's pixels will blend
     seamlessly into the  _d_s_t_V_f_b  background  rather  than  leave
     empty black triangular corners.

     In a more complex use of a _d_s_t_V_f_b, the _d_s_t_V_f_b may be intial-
     ized  to  a  transparent  alpha  channel value.  The _s_r_c_V_f_b,



SDSC             Last change: November 24, 1992                 1






IMVFBROTATE(1IM)           IMAGE TOOLS           IMVFBROTATE(1IM)



     complete with its own  variety  of  transparent  and  opaque
     alpha  values,  will  be  rotated  and placed into the tran-
     sparent background of _d_s_t_V_f_b.  The combination can  then  be
     used with ImVfbComp to digitally composite the rotated image
     atop another image.

     Finally, a _d_s_t_V_f_b could contain a complete image atop  which
     the  rotated  image  is  to be placed.  This is usually less
     satisfying that using  an  alpha-channel  based  compositing
     approach  because the entire rectangle of the rotated _s_r_c_V_f_b
     will be pasted atop the _d_s_t_V_f_b, leaving you a rotated  image
     with _d_s_t_V_f_b only showing through in the corners.

     _s_r_c_V_f_b is unaltered by this operation.

RETURNS
     Upon success, ImVfbRotate returns a pointer to the  destina-
     tion  VFB.  Upon failure, IMVFBNULL is returned, and ImErrNo
     set to one of the following:

          IMEFIELD    _s_r_c_V_f_b and dstVfb fields aren't compatible
          IMEHEIGHT   Height not the right size for the resulting shear
          IMEMALLOC   Cannot allocate enough memory for the new VFB
          IMENOVFB    NULL _s_r_c_V_f_b
          IMEWIDTH    Width  not the right size for the resulting shear

SEE ALSO
     ImIntro    (3IM),     ImErrNo     (3IM),     ImVfbComp(3IM),
     ImVfbXShear(3IM), ImVfbYShear(3IM)

AUTHOR
     Dave Nadeau
     San Diego Supercomputer Center

CONTACT
     SDSC consultants, (619)534-5100, consult@y1.sdsc.edu



















2                Last change: November 24, 1992              SDSC



